AI Harness Catalog

AAC and AHC, in one page

Two repositories, one boundary. Neither is complete alone, and merging them would make one of the two redundant.

They are separate because they answer different questions. An obligation nobody knows how to build is a principle; a component nobody knows how to check is a hope. Keeping them apart is what lets each stay short.

A worked pair

The assurance catalog says, in AAC-0055: maximum steps, wall-clock and token budget are enforced by the harness — not requested in the prompt — and the stop path is tested including its partial-result behaviour.

Note “enforced by the harness.” The obligation cannot say where that counter lives, what the caller receives at cutoff, or whether the budget is enforced in the loop or at the gateway — those are construction questions, and answering them inside an assurance catalog would turn it into a framework manual. So a capability here states what the loop must contain, and cites discharges: [AAC-0055] back.

What one capability looks like

Three fields carry the weight. failure_mode is what justifies the capability existing — a vague one means it is a principle, not a component. design_decisions is the substance; a decision with nothing genuinely traded away is not a decision. discharges is the join, and it runs both ways: an obligation no capability discharges is a hole in this catalog.

id: AHC-0004
level: MUST
layers: [L2]              # model invocation
positions: [P3, P2]       # harness library, gateway backstop
title: One choke point for every model call
requirement: >-
  Every model invocation in the system passes through a single component.
  Provider SDKs are constructed in that one place and nowhere else, and the
  set of reachable models is enumerable from it.
failure_mode: >-
  Once a second call path exists, every subsequent capability in this catalog
  acquires a hole. Cost accounting undercounts, spans go missing, the policy
  point is bypassed, and the model allow-list is advisory.
discharges: [AAC-0011, AAC-0100, AAC-0098, AAC-0094]     # <- the join
design_decisions:
  - question: In-process choke point, gateway, or both?
    tension: >-
      In-process sees types, caller identity and business context, but governs
      only code that imports it. A gateway covers everything on the network
      path and knows none of that context.
    resolution: >-
      Both, with the split made explicit. Write it down; the failure mode is
      each side assuming the other did it.

Conceptual now, physical later

Everything published today is conceptual and portable: what must exist, what breaks without it, and what you must decide. Nothing here names a product in normative text, and nothing here ships a component.

The physical layers come later and deliberately so — realizations (how each capability actually gets built, the only place products may appear) and reference skeletons (runnable, copied rather than imported). Products are the fastest-rotting layer; authoring them alongside each capability means writing them two or three times before the catalog stabilises. See the roadmap.

The dependency direction

One-directional: AHC → AAC. This catalog cites assurance identifiers; the assurance catalog contains no reference to this one and does not need to know it exists. That protects the neutral half — assurance guidance competes with nobody, and construction guidance competes with every framework's documentation.

Everything that is neither the model nor your business logic

The deterministic scaffolding that turns a model into a system. Sixteen layers, and that count is the argument.

Observability is L11 and the eval harness is L12. That they are two of sixteen is the point of this catalog: teams routinely build those two, and call the harness done. Layers are tags, not a tree — a capability frequently spans two, because context assembly is also a cost concern and tool dispatch is also an authorization concern.

Ten shapes, and what each one adds

The archetype vocabulary is owned by the assurance catalog and pinned here, so the two catalogs join on the same ten shapes.

Boundaries are drawn by two questions only — who owns control flow, and what the output touches. Not by domain, sector or model size, because those do not change what you have to build. Every shape owes the core block in full; the count on each row is what is genuinely new about that shape, which is why this is 118 capabilities and not several hundred.

Where it lives, and who supplies it

Deliberately not the assurance catalog's axes. That one organises by mechanism and stage — verification axes. This one organises by position and approach.

Position is this catalog's spine. It is the axis architects actually argue about, and the same capability at a different position is a different system: a budget enforced in the loop and a budget enforced at the gateway catch different failures and miss different ones. On every capability, the first position listed is primary; the rest are backstops.

Approach answers who supplies the machinery. Five of the six are the assurance catalog's vocabulary, kept identical so an adopter filters both catalogs the same way. framework is the one deliberate addition: “adopt an agent framework or build the loop” is the defining harness question and has no assurance-side equivalent.

Levels follow RFC 2119 usage and bind only within an adopting organisation.

Where the harness meets what it does not own

A capability says what must exist. A port says where the harness meets something it did not build, and what must hold across that meeting whoever implements it.

The catalog is portable because it names no products, and the cost of that is a gap: a reader agrees that every model call needs one choke point and still has to invent the boundary between their code and a provider's library — and everyone invents a different one. Ports are that missing vocabulary, declared as data so an interface can be generated in any language without this repository ever shipping a package.

A port is not a partition of the catalog. Most capabilities are structural and cross no seam at all. Two fields carry the weight: kernel_owns, which states what stays on the harness side and is therefore not an implementation's to decide — a seam with nothing on the harness side is a client library, and the linter fails the build for it — and the substitution test, which is how you tell a port from one vendor's API with a wrapper on it.

Operations are stated by intent, never by signature — no types, no language, no error taxonomy. Those belong to a generated interface, which is downstream of this catalog. A trailing ? marks an operation an implementation may legitimately not offer, in which case the harness needs a declared path for its absence.

Capabilities, in plain English

Select a shape. Core is always owed; the archetype block is what that shape adds on top.

Each entry states what must exist, what breaks without it, where it can live, the obligations it makes verifiable, and — behind the disclosure — the decisions whoever builds it is forced to make.

Which shapes need which layers

Archetype deltas only; the core row is listed separately since it would otherwise appear in every column.

Read this as a design-review heat map. A dense cell is where that shape's harness work actually is. An empty cell for a layer you know you need means either the classification is wrong, or the requirement was already covered by core.

Read from the assurance side

The same relation inverted: for each assurance obligation, what has to exist before anyone can check it.

This is the table that makes the pair useful at design review. An obligation with several capabilities behind it is one where the test is cheap and the construction is not. The join is also a completeness check in both directions — an obligation no capability discharges is a hole here, and a capability citing nothing is a component with no stated assurance consequence.

Obligation identifiers link to the assurance catalog's source. They are owned there, permanent, and stable in both directions.

What is normative today, and what comes next

The normative catalog is complete. What remains is the physical half — how each capability actually gets built, and skeletons to copy.

Phase 4 is deliberately last. Products rot faster than anything else in the catalog, and authoring them alongside each capability means writing them two or three times before the specification stabilises.