Public Reveal Walkthrough

Executable bindings for the ten-minute tour

public_reveal_walkthrough makes the first-run ten-minute tour executable by binding each step to evidence in the public clone, blocking if any step points at nothing the system runs. public_reveal_walkthrough checks the short guided tour Microcosm shows a first-time reader, and it binds that tour to evidence that exists in the public clone. The reader is promised a ten-minute path: run a command, look at local state, follow one route through patterns, work, events, and evidence, then read the result record and the scope limit behind it. This component makes that promise executable. It blocks if any step on the path points at nothing the system actually runs.

It reads two inputs, a first-wave fixture carrying the walkthrough, evidence map, claim floor, and four rejection cases, and an exported bundle of copied public source bodies, writing metadata-only records from both. It reads two inputs. The first-wave fixture under fixtures/first_wave/public_reveal_walkthrough/input/ carries the declared walkthrough, an evidence map, a claim floor, and four rejection cases. The exported bundle under examples/public_reveal_walkthrough/exported_public_reveal_bundle/ carries copied public source bodies with a manifest. The component runs both and writes metadata-only result records: public_reveal_walkthrough_result.json, ten_minute_reveal_board.json, public_reveal_validation_receipt.json, and public_reveal_walkthrough_fixture_acceptance.json.

A pass is bounded validator evidence rather than a launch, with the scope limit stated once under Scope limit. A pass is bounded validator evidence, not a launch. The scope limit is stated once, under Scope limit.

Purpose

Accounting, not a pitch

A walkthrough drifts into a pitch as soon as commands and evidence refs are dropped, so this component treats the first-run path as accounting where each step points at real state, work, and records. A walkthrough drifts toward a pitch the moment it is allowed to. Dropping the commands and the evidence refs is the easiest way to make a first run look more impressive and prove less. This component removes that option. It treats the first-run path as an accounting exercise rather than a narrative: a command produces local state, a route points at work and events, an evidence ref points at a record, and a scope limit sits beside any impressive-looking total.

The real-lane witness

The fixture does not pass on its own paperwork; it passes only when the exported bundle runs underneath it with copied bodies digest-verified, so the reveal cannot describe a runnable path that is broken. The stricter part is the real-lane witness. The fixture does not pass on its own paperwork. It passes only when the exported bundle actually runs underneath it, with its copied source bodies present and digest-verified. So the reveal cannot describe a runnable path while the runnable path is broken. That is the quiet failure mode of every quick-start that says more than it can execute.

How it works

The two entrypoints share one core builder, _build_result, and differ in what they require. The two entrypoints share one core builder, _build_result, and differ in what they require.

The fixture lane and its three validators

run calls _build_result, which scans inputs and runs three validators for the density floor, the evidence map, and the claim floor, passing only when all pass with no missing rejection and a clean scan. run is the fixture lane. It calls _build_result with include_negative set true, then gates the outcome on a witness, then writes the record set. _build_result loads the fixture payloads, runs the secret-exclusion scan over every input path with scan_paths, and calls three validators. validate_walkthrough enforces the density floor: at least five steps, at least four distinct commands, and at least four evidence refs, otherwise it emits PUBLIC_REVEAL_DENSITY_FLOOR_MISSING. validate_evidence_map checks the evidence map. validate_claim_floor requires the declared product-loop phrases to appear in the public claim and rejects the overclaim cases. The builder sets status to pass only when no expected rejection case is missing, the secret scan has zero blocking hits, and all three validators pass.

Gating the fixture on the real-lane witness

_fixture_real_lane_witness reruns the exported bundle with the manifest required, and _attach_real_lane_witness forces the fixture result to blocked if that witness did not pass. After the builder, run calls _fixture_real_lane_witness, which runs the exported bundle through _build_result with the source-module manifest required, so the copied bodies are digest-checked for real. _attach_real_lane_witness reads that witness: if it did not pass, the fixture result is forced to blocked, real_runtime_receipt is set false, and a PUBLIC_REVEAL_REAL_LANE_WITNESS_REQUIRED or ...BLOCKED finding is added. Then write_receipts emits the records.

The bundle lane digest-verifies each module

run_reveal_bundle makes the source-module manifest mandatory, and _source_module_manifest_result checks each module's class, copied-and-metadata-only flag, existence, three digest fields, and required anchors, blocking on any mismatch. run_reveal_bundle is the exported-bundle lane. It calls _build_result with include_negative false, which makes the source-module manifest mandatory. _source_module_manifest_result walks each declared module: the material class must be one of PUBLIC_SAFE_SOURCE_BODY_CLASSES, the row must mark the body copied and kept out of the record, the target file must exist, all three digest fields must match the recomputed _sha256, and every declared anchor must be present in the copied text. Any mismatch becomes a finding and the manifest status goes to blocked. _source_open_body_import_summary folds the verified modules into a count and class list for the record.

flowchart TD Fixture["First-wave fixture walkthrough + claim floor + 4 negatives"] Bundle["Exported bundle 5 copied source bodies + manifest"] Build["_build_result load, scan, validate"] Witness["_fixture_real_lane_witness rerun bundle, digest-check bodies"] Records["metadata-only records result, board, validation, fixture"] Ceiling["Scope limit no launch, hosting, or private equivalence"] Fixture --> Build Bundle --> Witness Build --> Witness Witness --> Records Records --> Ceiling

Negative cases

Four inputs that must stay rejected

The fixture ships four inputs that must stay rejected, and if any stops producing its finding the reveal is no longer bounded enough for a cold reader. The fixture ships four inputs that must stay rejected. If any of these stops producing its finding, the reveal is no longer bounded enough for a cold reader.

A missing case blocks the run

The four expected cases live in EXPECTED_NEGATIVE_CASES, and a run is blocked if any is absent from the observed set. The four expected cases are declared in EXPECTED_NEGATIVE_CASES; a run is blocked if any of them is absent from the observed set.

Prior Art Grounding

First-run CLI, progressive disclosure, provenance

The path follows first-run CLI and progressive-disclosure practice for one runnable command and a bounded first route, and borrows provenance and tracing work for walking from artifact to source, record, and linked work. The path follows first-run CLI and progressive-disclosure practice. The Command Line Interface Guidelines motivate a single runnable command, worked examples, discoverable next steps, and machine-readable output. Nielsen Norman Group's progressive disclosure motivates showing the bounded first route before expanding into full drilldowns. The evidence walk borrows from provenance and tracing work: W3C PROV for moving from artifact to source and record, and OpenTelemetry traces for representing a causal chain as inspectable linked work.

Validation Result record Path

Reader validation without durable writes

PYTHONPATH=src ./repo-pytest tests/test_public_reveal_walkthrough.py -q --basetemp=/tmp/microcosm_public_reveal_walkthrough_pytest --ignore-host-pressure
./repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus

What the two commands check

The focused suite covers the fixture path, exported bundle, digest checks, and four negative cases, and a pass means the density floor was met, bodies verified, overclaims rejected, and records metadata-only for this fixture and bundle only. The first command runs the focused suite over the fixture path, the exported bundle, digest checks, and the four negative cases. The second confirms the paper-module corpus still resolves. A pass means the walkthrough met the density floor, the copied bodies verified, the overclaims stayed rejected, and the records stayed metadata-only for this fixture and this bundle only.