Flywheel Connector Protocol (FCP)

Specification note: FCP_Specification_V3.md is the current architectural and conformance target. FCP_Specification_V2.md is retained as historical / legacy-interoperability context. When descriptions conflict, trust V3 for intended semantics and the code for current behavior.

A secure connector protocol and Rust platform for AI agent operations across zones, hosts, and personal device meshes. The workspace ships 42 platform crates under crates/, 177 connector crates under connectors/ (176 production connectors plus one adversarial conformance test crate, connectors/_adversarial/), and a single agent-first CLI (fwc) that classifies every answer by truth source and refuses to fabricate runtime state.

TL;DR

The Problem

AI agents need to act on the real world (read mail, file PRs, send messages, query databases, control hardware), but the prevailing toolchains do this with a shared-memory plugin model, an "API key in a .env file" trust model, and a "prompt told the model not to do that" security model. None of those survive a hostile input from Discord, a compromised laptop, or a misconfigured deploy.

The Solution

FCP is a connector platform where:

• Every connector is a separately-signed sandboxed binary with an embedded manifest declaring its capabilities, sandbox limits, and network constraints.
• Every operation is gated by a capability token with type-state-enforced binding, so an UnboundVerified token does not compile against a function that requires BoundVerified.
• Every request is bound to exactly one zone (a cryptographic namespace with its own symmetric key); cross-zone access requires explicit policy and proof.
• Every connector's outbound network traffic flows through an egress proxy with CIDR deny defaults, SNI enforcement, and secretless credential injection, so the connector binary never sees raw API keys.
• Every operation produces a signed receipt and is recorded on a hash-linked audit chain with monotonic sequence numbers and Hybrid Logical Clock causality, plus an OpenTelemetry OTLP parity exporter.
• Sensitive zones support post-quantum cryptography (X-Wing KEM hybrid HPKE + ML-DSA-65 signatures) and threshold owner keys (FROST) so no single device holds the complete signing material.

Truth Hierarchy

fwc classifies every answer by its source (mesh-backed > host-backed > node-local > offline) rather than collapsing everything into a single fake "live" state.

• Current operational path (V1, host-first): fwc → fcp-host → connector subprocesses over supervised stdio/JSON-RPC. This is what runs in production today.
• Target steady state (V2, mesh-native): personal-device sovereignty, mesh durability, capability-gated execution across your own infrastructure. The mesh infrastructure (gossip, IBLT, XOR filters, symbol-first object distribution, LiveTruthResolver, KnowledgeState taxonomy) is built and tested; the cutover gates are documented in docs/FCP3_Transition_Scorecard.md.

Three Foundational Axioms

Why Use FCP?

Status legend: - PROVEN: backed by direct repository evidence (tests, harnesses, golden vectors). - LIMITED: functional at the stated scope but narrower than the mature target (e.g. threshold-gated rather than adaptive). - STEADY-STATE TARGET: architectural target with built infrastructure but not yet operational by default.

PROVEN means repository evidence, not a claim of live production deployment.

Audit status: all status labels reconciled as of 2026-05-16. See docs/quarterly/2026-Q2-claims-vs-reality.md for the inaugural quarterly debiasing report.

Design Philosophy

Five principles drive every architectural decision in FCP.

1. Mechanical Enforcement, Not Prompted Compliance

Security is enforced by the type system, the binary boundary, the protocol, or cryptography. Never by a string in a prompt. Telling a model "don't read private email" is trivially bypassed by a hostile message; telling a Rust compiler that gmail.read does not exist in the z:public zone is not. Examples from the codebase:

• Capability-token typestate. CapabilityToken<UnboundVerified> and CapabilityToken<BoundVerified> are distinct types. An operation executor that requires full instance-binding declares fn execute(_: CapabilityToken<BoundVerified>, ...). An UnboundVerified token (produced by the gateway, which does not yet know the connector's real InstanceId) does not compile against that signature. Enforced by trybuild tests in crates/fcp-core/tests/typestate_compile_fail.rs.
• Connector-boundary ratchet. crates/fcp-conformance/tests/capability_typestate_connector_boundary_dja9u.rs checks LEGACY_VERIFY_ALLOWLIST.len() == 0. New connectors must use the typestate path; enforced connectors cannot regress.
• Sealed FcpConnector trait. Third-party crates cannot accidentally subvert the lifecycle by implementing the trait themselves.

2. Default Deny With Explicit Allow

If a capability is not granted, it cannot be invoked. If a zone is not bound, the host refuses to start the subprocess. If allowed_zones is empty, connector RPC fails closed before invoke, introspection, or health probes reach connector code. If cidr_deny is malformed, the sandbox