Chapter 8 – Map-Updaters: From Terrain to Map
Documentation, specifications, inventories, and policies drift because the systems they describe continue to change. A workflow can make selected drift visible and propose a correction limited to one Map surface permitted by its Mission and adopted policy.
A Map-Updater is specifically a Terrain-to-Map workflow. It observes declared facts in the current system, compares them with one Map surface within its Mission’s authority, and proposes a reviewable Map change when they diverge. Adopted policy must permit that surface. The workflow does not change Terrain.
This direction matters. The same file can be authoritative for one property and observational for another. Route declarations can define one narrow property: the current endpoint inventory. They do not define intended API policy, compatibility promises, or future design. A Map-Updater must name the property for which the observed source is authoritative.
Sense, Normalize, Compare, Propose
The updater has four steps:
- Sense: observe the declared Terrain sources at the immutable identities already bound into the activated Mission and record the observations with provenance.
- Normalize: parse those observations into a stable representation, removing irrelevant transients.
- Compare: normalize the selected Map surface and compute the difference.
- Propose: when drift exists, create a candidate change inside the declared Map region.
All four steps may be deterministic. When structured Terrain can render the Map directly, that is preferable. If a model adds connective prose, the extracted facts do not change during generation, and the candidate stays inside the selected Map region. The workflow then re-extracts and checks the factual structure before proposal closure.
The run reaches no_change only when every required
source was available, the comparison completed, and no candidate effect
exists. The Run Record is then sealed. Missing or contradictory evidence
cannot be interpreted as agreement.
Chapter 6’s Skeleton-First rule has a descriptive form here: deterministic extraction records the observed structural facts in Terrain. Probabilistic generation may supply only the permitted explanation or presentation. If generated structure is later mistaken for observed fact, the Map begins reinforcing its own invention. Re-extraction outside candidate authority helps prevent that contamination by rejecting a mismatch before proposal closure.
One Map Proposal
Continue with the payments service from Chapter 7. Its local operator Map lists public routes, ownership, health checks, and standard commands. Route declarations, ownership metadata, deployment manifests, and task-runner definitions already contain those facts.
| Contract element | Declaration |
|---|---|
| Observed sources that define this generated property | Route declarations, ownership metadata, deployment manifests, and command definitions at pinned revisions |
| Permitted effect | Edit only the generated inventory blocks in the operator Map |
| Required evidence | Source identities, normalized comparison, candidate identity, and complete check results |
| Required checks | Every source parses; no out-of-region edit occurs; the candidate’s extracted inventory exactly matches Terrain |
| Adoption | A separate authority makes the exact supported proposal authoritative; any earlier staging remains non-authoritative |
A representative candidate remains small:
## Health Checks
- Readiness: `/ready`
+ Readiness: `/readyz`
## Ownership
- Primary: `payments-platform`
+ Primary: `money-movement`The updater can establish that drift existed, that the patch stayed inside the permitted Map blocks, and that its extracted inventory matches the declared Terrain sources. It cannot establish that the organization chose the right owners, routes, or operating policy. Those are different properties with different authority.
After every required check passes, complete records
proposal closure. The final artifact is a supported proposal, and the
Run Record is sealed.
When the Map Surface Is Hierarchical
The payments Map is shallow; other surfaces organize facts in deeper hierarchies. An operator guide, for example, may group routes and commands under service, subsystem, and platform sections. During Normalize, the updater parses leaf facts and deterministically aggregates parent inventories or counts before comparison. These derived views remain traceable to the named Terrain sources; bottom-up aggregation does not make them Map proposals.
Each derived parent view must retain links to the leaf observations that support it. If the proposed Map change needs a judgment-heavy parent summary or connective prose, a model writes it only during Propose. That material remains a candidate with its sources attached and receives a proportionate review.
When one leaf changes, the updater invalidates each derived ancestor whose declared inputs include that leaf.
The Terrain-to-Map authority direction, not bottom-up traversal, makes this a Map-Updater: declared Terrain facts support a proposed change to one Map surface within Mission authority.
Map-Driven Reconciliation: Map to Terrain
A Map-Updater always runs from observed Terrain toward a proposed Map revision. The opposite authority direction is Map-driven reconciliation: an authoritative Map governs a proposal to change Terrain within the declared effect envelope.
| Direction | Authority held for the run | Proposed effect |
|---|---|---|
| Terrain → Map | Declared observed facts for one Map property | A Map revision limited to a surface permitted by the Mission and adopted policy |
| Map → Terrain | An adopted requirement or desired state | A Terrain candidate within the effect envelope |
The directions are not inverses. Map-driven reconciliation elaborates adopted intent into a Terrain candidate. A Map-Updater describes selected facts observed in Terrain. It cannot recover why the system was built, infer what policy ought to be, or make its description authoritative.
If policy requires encrypted storage and a Sensor observes an unencrypted bucket, Map-driven reconciliation may propose the infrastructure change. The policy remains fixed during that run.
If evidence suggests the protected policy itself is wrong, the
reconciliation workflow must not edit its own authority to make Terrain
pass. It ends blocked and names the required external
decision. A separate Governance Mission may then propose a change to the
named protected Map, policy, authority, workflow, or control surface;
separate Adoption makes the exact proposal authoritative.
Completion Does Not Make a Map Authoritative
The updater and the delivery pipeline answer different questions. The
Map-Updater may reach complete because proposal closure
produced a supported proposal and the runtime sealed its Run Record. The
pipeline may still stop because the currently adopted Map remains out of
sync until separate Adoption makes the exact proposal authoritative.
That separation avoids a false failure. The updater completed its declared work; the enclosing policy decides whether unresolved drift may proceed. A waiver, where permitted, is a separate decision with a named scope, rationale, approver, and expiry.
For factual Map regions, validation should re-extract the candidate’s structure and trace it to the declared sources. Structural lint and reference checks may support that comparison. Subjective prose receives a proportionate review gate. No tool list can prove every sentence true; each enforced property needs a declared basis and a check outside updater and candidate authority.
Maps as Operating Memory
At small scales, a Map may be a schema, interface inventory, or policy file. At larger scales, Maps include architecture decisions, operating rules, incident lessons, onboarding guidance, and other shared knowledge.
Not every surface should become a hard gate. Structured contracts often support exact comparison. Judgment-heavy material may produce an advisory proposal that still requires human review. Different Map surfaces need checks proportionate to the claims they make.
The context-quality properties from Chapter 6 still apply: a useful Map concentrates decision-bearing meaning, remains traceable to current evidence, and stays relevant to the governed property. A Map is fresh only for the surfaces that were actually compared. More text does not make it current, and synchronization does not make every claim true.
Historical evidence can also support proposals: repeated incidents may justify a runbook change, and recurring review findings may justify a new check. A Map-Updater may propose a change to a Map surface permitted by its Mission and adopted policy. A protected check or policy change requires a Governance Mission. Separate Adoption makes either proposal authoritative.
The synchronized payments Map can then support context selection, generated help, policy evaluation, or later workflows. Chapter 9 uses that operating memory while selecting recurring maintenance; Chapter 13 later examines the stronger boundary where a selected Map claim becomes an enforceable constraint. Synchronization prepares that boundary, but does not create it automatically.