These documents define FX independently of any implementation. The Rust engine, the SDKs and the conformance suite all follow them.
| Document | What it defines |
|---|---|
| identity.md | Values, canonical JSON, and every digest: files, node types, routes, steps, calls, plans |
| facts.md | File facts: what facts(f) gives for every file, image, WAV, MP4 and Matroska/WebM file |
| yaml.md | The strict YAML subset FX reads |
| expressions.md | Expressions: what counts as nothing, and the fallback ??, including a missing field |
| store.md | The cache layout and its records |
| observation.md | Run-observation v1: consistent snapshots, bounded events, cursors and errors |
| exports.md | Portable terminal run inspection: disclosure, verified media, immutable manifests and offline export |
| service.md | Project initialization, local service lifecycle, stable run/plan URLs and standalone inspection |
| layout.md | Canvas layout: the automatic grid and decks, and the optional <workflow id>.layout.json file (not implemented) |
| control.md | Local run control: exact invocation targeting, cancellation acceptance, verified local completion and force boundaries |
| sdk.md | SDK user jobs: named execution/resume, pinned saved records, independent observation and in-process stand-ins |
| distribution.md | The ways to run FX (grida fx, grida-fx, python -m grida.fx), the invoker, the host contract and the release order |
| protocol.md | The node protocol between the engine and a node host, and the Python and TypeScript hosts |
| capabilities.md | Each paid capability's canonical request, its answer, and the features a route declares |
| adapters.md | The adapter contract, version 1: where adapters run, the transport, how provider answers become outcomes and bills, refusals, long jobs, downloads and reasons, provider options, and the binding of a project's own adapters, which run out of process (§9) |
| providers.md | Provider declarations (FX's own and a project's providers:), their keys and endpoints, the built-in adapters, the family adapters and their references, a declaration's own adapter, the built-in route table, and renamed features |
| schemas/ | JSON Schemas for every document and record |
| vectors/ | Test vectors: canonical JSON, YAML, identity examples, file facts |
A change to identity changes every cache. It needs a new kind version in identity.md, new vectors, and a migration note. The one exception, the route contract's completion (identity.md §7), kept fx-route-v1 because it moved no built-in fingerprint; it has its vectors and its migration note.