Split the API snapshots: runner crate, api-vs-rest

[blooop]

Question

Implement the snapshot re-scope decided in "Re-scope the public-API snapshots": add a checked-in cargo public-api snapshot for devlaunch-runner (its whole surface currently enters core's snapshot as the one unexpanded glob at public-api.txt:2301), and split devlaunch-core's snapshot into an api-only file (the frozen wf promise; a diff is a breaking change by definition) and a rest file (routine tripwire over the binary surface, regenerated freely). Update the public-api CI job (.github/workflows/ci.yml:397-419) to check all three, keeping the pinned cargo-public-api 0.52.0 and the -ss rationale. While there: tidy the 2 bare-pub allow(dead_code) items (flows/repo_manager.rs:389 WrongRepoLock, domain/metadata.rs:313 region) where a demotion survives the build. Document regeneration somewhere findable outside the CI error string.

Blocks #314, #316, and the two api::Launch builds, so the snapshot files move once.

[blooop]

breadcrumb: entering building — wf-tdd stage subagent launched (manager: wf-mid run working map #299).

[blooop]

breadcrumb: building the #312 decision as specified. Three snapshots where there was one: devlaunch-runner gets its own cargo public-api snapshot (its surface today hides behind core's one unexpanded glob row), and core's splits into an api-only file (the frozen wf promise — a diff there is a breaking change by definition) and a rest file (routine tripwire over the binary surface). The split filter lives in one regeneration script that the CI job and the docs both point at, so the classification is single-sourced. Seams I will test at: (1) the partition invariant — every row of the api file is a devlaunch_core::api declaration and no row of the rest file is, held by unit tests over the checked-in files; (2) the runner snapshot pins the Runner/Outcome surface, held by a test that the snapshot exists and carries the trait; (3) the CI job diffs all three against fresh generation, pinned cargo-public-api 0.52.0 on nightly, -ss rationale kept. The 'tidy the 2 bare-pub allow(dead_code) items' side-task: measured against today's tree, both anchors (WrongRepoLock; the metadata region) are imported by name in the dl crate, so no demotion survives the build — the nearby allow(dead_code) attributes belong to pub(crate)/private members already. Will record the measurement in the PR rather than force a change the ticket conditioned away.

[blooop]

breadcrumb: resuming after the killed attempt; starting clean on branch wayfinder/devlaunch-338. Building the #312 decision unchanged, at the three seams the earlier breadcrumb named: (1) the partition invariant over the two checked-in core files — every row of the api file names devlaunch_core::api, no row of the rest file does, the two disjoint and both anchored on a known row; (2) the runner crate carries its own snapshot, pinned by a test that it exists and names the Runner trait and Outcome; (3) one regeneration script owns the split filter, and the CI job checks all three files by running that script into a scratch tree and diffing — so CI never re-implements the classification. Local constraint recorded up front: this container has no nightly rustdoc, so the two core files are derived by the filter from the checked-in snapshot (exact, it is a line partition), and the runner snapshot is the one file the first CI run has to prove.

[blooop]

breadcrumb: built and pushed as PR #347 — the snapshot re-scope, landed once so the tickets behind it can move. Three checked-in surfaces where there was one: the frozen api promise (37 rows, a diff there is a breaking change by definition), the freely regenerated rest, and the runner crate’s own seam, which until now entered core’s snapshot as a single unexpanded glob row. One regeneration script owns the classification, the pinned tool version and the -ss choice; the CI job runs that script into a scratch tree and diffs all three rather than re-implementing the filter, and README now carries the regeneration story so a red tick is not the only place it is written down. The split is verified rather than derived: a nightly plus the pinned cargo-public-api were installed in a scratch prefix, all three files generated for real, and the union of the two core files came out byte-identical to the snapshot this branch replaces. The conditional dead-code tidy is closed by measurement, not by an edit — the one bare-pub anchor is named by the rendering layer, and demoting it fails the build with E0603; the other anchor is already pub(crate).

[blooop]

breadcrumb: CI has proven the snapshots on the real nightly — the public-api job runs the regeneration script and finds all three files unchanged, so the runner snapshot and the two halves of core are confirmed rather than asserted. ci, rust, rust-coverage, packaging and prek are green too; only the real-container e2e leg was still running when the build stage ended, and this branch changes no binary behaviour. One fix after the first push: the spell-check hook prefers "implementer" over "implementor".

[blooop]

breadcrumb: build → in review. PR #347 pushed; every check green including gate and the real-container e2e leg that was still running when the builder finished. Handing to a fresh wf-review context.

Note for the map: this ticket gates #314, #316, #339, #340 and #346, and those edges clear on merge, not on approval — so they stay blocked until a human merges #347.

[blooop]

breadcrumb: in review → review posted on #347. Verdict Comment: Standards pass-with-nits, Spec pass-with-one-correction. The guard holds where it matters — the two core files are a byte-exact line partition of the snapshot they replace, all three files match generator output exactly (regenerated for real on nightly + cargo-public-api 0.52.0, not taken on trust), and the tripwire was made to fire on each of the three surfaces including the runner seam that previously moved nothing. Reclassifying a frozen row into the tripwire file is caught by the new partition test, verified by doing it. Three fixes asked for, none a hole in the guard: (1) public-api-snapshots.sh truncates a checked-in snapshot to 0 bytes when its own no-rows-matched guard fires — write-then-mv; (2) a relative DEST argument breaks on the cd — absolutise first; (3) the promise file holds declarations at the api path only, so Launch::new/Launch::run/CommandContext::new/DevcontainerPath::as_str and every derived impl on the promised types sit in the "routine" file — lib.rs:45-46 and the README table assert more than the filter delivers, so correct the prose (a wider filter is its own ticket). Node is needs attention for a wf-tdd fix-up push. Not merged — merge stays human, and this ticket's edges to #314/#316/#339/#340/#346 clear on merge.

[blooop]

breadcrumb: in review → changes requested, routed back to building. Both axes pass on their own terms, but the review's own probing turned up one finding that goes to the point of the ticket and two that are latent footguns.

The promise file does not yet guard the promise. cargo public-api renders methods and impls only at a type's canonical path, so a devlaunch_core::api\b grep cannot see them. The generator emits 79 contiguous api rows; the filter keeps 37. The other 42 include Launch::new and Launch::run — the only constructor and method of the central promised type — plus CommandContext::new, DevcontainerPath::as_str, and every derived trait impl on the four promised types. Renaming Launch::run leaves public-api.api.txt byte-identical.

agent-decided (long-term maintainability): the file as built matches #312's literal "37 lines today", so this PR is not wrong against its ticket — but lib.rs:45-46 and the README table assert the converse of what actually holds, and a tripwire that is trusted and silently does not fire is worse than none. So: the prose overclaim is fixed in this PR (that class of claim is the exact thing map #299 exists to close, and shipping a fresh one would be self-defeating), and widening the filter to cover promised types' canonical-path rows is its own ticket, because it is additive and holding #347 for it would keep five dependent tickets blocked behind a strict improvement.

Escalation was considered and declined: widening the filter fulfils #312's intent rather than contradicting it, and it is cheap to reverse. Flagged to the human regardless, since the decision was theirs.

Two latent bugs to fix here as well:

• scripts/public-api-snapshots.sh:88,93 — the shell truncates the redirect target before grep runs, so when the script's own "no rows matched" guard fires it leaves the checked-in public-api.api.txt at 0 bytes. Reproduced by the reviewer: 3376 bytes → 0. Only one of the four partition tests would catch it.
• A relative DEST argument breaks (mkdir -p runs in the caller's CWD, the redirects run after cd rust). CI escapes it only because $RUNNER_TEMP is absolute.

The reviewer's --print-files suggestion is worth taking if cheap — the three-file list is duplicated in ci.yml and merely enforced by the Python test, where the pin and filter are properly single-sourced.