Technology · Discipline

Contract-first interface design

Every job an agent receives in my governance platform carries a schema that says what must come back. Contracts first, prose only for behaviour.

JSON SchemaValidated on both sidesSeam registry with census tests
One seam · a contract pair
producer checksconsumer checks
producerconsumer
On a mismatch nothing crosses the seam
2 checksagainst the same schema, on every handoff
  • 10seams in the registry, each with producer, consumer, schema and refusal tests
  • 6 + 4input contracts and overlays delivered in the first phase
  • 4.78 MBthe packet that went out past a ceiling one launch path never checked

A contract for every task

In AgentOS, free-form messages between agents were where long runs drifted, so I made every handoff in AgentOS a typed contract from its first phase. That phase delivered the input contracts and overlays under change control, pinned by a hashed manifest. Each task gets an execution contract rendered by AgentOS.

One task's execution contract
Write roots: where the agent may write
Sealed dependencies
Grounding the job needs
Completion contract: what must come back, and the evidence that proves it
What the agent may not do with it
edit it
Band heights are illustrative.

Above tasks sit envelopes, the ratified limits of autonomous work.

An envelope: the ratified limittasks inside proceed without escalation
Moving the edge
a change request with a declared blast radius

Both sides of every seam

Every seam has a contract pair. The producer validates against a JSON Schema when it builds a payload, and the consumer validates again when it ingests it. Both call one shared validator, so the two sides cannot drift apart, and a refusal names the schema it enforced, which gives an agent something concrete to fix.

A seam registry lists every seam, and census tests keep the registry matched to the source.

producerconsumerschemarefusal tests

Ceilings at the choke points

A packet-size budget sat in the pinned contracts while one launch path never checked it, and an oversized packet went out. I moved the ceiling into both choke points every packet passes, including the path that leaked.

Declaredlaunch path one
launch path twothe oversized packet passes the path with no check
Enforcedchoke point one
choke point two
the same packet stops at the ceiling
Packet widths are illustrative.

A declared limit nobody checks is documentation.

Data never travels as instructions

AgentOS renders and keeps every packet it sends, so the lead agent issues one-line decisions and has no path to edit an artifact; Why long agent runs fail explains that rule. I also ruled that work items never travel inside instructions.

The packet
Instruction text: literals compiled into the binary
path to the work item
anything derived from data, in a file

Quality verdicts anchor to the work graph's generation and the content actually read. Stored file digests had raised false alarms with no content defect behind any of them.

The schemas are JSON Schema and the validators are standard libraries; my part is where the contracts sit and what they refuse.