Semantic Infrastructure Lab

Trust gets engineered twice — once into the agent's own operating environment, once into the tools it points at the work. Comparing the two exposes a confidence dimension the original five properties never name.

We did not set out to build the same five things twice.

I Didn't Learn to Trust AI. I Learned to Engineer Trust. argued that trust is an emergent property of an engineering system rather than of a model, and derived five properties such a system needs: Observability, Verification, Containment, Continuity, Meta-Engineering. It reached them inductively, from eighteen months of incidents.

This article asks a different question: where do those properties actually live?

That question has a structural answer, and it is sharper than "trust has two parts." The five properties are not five components of one system. Each one has to be engineered twice — once into the agent's own operating environment (how it boots, what it remembers, how work is tracked across sessions), and once into the tools through which the agent perceives and acts on the artifact. Observability is not divided between them; it is implemented in both, differently. Neither implementation substitutes for the other, and a system built with only one fails in a characteristic, recognizable way.

Worth saying plainly: this decomposition was not designed. The agent operating environment and the artifact tooling were built separately over roughly eighteen months, by people solving different problems on different days. Nobody set out to implement five properties twice. The symmetry only became visible in retrospect, laying the two side by side — which is the main reason to trust it. The examples below come from two implementations built in this lab: TIA, our agent operating environment — the boot sequence, operating manual, persistent memory, and task ledger the agent works within — and Reveal, a structural query layer for code.

That decomposition is this article's subject. It also has a consequence, and flagging it before we start is what makes the exercise more than filing: you cannot lay the two halves side by side without noticing something neither one shows on its own. The same blind spot turns up in the same place in both implementations — a question about its own perception that neither half was built to answer, and that the original five properties never name. The table below leaves it a column, unnamed. This is far easier to recognize from a failure than to accept as an abstraction, so §1 ends with one and the name follows immediately after.

The rows do not all behave alike. The first three mirror almost exactly: the same engineering job, implemented in two places. Continuity complements — retrieval finds, a ledger closes, and neither does the other's job. Meta-engineering goes further still, into feedback: it is where the two implementations begin improving each other.

Mirror → Complement → Feedback

That progression is the spine of what follows, and it is where the framework stops being tidy and starts being useful. Each section below says which of the three it is.

1. Observability — Can the Agent Perceive Reality?

Mirror.

Agent implementation. Before touching anything, the boot sequence runs a fixed orientation: live project status, a time-sorted document list, then structure. This isn't ceremony — the alternative is an agent acting on stale assumptions about a project it hasn't actually looked at this session. The rule is explicit: a summary injected at session start is ambient context, not a substitute for running the orientation yourself.

Tool implementation. Progressive disclosure — directory, then file, then element, then behavior flags — exists so perception scales with the artifact instead of collapsing into "read everything." The _dispatch_nav example makes the case concretely: six sys.exit calls hiding inside a function named like a router, invisible to a header read and hard to find by grep.

Both halves converge on one rule: the agent should be able to see the shape of a thing before it commits budget to the contents. And the rule turns reflexive — an agent's own history is an observable artifact too. Session archaeology answers what git log cannot: what was tried, what failed, what was abandoned. A system that cannot ask that has no way to catch itself repeating a mistake it has already made.

And the part that breaks

Observability tools carry an assumption, and the assumption can stop holding without any error being raised. The first article's sharpest example was the legacy PHP file that runs past 11,000 lines and defines no functions at all: a function-shaped index reports almost nothing, not because it is broken but because the abstraction it indexes on stopped matching reality. The fix was a second lens on a different abstraction — what behavior exists here rather than what functions exist here.

Told once, that is a story about one bad file. Told beside the other half, it is a correction to how progressive disclosure is usually described:

Chunk size is downstream of chunk unit. "Read the right amount" presumes you are chunking on a boundary the artifact actually has. When the unit is wrong, the size is irrelevant — and the failure is silent, because a function-shaped index over a function-free file returns a clean, confident, empty answer.

There is a name for what that clean, confident, empty answer is missing.

Calibration: The Dimension Running Through All Five

That is the column the table left open, and it now has a name. Observability asks whether the agent can see. Calibration asks how trustworthy the agent's perception currently is — what it failed to see, what got silently truncated, what has gone stale, what its tools could not resolve. The two come apart, because a perfectly executed observability operation can still produce a confidently wrong completeness signal.

It gets a section because it needs a definition; it does not get a number, because it is not a peer. Calibration is to these five properties what latency is to a network stack: not another layer, but a property every layer has, which only shows up when you measure across them. Nobody adds latency to a protocol — you either account for it at each hop or you get a system that works perfectly in theory and disappoints in production. Calibration behaves the same way. It is not a sixth property standing beside the other five and it is not a second thesis, which is why it only became visible by comparing the halves and finding the same silence on both sides. Watch where the four mechanisms below come from: one is an observability failure, one lives inside a verification contract, one is a containment sweep, one is a continuity index. Calibration has no home of its own.

That is why either half alone hides it. Each looks complete inside its own boundary — the tools answer every question you think to ask them, and the operating rules cover every situation you thought to write down. Only with two independently built systems side by side does the same shape of silence show up in both: neither had a way to say what it could not see. The original framework came close in its closing thesis — most failures came from "reasoning correctly over the wrong representation of reality" — but there was no section for the dimension to sit in, so it stayed a lesson rather than a component.

Distinguish absence from blindness

An empty result means one of two very different things: there is nothing here, or I cannot see what is here. A tool that renders both identically will eventually hand an agent a clean bill of health it did not earn. TIA's memory carries this as a standing rule, written after a measurement: a near-empty outline on a 500-line file means the file was not triaged, not that it was simple — structural coverage on one such file measured 2.3%.

The behavior lens built for that PHP system encodes the same principle in its own interface. Its cross-file lock sweep documents, in the help text an agent reads to learn the command:

"Writes whose table name is interpolated are reported, not dropped: an unresolvable table cannot be ruled out of a cross-reference sweep."

That is the whole idea in one sentence. A sweep that silently discards what it could not resolve returns a false clean result. Reporting the unresolvable is what keeps a green answer honest.

Label confidence at the point of use

The same tool goes further, and this is the single design pattern most worth stealing. Its help text does not only say what a command finds — it says what the finding does not prove:

• "Dynamic matches are flagged '(dynamic path — verify)' — not a guarantee, since a dynamic path can't be fully resolved without running the code… Always read dynamic matches as 'worth checking', not proof."
• "STATIC in-file existence check … not proof of runtime delivery or path co-occurrence."
• "Classifies loop FORM, not the proven bound."

It even ships a real false positive from the production corpus as documentation: an unrelated include matched a target purely because both filenames happened to end in the same conventional suffix.

The delivery mechanism matters as much as the content. Those caveats live in the same text the agent reads to learn the command, so the capability and its limits arrive together and cannot be acquired separately. That is calibration by construction rather than by instruction.

Announce what you cut, and how old it is

Two failures with the same shape. Reveal's token-budget flags (--max-items, --max-snippet-chars) do not silently cut a list short — when output is trimmed, a meta.budget field appears carrying a pagination cursor, so the agent knows it received a partial view. An agent that does not know it was truncated draws conclusions from incomplete data at full confidence; silent truncation is one of the surest ways a well-built retrieval layer produces a confidently wrong answer.

Staleness is the same problem in the time dimension. A stale fact that looks current is worse than a missing one, because it is cheap to believe — which is why TIA's document graph warns when its answer comes from a graph more than seven days old. The corollary for writing: cite the command, not the number. Every hardcoded count is a future lie with a delay fuse. Preparing this article turned up three in our own published material — a rule count, a tool count, and a version — each correct when written and wrong by the time anyone reread it.

A worked example, from writing this article

The best illustration came from getting it wrong while researching this piece.

We ran a link-graph query across the article corpus to measure how well the series cross-references itself. It returned twenty files, four edges, fifteen isolated — and the conclusion drawn, that these articles largely fail to link to one another, survived two rounds of analysis before anything caught it. What the tool actually reported was that fifteen files contain no links that resolve as filesystem paths. The articles cross-link heavily; they just use web-absolute paths, because that is what the published site serves.

Every step was individually correct. The tool answered accurately, the measurement was reproducible, the reasoning over it was valid — and the conclusion was still false, because the representation being measured was not the representation the question was about. This is what the failure feels like from the inside, which is to say it feels like nothing at all. No error, no warning, no ambiguity. What caught it was checking the claim against a second representation before publishing.

2. Verification — Can We Prove What We Think Is True?

Mirror.

Agent implementation. "Never trust a status report when you can verify reality directly" has teeth here. Marking work complete requires a commit hash validated against the actual repository; nothing is inferred, and "merged" is not treated as "released" until an ancestry check confirms it. The verification methods themselves get verified too: one standing rule exists only because a common way of confirming a committed fix silently no-ops on already-committed files and then manufactures a phantom conflict — a technique that returned a false result once and was replaced with one that cannot.

Tool implementation. reveal check and reveal review return real exit codes rather than a narrated summary, which makes them valid CI gates with no configuration — the published CI gate recipe is a few lines of YAML wired straight to those codes. Structural diffs carry complexity_before, complexity_after, and complexity_delta as data, so "did this change make anything harder to maintain" becomes a query instead of an impression. And the subagent output contract — Finding / Evidence / Mechanism / Confidence / Unverified — pushes verification into the shape of the answer: a finding has nowhere to live unless a command produced it. Being exact about the mechanism, since it is easy to oversell: this is a required output template, not a validated schema. Nothing rejects a malformed answer. What it does is make the omission conspicuous — a missing Evidence: line is visible in a way that a merely unsupported sentence is not, to the reader and to the agent writing it.

Note the last field. Unverified: is a calibration primitive living inside a verification contract — a declared boundary of what was not established, which is what makes the positive findings worth anything.

The synthesis: both halves land on the same move — replace a sentence asserting something with a structure that can only be populated by something that already checked. A commit hash. An exit code. A complexity delta. An evidence field with real command output in it.

The calibration question here — what did this check not cover? — is why the token-reduction figures behind progressive disclosure are published with their methodology and error bars, and as an honest range rather than the single flattering number. A benchmark that declares where it is weakest is doing the same work as an Unverified: field.

3. Containment — Blast Radius, in Both Directions

Mirror — and the last one that does.

Agent implementation. The hard rules are pure containment: never push without an explicit instruction, stop and ask before any production or remote-write action, verify ephemeral compute is torn down before a task counts as done. That is the permissions-versus-contracts distinction made operational: not a list of what the agent may do, but of what it should do and what it must ask about first.

And the second direction, which is consistently underrated: concurrent interference. A standing rule forbids blanket staging in shared repositories, because two agent sessions each believing they are making an isolated change is how one quietly sweeps the other's unfinished work into a commit under the wrong message. That is not a reasoning failure. It is a race condition, and agentic systems inherit every problem distributed systems have had for decades.

Tool implementation. Tool restriction is containment applied to agent design itself. The analysis subagents ship with read-only tool sets — the edit and write tools are simply absent from their definitions, which is a stronger guarantee than an instruction not to use them. Worth being precise about how strong, though, because this is exactly where a blast-radius estimate gets flattering: they retain a shell, and a shell can write. The removal is a real, structural narrowing — it deletes the convenient path and makes mutation something the agent would have to construct deliberately — but it is not an inviolable boundary, and describing it as one would be the same overclaim this article keeps warning about. The same discipline runs one level down: Reveal's navigation flags are read-only by construction, with no --fix. Observation and mutation do not share a code path, let alone a tool call. And before an edit happens, call-graph and import queries give a blast-radius estimate for free.

The same instinct extends past agents into ordinary code. Declaring an architectural boundary in an enforced config file — routes may not import repositories, checked on every commit — converts a promise into a contract that fails CI the moment it is crossed. A design document says what should be true. A contract makes it true whether or not anyone remembers to check.

The calibration question here — what lies outside my blast-radius estimate? — is the one a call graph cannot answer about itself. Dynamic dispatch, reflection, and string-built call targets are precisely what a static sweep misses, which is why the honest ones report what they could not resolve rather than quietly dropping it.

4. Continuity — A Ledger, Not Just Retrieval

Complement.

Here the halves stop reflecting each other. They complement each other instead, and the tool half alone does not solve it.

The tool implementation gives retrieval, which is necessary and not sufficient. Session search and session archaeology are excellent at finding what happened. They have no concept of status. Nothing marks a thread resolved; nothing tracks ownership. That is not a gap in the tool — it is a different problem than the one the tool is built to solve.

The agent implementation is the ledger. The original article's continuity example — one missing configuration fact, independently rediscovered across more than half a dozen sessions over more than a week, because every session searched correctly, found it, and stopped — is exactly the failure a committed task tracker was built to close.

The design process behind that tracker is itself the lesson, and The Hard Part of Agentic AI Isn't Reasoning — It's Grounding documents it in full. The short version: four projects that had each hand-rolled a markdown task list were surveyed, and the same three weaknesses turned up independently in every one — no real ID counter, no structured status field, and a schema too rigid for the evidentiary detail real entries carry. What came out of it generalizes past task tracking to any durable agent artifact: the artifact must outlive the tool (plain committed markdown, usable with none of our tooling installed), the IDs must be self-hosted (a tracker migration elsewhere renumbered every ticket and killed every historical link), and resolution must be recorded explicitly rather than scraped from commit-message conventions that drift.

And one failure mode to design against, because it is the part most teams get wrong: "it isn't building the tracker — it's building it and not connecting it. A task list nobody sees at session start, that isn't searchable alongside the docs, that the agent has to remember to check, is a task list in name only."

A new system needs retrieval and a ledger, and they are not the same component:

Retrieval answers "has this been discussed."
A ledger answers "is this resolved, and if not, whose job is it."

Build only the first and the same gap gets rediscovered for free, forever.

The calibration question here — how stale is what I retrieved? — is why an index-backed answer should carry its own age. Retrieval that cannot say when it last looked is indistinguishable, from the inside, from retrieval that is simply wrong.

5. Meta-Engineering — Does the Environment Keep Improving?

Feedback.

The name undersells it. Failures are the obvious input, but the real activity is broader: continuously improving the environment the agent works in. Here the halves feed each other — rules produce tools, tools produce new routing problems, routing produces new rules.

Three modes drive that, and only the first is what "learn from failure" usually means. An incident produces a standing rule. Repeated friction that never actually broke anything produces a tool — Reveal itself is this mode, no single incident produced it. And a capability the agent never reached for produces teaching rather than code. The third is the least discussed and, in our own commit history, by far the most common; a representative month of commits to the agent's repository reads "teach agents the Beth audit golden path," "document graph explore for related-doc lookup," "add the grep/help-discoverability reflex." None of those built anything.

The agent implementation is an operating manual and a memory system accumulating rules traceable to specific incidents — a verification technique replaced after it returned a false result, a staging rule written after two concurrent sessions collided.

The tool implementation is the rule engine (reveal check --rules, --explain <CODE>) and — more interestingly — an anti-patterns guide: a blunt list of ways the tool gets used wrong, including reading files too early and ignoring the breadcrumbs the tool prints to say what to run next.

What makes this the Feedback stage rather than a third mirror is that artifacts move between the halves. The clearest case ran in three moves. The tool's own reference had grown to 40,000 tokens, so the operating manual gained a hand-written warning never to open it cold — a workaround, living in a file that downstream projects copy and none of them re-measure. The tool half then named that hand-maintained manual, in its own planning document, as "Exhibit A for why orientation must be emitted by the tool, not templated," and set a goal of shrinking the copied block to one line pointing back at the tool. Tiered help shipped seventeen days later; two days after that, the hand-written warning was retired.

Workaround in the agent half, feature in the tool half, workaround retired. The loop is not "we wrote down a lesson" — it is that a hand-maintained copy of the truth got recognized as a defect in the tool, and the fix moved that truth to the only place it cannot drift from: the tool's own output.

The mechanics of that loop — why it sometimes runs in three hours and sometimes takes seven weeks, and what the two speeds have to do with each other — are the subject of The Two Speeds of Meta-Engineering.

Meta-engineering is not a resolution to be more careful. It is a standing artifact — a rule, a scanner, a tool, a paragraph in an operating manual — that outlives the session where the friction was felt.

The calibration question here is the sharpest of the five: which failure classes have I never swept for? A rule engine reports what it checked; almost nothing reports what it cannot check at all. The best answer we have built sits on the tool side, and it is the piece to steal first: more than thirty ground-truth recall oracles, one per language pass, measure what the structural lens misses; a correctness matrix records which rules are verified where; and check --rules prints the distinction between "verified here" and "runs here as best-effort." That is coverage measured rather than assumed — a tool that can state its own blind spots in numbers. TIA has no equivalent yet: nothing measures which of its own standing rules were ever actually followed, and every lesson in it got written because a person noticed, not because anything watched. Building the second one is the next piece of work.

What Generalizes: Two Tools, One Shape

If this decomposition only described Reveal, it would not be worth much. So here is the reason to think the tool implementation has a definite shape rather than reflecting one tool's preferences.

Reveal is a general-purpose structural query layer — twenty-five adapters, hundreds of languages, 143 releases. The behavior lens is a single-purpose tool built for one legacy PHP codebase whose structure defeated AST analysis. Different abstractions, different artifacts, no shared code. Capabilities have crossed between them deliberately — one taxonomy made the trip in a single afternoon — but the seven moves below are not that. Nobody ported them, and they turned up in both anyway:

The last row is the one to build first, and the easiest to leave out.

Notice what none of the seven are about: parsing. Not one is a claim about languages, syntax trees, or code at all. They are interface decisions about helping an agent know what it just learned, what it did not, and what the next answer will cost — which is why they survive the change of artifact in the section below.

Two tools solving different problems arriving at the same seven moves is reasonable grounds for treating these as candidate design principles rather than isolated implementation choices. If you are building the tool half of a new system and it has none of them, that is worth explaining rather than assuming.

What This Argument Does Not Claim

Four caveats, stated before the build list rather than after it, because they change how you should read it.

Most of the tooling cited is not mature. Of the twenty-five adapters in the structural lens, five are marked stable; the rest are beta, project-specific, or experimental. The patterns are what transfer; the specific commands are a moving target — hence the recommendation below to cite commands rather than copy version numbers.

The behavior lens is a domain tool, not a product. It was purpose-built for one codebase's real shape, and it works because it was fitted rather than generalized. The transferable part is that a second lens was built at all, on a deliberately different abstraction.

The convergence evidence is weaker than it looks. Both tools come from this lab. They target different artifacts on different abstractions with no shared code, which is what makes the agreement interesting — but they do not have independent authors, and shared instincts are a live alternative explanation. And at least once it was not convergence at all: a side-effect taxonomy crossed from one tool to the other in an afternoon, deliberately, by the same hand. That instance is evidence of a transferable design, not an independently discovered one, and the two should not be counted as the same kind of support.

So treat the seven moves as a hypothesis, and here is what would falsify it: examine a mature agent platform built by people with no connection to this lab, and look for the same split — properties implemented once in the operating environment and again in the tooling, with a calibration gap in both. If the split is not there, or if one half turns out to subsume the other, this framework is describing our house style rather than a property of the problem. Run that check before adopting any of this wholesale.

Not every gate we designed got built. One roadmap here spells out a complete pre-merge check for a posting pipeline — invariant guards already designed — under a heading reading, verbatim, "REJECTED — not adding CI gates," with the cost acknowledged in the same breath. It was priced and declined, on the record. Not every promise gets upgraded to a contract, and the honest move is writing down that it did not.

Standing Up a New System: What to Build, and When

The five properties are usually presented as peers. Building both halves makes clear they are not — they come online at different times, and a checklist that ignores this implies you can stand up a fully trust-engineered system on day one. You cannot, and the reason is structural: meta-engineering runs on experience you do not have yet. A brand-new system cannot have it — not because nobody thought of it, but because no incident has happened, no friction has repeated, and no capability has yet gone unused.

That is not a gap to apologize for. It is the actual answer to "how do I get from a new agent to a trustworthy one" — some of this is installed, some accrues, and some is earned. The tiers also feed backward: every Tier 3 artifact eventually becomes a Tier 1 default for the next system you build.

Tier 1 — installable on day zero

1. Make progressive disclosure the only way in. Structure, then outline, then element, then behavior flags — enforced by which tools the agent has, not by instruction. The concrete mechanism is tool registration: Reveal ships an MCP server exposing six tools (reveal_structure, reveal_element, reveal_query, reveal_pack, reveal_check, reveal_nav). Register those, omit a raw whole-file read, and the discipline stops being a policy the agent can drift from.
2. Restrict tools by role, structurally. An analysis agent gets read and query, never edit or write. Cheaper and more reliable than an instruction to look but not touch.
3. Gate the irreversible. Approval before production changes, pushes, and anything externally visible. Contracts, not permissions.
4. Require confidence and truncation signals in tool output. Distinguish "nothing here" from "cannot see." Announce partial views rather than performing completeness. It is the cheapest item on this list, and the one we most often see missing entirely.

Tier 2 — build now, benefit later

5. A ledger, distinct from search. Committed with the project, real IDs, a status enum, validated resolution references. Building it in month three loses months one and two.
6. Session and tool-call history from day one. If nobody can ask "what did we already try and what failed," every session relearns its own mistakes.
7. Author documents to be retrieved. Real headings so an outline query works, metadata so search finds it, cross-links so related is a traversable relation rather than a guess. Retrieval quality is capped by how the corpus was written, and this is the half of grounding that only pays off in sessions you are not in yet.

Tier 3 — earned through use

8. Dogfood on real work, and write down where the tool fell short. Not synthetic tests — actual work on an unrelated project, with a short note per incident: what happened, root cause, and the problems separated by cost to fix. Ours are filed under the project the work was on, not the feature at fault, which is why they read as requirements rather than bug reports.
9. Let friction write rules — and tools, and instructions. A cost paid twice and never turned into a check, a command, or a line in the operating manual is a cost paid again by whoever hits it next.
10. Prefer a scanner to a note. "Watch out for this" finds the instance you already know about. A scanner finds the ones nobody has looked at.
11. Build the second lens when the first stops fitting. Not when the model seems confused — when the abstraction stops matching the artifact. Knowing the difference requires Tier 1, item 4.

None of the eleven make the model smarter. All eleven make a specific class of failure structurally harder to produce.

None of this is about code

Every example here happens to be code, because that is the artifact this lab works on. Nothing in the framework depends on it. Substitute the artifact and the two halves stay put: a contract review agent needs a structural lens over clauses and defined terms, and a ledger saying which redlines are settled and whose signature is outstanding. A research agent needs to distinguish no papers exist from my query missed them, and a record of hypotheses already tested and abandoned. An operations agent needs a blast-radius estimate before it touches a running system, and a way to say what its estimate could not resolve.

The test transfers cleanly. Ask of any agent system: what does it perceive, what does it know it cannot perceive, and where does a finished thread get marked finished? If the answer to the second is "nothing" and the answer to the third is "the transcript," it has one half, whatever the domain.

Both Halves, or Neither

The failure modes of building one half are specific enough to recognize.

Build only the agent half — good boot discipline, hard rules, a real ledger — and point it at an artifact your tools cannot perceive, and you get the 11,000-line file with the confident empty outline. Every process working, nothing seen.

Build only the tool half — excellent retrieval, structural queries, session search — and you get one configuration fact rediscovered across eight sessions in a week. Every search succeeding, nothing finished.

Laid out whole, the decomposition looks like this:

Read the bottom two rows carefully, because that is where the halves stop mirroring each other. Retrieval finds what happened; only a ledger can say it is finished. A rule teaches the next session; only a scanner finds the instances nobody has looked at yet. Where the columns diverge is exactly where each half is doing work the other one cannot — which is the argument for building both, compressed into two rows.

Calibration is the question asked of every cell in that table: how good is this right now, and what is it failing to show?

The model never becomes perfect. What it can perceive, what it knows it cannot perceive, what gets verified rather than trusted, what damage a wrong answer can do, what survives past one conversation, and what gets permanently fixed — all of that is engineering, and all of it is yours to build.

Where this goes next. One of the five behaves unlike the others: meta-engineering is the only property where the two halves start improving each other. Watching that loop with dates attached — why it sometimes closes in an afternoon and sometimes takes seven weeks — is The Two Speeds of Meta-Engineering.

Part of SIL's ongoing series on agentic reliability. See also:
- I Didn't Learn to Trust AI. I Learned to Engineer Trust. — the five properties, and the incidents they came from
- The Two Speeds of Meta-Engineering — how a lesson becomes a permanent capability, in three hours or seven weeks
- The Hard Part of Agentic AI Isn't Reasoning — It's Grounding — getting the right information in, and the ledger design process
- Trained to Please, Empowered to Act — five public incidents behind permissions versus contracts
- Agents That Don't Read Everything — escalation ladders and evidence-bearing output contracts
- Session Archaeology — querying an agent's own history as an audit trail
- Configuration as Semantic Contract — architectural boundaries enforced on every commit