Cold Clone Probe

Probe is first

The probe is the first script a fresh clone runs, checking whether it can bootstrap the first-wave contract from source without leaking anything private. cold_clone_probe is the first script a reader runs after cloning the public checkout. It answers one question: can this clone bootstrap the bounded first-wave contract from source, without leaking anything private, before the reader installs the package or reads the long component inventory?

Imports from src

It imports from src/, checks fixture inputs, scans for secrets, replays the pattern-binding fixture, and writes one ignored local record; a pass proves only the first bounded action. The probe imports the package from src/, checks that the first-wave fixture inputs are present, runs a secret-exclusion scan, replays the pattern-binding fixture, and then writes one small result record. That record is ignored local state, not a tracked artifact. A pass means the first local action from a fresh clone works and stays inside the public boundary. It is not an install proof, a launch proof, or a statement about the rest of the system.

Purpose

Pulling the first-step check to the front

A public checkout must prove its own first step, so the probe pulls the bootstrap check ahead of install or inventory into one command, one record, four typed failure modes. A public checkout has to prove its own first step. If the reader's first action is make install or a long tour of the component inventory, a broken or leaky bootstrap is discovered late and off to the side. The probe pulls that check to the front and makes it concrete: one command, one result record, four typed failure modes.

Why a bare import-and-ok is not enough

A probe that only imports and prints "ok" would pass on missing fixtures, an unavailable scan, or absent result records, so each failure gets a distinct blocked status and code instead. "Loose" here means a probe that only imports the package and prints "ok". That would pass on a clone that is missing its fixtures, or one whose secret scan is unavailable, or one where the pattern-binding result records never materialize. The probe refuses to call any of those a pass. Each is a distinct blocked status with its own code, so the reader learns which part of the bootstrap is wrong.

How it works

run_probe predicate and main wrapper

The proof predicate run_probe runs a fixed sequence and never raises, while the CLI wrapper main parses flags, writes the --emit record, and sets the exit code. The runtime is one file, src/microcosm_core/cold_clone_probe.py. The proof predicate is run_probe(root, suite, emit_ref). It runs a fixed sequence over the checkout root and returns a result dict; it never raises. The CLI wrapper main parses --suite and --emit, calls run_probe on the current directory, writes the returned record, and exits 0 on pass or 1 otherwise. The one file that writes the --emit record is main, not run_probe.

A reproducible command stamp before four gates

run_probe stamps the base record with a reproducible ./bootstrap.sh command quoted through shlex.quote, then walks four gates in order. run_probe builds a metadata-only base record stamped with the reproducible command string from _bootstrap_command(suite, emit_ref), which returns ./bootstrap.sh --suite <suite> --emit <path> with both arguments quoted through shlex.quote. It then walks four gates in order:

Gate order and result record mirroring

The gates run suite, inputs, secret scan, then replay so the boundary check gates fixture work, after which _mirror_missing_pattern_receipts copies missing result records into their canonical slots. The order matters. run_probe checks the suite first, then REQUIRED_INPUTS, then the secret scan, and only then the pattern-binding replay. The scan runs before replay on purpose: the boundary check gates the fixture work, not the other way around. After validate_pattern_binding writes into the scratch directory, _mirror_missing_pattern_receipts(root_path, source_dir) copies each canonical result record that is absent at the root but present in the scratch output. It skips destinations that already exist and sources that are not files, using _path_exists and _path_is_file, two probes that swallow OSError and report missing rather than crashing on a fresh clone with odd permissions. When it copies the validation-result result record it rewrites that file's receipt_paths field to the canonical PATTERN_RECEIPTS list, so the mirrored record points at the stable slots.

What a pass record carries

A pass record lists the emit path, the five result record refs, and the secret-scan summary with no private bodies, also aliased under private_state_scan for older readers. A pass record lists the emit path first, then the five pattern-binding result record refs, and carries the secret-exclusion scan summary with no private bodies copied in. The scan summary is also exposed under private_state_scan as a compatibility alias for older readers.

flowchart TD A["Fresh public checkout"] --> B["run_probe(root, suite, emit_ref)"] B --> C{"suite in SUPPORTED_SUITES?"} C -- no --> X1["blocked_invalid_input UNKNOWN_COLD_CLONE_SUITE"] C -- yes --> D{"REQUIRED_INPUTS present?"} D -- no --> X2["blocked_dependency_missing MISSING_FIXTURE_INPUT"] D -- yes --> E["validate_secret_exclusion_scan"] E -- raises --> X3["blocked_command_unavailable COMMAND_UNAVAILABLE"] E -- status not pass --> X4["blocked_secret_exclusion SECRET_EXCLUSION_SCAN_BLOCKED"] E -- pass --> F["validate_pattern_binding + mirror"] F -- fail or missing --> X5["blocked_dependency_missing MISSING_PATTERN_BINDING_RECEIPT"] F -- all present --> P["status pass emit ref + five result record refs"]

Negative cases

Run probe never

run_probe never raises. run_probe never raises. Every failure is a typed record the reader can read:

• blocked_invalid_input with code UNKNOWN_COLD_CLONE_SUITE: the requested suite is not first-wave. It also returns the supported list.
• blocked_dependency_missing with code MISSING_FIXTURE_INPUT: one or more of REQUIRED_INPUTS is absent. The record names the missing files.
• blocked_command_unavailable with code COMMAND_UNAVAILABLE: the secret scan raised, so the boundary cannot be checked. The exception text is recorded.
• blocked_secret_exclusion with code SECRET_EXCLUSION_SCAN_BLOCKED: the scan ran but did not pass. The scan summary is attached, without leaking findings.
• blocked_dependency_missing with code MISSING_PATTERN_BINDING_RECEIPT: the pattern-binding validator did not pass, or one of the five PATTERN_RECEIPTS is still absent after mirroring. The record names the missing result records.

Prior Art Grounding

Reproducible builds, twelve-factor, clean-checkout CI

The shape borrows from reproducible builds, the twelve-factor dependency rule, and clean-checkout CI, applied to one bounded first action from source. The shape borrows from three public practices. Reproducible builds recreate outputs from declared sources and a constrained environment (reproducible-builds.org). The Twelve-Factor dependency rule declares dependencies rather than relying on ambient system packages (12factor.net). Clean-checkout CI on hosted runners is the common way to prove a fresh clone builds and smoke-tests (GitHub Actions). The probe keeps the clean-checkout, declared-input, gated shape and applies it to one bounded first action from source.

Validation Result record Path

Run ./bootstrap.sh from the public root. Use --dry-run first to print the exact command and the ignored result target without writing anything, then run it for real and check the focused tests:

./bootstrap.sh --dry-run
./bootstrap.sh
PYTHONPATH=src ../repo-pytest \
  tests/test_cold_clone_probe.py \
  tests/test_bootstrap_script.py \
  tests/test_public_entry_docs.py \
  -q --basetemp /tmp/microcosm-cold-clone-probe

The result record and what green pytest means

The normal run writes an ignored result record, and a green pytest line means the predicate, wrapper, and public-entry docs agree, though a pass installs nothing and certifies no launch. The normal run writes ignored .microcosm/cold_clone_probe.json evidence with status=pass, the five public result record refs, and the secret-scan summary. Pass --emit <path> only to refresh an intentional local target; the default stays ignored local state. A green pytest line means the predicate, the root wrapper, and the public-entry docs all agree with the current checkout. These are the validation result records for this module; a pass here does not install the package, certify launch, or aggregate any wider coverage.