Architecture

The engine has six production crates, and trust flows in one direction; a seventh exists only for tests. The unpublished provider-controller crates share the same workspace and depend on the engine, never the other way round.

The graph above is the root workspace. amiss-wire is its foundation: strict JSON with canonical output, the digest rules, the report format, and every machine contract. Nothing in it knows what a repository is.

amiss-git reads Git storage behind the never-follow-links boundary: loose objects, packs, deltas, and the index, each under a parser that rejects malformed input and a published resource ceiling. It repairs nothing.

amiss-md holds the document parsers, pinned against the official CommonMark and GFM test suites plus the MDX grammar’s own tests. The pin is a checked-in manifest recording node counts, extraction results, and byte positions for every test case. A parser change that moves any of those moves the manifest, and review sees the diff.

amiss-scan is the evaluation itself: discovery, resolution, correlation, the base-versus-candidate comparison, policy, and report construction. It is a library that does no I/O beyond the store handed to it. It also carries the ten heading-identity rules, each pinned against the renderer it models rather than written from its documentation.

amiss is the binary: the closed public command grammar, the in-process run, the two output formats, and a private sealed entry reserved for the bootstrap. amiss-bootstrap validates a pinned action tree and externally supplied constraint as data, validates three canonical requests, and launches the verified engine with a cleared environment and a closed stdin frame. It is the root production crate allowed to start a process, and the process it starts is the binary it just verified. The sealed path exists but is not integrated into the published convenience Action; Project status keeps that distinction explicit. A seventh crate, amiss-fixtures, exists only for tests: it writes hostile Git bytes straight into test repositories so the same fixtures exist on every platform.

The root api/ specialist and controller/ crates sit outside that graph. They are unpublished and nothing above depends on them. amiss-api normalizes bounded Rustdoc JSON into semantic records without entering provider binaries. The controller crates keep provider, HTTP, storage, credential, Git acquisition, and runtime dependencies out of the scanner. amiss-controller owns the provider-neutral orchestration and supervised bootstrap contracts; amiss-controller-git owns bounded protocol-v2 acquisition; and amiss-controller-service owns the bounded webhook, synchronous evaluation, and authenticated artifact endpoints, durable raw inbox, and worker. Small provider crates and service binaries add the GitHub App Check Run, GitLab merge-train policy job, and Gitea or Forgejo dedicated-reviewer gates. All durable state uses ordinary files rather than SQL or a database.

Controller delivery defines the neutral record and retry rules. Provider-verified controls compares the concrete flows and links each provider’s setup and trust boundary.

Inside an engine run, the stages form a line:

Each stage charges resource counters at a defined admission or observation point, and a crossed ceiling is a refusal, never a repair. Not every counter is a pre-work bound: document bytes are admitted before parsing, while parser node and nesting totals are charged after the grammar returns. Security model records the CPU-boundary limitation that follows from that ordering. Subject to those declared inputs and boundaries, the report is a pure function of the two snapshots and the invocation.