Cold-Reader Route Map

Route map checks

The route map checks a newcomer's first ten minutes, confirming each first-run step's command, docs reference, and evidence record resolves against real source, not prose. cold_reader_route_map checks the guided path a newcomer follows in their first ten minutes with Microcosm. It reads a public route map whose rows bind each first-run step to a runnable command, a public documentation reference, and an evidence record, then it confirms that every one of those bindings resolves against real source instead of prose.

Takes three fixture

It takes three fixture files plus an optional copied-source manifest and emits metadata-only findings, a route board, validation records, and a card carrying ids, refs, and digests only. The component takes three fixture files (route_map.json, route_receipts.json, route_policy.json) plus an optional copied-source manifest, and emits deterministic findings, a route board, validation records, and a compact card. Every emitted record is metadata-only: it carries route ids, commands, refs, digests, and body_in_receipt: false markers, never inlined source or live state.

Source replay is what lifts it above field-presence checking: an unrunnable command, an unresolved docs heading, or a non-passing evidence ref each blocks the route. The discipline that makes it more than a field-presence checker is source replay. A route that promises a command the system does not actually run is blocked, as is a docs reference that resolves to no heading and an evidence ref that does not open a passing record. That is the failure a hand-written quick-start guide slides into the moment the commands change underneath it.

Purpose

What to run first, with evidence

A cold reader should not reverse-engineer the path from a README, so the route map answers what to run first and what evidence shows that path is wired. A cold technical reader should not have to reverse-engineer the product path from a long README or a raw tree of result files. The route map answers one question: what do I run first, and what evidence shows that path is wired?

Each row as a claim-boundary check

A prose route map lists commands nothing re-checks; this one treats each row as a claim-boundary check so the trusted sequence stays tied to re-runnable source. A loose route map answers that question with prose. It lists impressive commands, and nothing checks that they still exist or that their supporting records still pass. The route map here treats each row as a claim-boundary check, so the sequence a newcomer trusts stays tied to source that a test can re-run.

How it works

Fixture and exported-bundle entrypoints

run builds the fixture with negative cases and writes the record set, while run_route_map_bundle runs the same builder with negatives off and the copied-source manifest required. run is the fixture entrypoint. It calls _build_result with negative cases included, then writes the result, board, and validation records, plus a cold_reader_route_map_fixture_acceptance_v1 record when the caller passes acceptance_out. run_route_map_bundle is the exported-bundle entrypoint. It runs the same builder with negative cases off and the copied-source manifest required, so the bundle proves replay shape from public inputs alone.

_build_result joins four checks and a scan

_build_result runs four independent checks plus a secret-exclusion scan, passing only when no check files a blocking finding and the scan reports no blocking hit. _build_result assembles four independent checks plus a secret-exclusion scan over the inputs, and passes only when none of the four checks files a blocking finding and the scan reports no blocking hit.

Required routes and front-door ordering

_positive_findings requires each route to name a command, docs refs, and a result record ref, and the front-door sequence to match live first-screen strings in ordinal order. _positive_findings walks the routes named in route_policy. Each required route must exist, name a command, carry docs_refs, and point at a result record ref. The first-run sequence must start with the three front-door routes in FRONT_DOOR_ROUTE_COMMANDS (tour_project, status_card, proof_lab), those front-door commands must match the live first-screen strings, and the whole sequence must be present and ordinal sorted. A gap, a missing field, or a drifted front-door command becomes a finding.

Replaying commands, refs, and signals against source

_route_source_replay_result builds a source corpus and blocks any command token, docs ref, result record ref, or claimed signal that does not resolve against real public source. _route_source_replay_result is the replay pass. It builds one text corpus from the copied source modules, a fixed set of public source refs, every route's docs refs, and every result record ref, then it tests each route against that corpus. _command_support splits a command into material tokens and blocks it if a token appears nowhere in the corpus. _document_ref_result requires each docs ref to resolve to a real public file and, when the ref names a heading anchor, to a real heading. _receipt_ref_result opens each result record ref and blocks it unless the file is JSON with status equal to pass. _mechanism_signal_support takes the human-readable signals a row claims to show and blocks the row if their terms are absent from the corpus.

The copied-body floor for the bundle

_source_module_import_result recomputes each copied body's digest against the manifest sha256, checks provenance anchors survive, and requires a copied_non_secret_macro_body exact-copy declaration. _source_module_import_result governs the copied-body floor used by the exported bundle. For each row in source_module_manifest.json it recomputes the file digest, compares it to the manifest sha256, checks that required provenance anchors survive in the copied text, and confirms the row declares copied_non_secret_macro_body with a material class and an exact_copy relation. A digest mismatch, a missing anchor, a body marked for a record, or an unsupported class each files a finding.

Negative findings evaluates

_negative_findings evaluates the five perturbed inputs and records the error code each one must raise, listed under Negative cases below. _negative_findings evaluates the five perturbed inputs and records the error code each one must raise, listed under Negative cases below.

flowchart TD Inputs["route_map, route_receipts, route_policy, manifest"] --> Positive["_positive_findings required routes, commands, docs refs, result record refs, order"] Inputs --> Replay["_route_source_replay_result commands and refs matched against the source corpus"] Inputs --> Modules["_source_module_import_result copied-body digests and anchors"] Inputs --> Negative["_negative_findings five rejection cases"] Positive --> Result["_build_result pass only when no blocking finding"] Replay --> Result Modules --> Result Negative --> Result Result --> Records["run and run_route_map_bundle write metadata-only records"]

Function to role:

Negative cases

Expected negative cases

EXPECTED_NEGATIVE_CASES names the five inputs the fixture must reject and the code each one raises. EXPECTED_NEGATIVE_CASES names the five inputs the fixture must reject and the code each one raises:

• missing_command_ref raises COLD_ROUTE_MISSING_COMMAND_REF: a route with no command cannot guide anyone.
• missing_receipt_ref raises COLD_ROUTE_MISSING_RECEIPT_REF: a route with no evidence ref is not backed.
• route_sequence_gap raises COLD_ROUTE_SEQUENCE_GAP: a sequence that does not start from tour_project is malformed.
• release_overclaim raises COLD_ROUTE_AUTHORITY_OVERCLAIM: a row that sets a key in OVERCLAIM_KEYS, such as release_authorized or whole_system_correctness_claim, is refused.
• private_source_leakage raises COLD_ROUTE_PRIVATE_SOURCE_FORBIDDEN: a row carrying a key in FORBIDDEN_PRIVATE_KEYS, such as private_source_body, proof_body, or provider_payload_body, is refused so a route card cannot become a disclosure channel.

If fixture run

If the fixture run does not observe one of these five, _build_result marks the run blocked for the missing case. If the fixture run does not observe one of these five, _build_result marks the run blocked for the missing case.

Reader-Specific Evidence Routing

Command order and evidence order kept together

The route map keeps a command order and an evidence order, so a reader sees the compact sequence first yet keeps each step's result record-ref and scope-limit context in drilldowns. The route map keeps two orders: the command order and the evidence order. A reader sees the compact command sequence first, then can open full drilldowns without losing the result record-ref and scope-limit context attached to each step.

The accepted path is:

1. plectis hello <project>
2. plectis tour --card <project>
3. plectis status --card <project>
4. plectis authority --card
5. plectis workingness --card
6. plectis legibility-scorecard
7. Read selected_route_id from the compact tour or status card.
8. plectis explain <project> <selected_route_id>
9. plectis observe --card <project>
10. plectis cold-reader-route-map run-route-map-bundle
11. plectis comprehend --component certificate_kernel_execution_lab

Full drilldowns stay available after the compact path is visible:

• plectis tour <project> for the full first-screen route tree.
• plectis compile <project> for project-state materialization detail.
• plectis proof-lab --out /tmp/microcosm-proof-lab for proof-lab component records.
• plectis serve <project> --host 127.0.0.1 --port 8765 for the local observatory.

Compact board must match the terminal row

A browser-first reader follows the same order, and the compact board must carry the same command ref, evidence ref, class, and scope limit as the terminal row, or it is a preview. A browser-first reader follows the same order in compressed form, and the compact board must carry the same command ref, evidence ref, evidence class, and scope limit as the terminal row, or it is a preview only.

Prior Art Grounding

Diataxis and literate programming lineage

The design follows Diataxis's task-shaped documentation and Knuth's literate programming, borrowing the ordered-reader pattern without turning documentation sequence into source authority. The component follows documentation systems that treat reader state and task shape as first-class. Diataxis separates tutorials, how-to guides, reference, and explanation so a reader is not pushed through one undifferentiated pile. Knuth's literate programming is the older anchor for writing an executable system for human comprehension as well as machine execution. The route map borrows the ordered-reader pattern of first command, evidence ref, evidence class, scope limit, and next drilldown, without turning documentation sequence into source authority.

Validation Result record Path

From microcosm-substrate/, reproduce this page's proof boundary with temporary records:

What a pass means here

A pass means the eleven-route fixture, the exported bundle, and the copied source-module digests all validated with no blocking finding and stay consistent with the source record and generated views. A pass means the eleven-route fixture, the exported bundle, and the copied source-module digests all validated with no blocking finding, and that this page stays consistent with its source record, generated diagram, and Atlas card.