Re-deriving projections

A generated map is useful because it saves a reader from opening every source card. It becomes a liability when someone maintains the map as though it were another authored record. The card can change while the map stays plausible, and the project now has two answers to the same question.

Coldstart's answer is re-derivation. Authored sources own the facts. A generator scans them, constructs the complete expected projection, and compares that result with the bytes currently on disk. Drift is repaired by changing the source when necessary and running the generator again, not by reconciling two supposedly canonical files by hand.

[Visual 7.2 — The right panel of the section frame, enlarged into two parallel lanes. Upper lane: "authored warehouse cards + room structure" enters "scan and validate", then "render every warehouse map", then a diamond labelled "byte-equal to disk?". Lower lane: "authored capability cards" enters "scan and validate", then "render routing rows + index", then the same byte-equality diamond. Each diamond has three exits with identical labels: "yes — current", "no — --check reports stale without writing; write mode replaces the projection", and "source unreadable — exit 2, write no partial projection". A return arrow from every stale output points only to its authored source. A footer reads "generated projection: replaceable view, never a second source of truth".]

The source owns the meaning

The warehouse projection begins with authored knowledge cards and their room structure. The generator scans that structure and computes the complete set of top-level and room maps that should exist. It does not decide how to split a crowded room, move a card, or rewrite a decision. Those are judgment calls in the authored layer.

The routing projection begins with authored capability cards. Its generator scans the library and computes two machine-facing views: compact routing rows and an index used to find matching material. It does not invent a card, add a missing facet, or decide that two capabilities overlap. A human changes the card contract; the generator only re-expresses it.

Both lanes therefore have one-way ownership. Source changes may change the projection. A surprising projection can reveal that a source is malformed or says something unexpected. But editing the projection does not change the source's meaning and cannot become the supported repair.

Regeneration is whole, not incremental guesswork

Each tool scans its complete authored subject and renders the expected output from scratch. That matters because an incremental patch would need its own memory of prior state: which row belonged to a removed card, which count changed when a room moved, or which index entry a renamed facet used to own. That memory would become another source of drift.

Whole regeneration is simpler. The current source set determines the entire desired view. Running the same generator twice against unchanged sources is idempotent: after the first successful write, the second run finds the same bytes already present.

The warehouse generator also distinguishes mapping from organization. It may re-list rooms and cards, but it never creates a room, moves a card or decides that a box has become too large. The routing generator similarly projects card fields without deciding their quality. Mechanical re-derivation stops at the judgment seam.

The comparison is byte-for-byte

After rendering, each generator reads the existing output as bytes and compares it with the expected text. It does not rely on a parser that normalizes line endings or whitespace before comparison.

That strictness is intentional. A generated file whose line endings changed can remain permanently different from the form the generator promises to write, even if a casual text read hides the difference. Byte comparison makes that drift observable. Successful writes use the promised line ending, so a later check converges on exact equality.

Byte equality proves a narrow fact: the stored projection matches this generator's rendering of the sources it successfully scanned. It does not prove the source is correct, current or sufficient for the reader's decision.

Check-only mode observes without repairing

Both tools have a check-only mode. They perform root resolution, source scanning, validation, rendering and byte comparison exactly as the writer does. When an expected output differs, they name the stale projection and return exit 1. They do not create a missing file or overwrite a differing one.

That makes check-only mode suitable for a gate. It answers “would regeneration change a machine-owned view?” without changing the evidence during the question. A clean check returns exit 0. A stale check returns exit 1. The operator can then inspect the source change and run write mode when the new projection is intended.

Write mode follows the same comparison. It writes only outputs whose bytes differ and reports which ones moved. If every expected file is already current, it reports that there was nothing to change. The report therefore distinguishes a real re-derivation from a ceremonial command that happened to touch nothing.

Unreadable input is broken generation, not staleness

Staleness means the generator successfully understood the authored sources and computed bytes that differ from disk. Malformed input is different: the tool cannot know what a complete projection should contain.

If a warehouse card or structure is unreadable, the map generator reports the defects and returns exit 2 before writing. If a capability card is unreadable, the routing generator does the same. In both cases, rendering around the bad source would silently omit it and produce a partial view — the exact drift the mechanism exists to prevent.

Root-resolution failure is also exit 2. A command that cannot establish which Coldstart tree it is operating on cannot safely declare its outputs current or stale.

There are two honest empty cases. A tree with no warehouse has no warehouse maps to derive, and a tree with no capability library has no routing projection to derive. The tools report that there is nothing to do. That is different from a present source area that contains malformed material.

A practical regeneration receipt

When a projection changes, keep enough context to answer four questions:

1. Which authored source change caused the new rendering?
2. Which generator and source revision produced it?
3. Did check-only mode report staleness before any write?
4. Did the final comparison return current after regeneration?

The first question prevents generated output from becoming the explanation for itself. “The index changed because the index changed” is not provenance. The answer should point back to an authored card, a room move, or another source-level change a reviewer can judge.

The last question catches partial maintenance. A generator may report the files it wrote, but a fresh check-only comparison is the clean receipt that the stored bytes now equal a complete re-rendering.

Where this sits in wider upkeep

The pinned maintenance routine starts by regenerating these projections, then runs strict self-CI, re-measures evaluation envelopes, and reviews stale open work and evidence. Re-derivation is one step in that routine, not a name for all of it.

This page deliberately stops before evaluation, staleness policy and cleanup. Those jobs involve different evidence and judgment. Folding them into “refresh the generated files” would make a mechanical projection command appear to maintain the health of the whole harness.

What this page does not claim

Re-derivation does not make generated output infallible. The generator can contain a bug, and the authored source can be wrong. Exact byte parity proves agreement between those two surfaces under the observed implementation; it does not independently validate either one's meaning.

The page also does not authorize edits to authored cards, room boundaries or capability facets. Those remain human-owned changes. The generator's job is to make their machine-owned views replaceable, deterministic and unable to drift quietly.

Next

The next section keeps machine installation, project activation and personal calibration separate: setup.

How current this page is

Checked on 10 August 2026 against the pinned product revision's maintenance instruction, warehouse map generator, routing-projection generator and hermetic generator tests. To ask whether a claim here still holds, or to report one that does not, write to [email protected].