Repository navigation
028: Complete Underlay local Oxide routing and Builds scratch policy - #61
Conversation
Remove the rust:*:cargo selector siblings now that every ordinary local Rust route runs through Oxide, and state the operator escape plainly. Run Tarpaulin through oxide exec -- cargo tarpaulin with unchanged arguments, thresholds and exit handling, and prove that dispatch with fake tools. Place agent and proof scratch in unique directories below /Volumes/Builds/scratch/underlay with an unavailable-volume refusal, and record the routing and scratch rules in the owning contract and AGENTS guidance instead of the consumer guides, CI examples or historical records.
inflatable-tester
left a comment
There was a problem hiding this comment.
Request changes at dab4a5a.
Ordinary local routing is in good shape: :cargo siblings are gone from the effective Effigy catalog, Tarpaulin goes through oxide exec -- cargo tarpaulin --workspace --out Xml, fake-tool proof covers dispatch/args/stdout/stderr/exit and the missing-tool path, agent/proof scratch sits on Builds with unavailable-volume refusal, and contract 123 records the ruling. Covering Effigy checks passed. One current THIS-workspace guide recipe still tells maintainers to run Cargo in this checkout.
Blocking
1. Maintainer workflow in 041 still runs Cargo against Underlay crates
File: docs/guides/041-rust-module-splitting.md lines 95–96
This guide is current THIS-workspace instruction: it defines how to split large Rust source files in Underlay crates. Steps 5 and 6 still say:
cargo check -p <crate> --all-features
cargo test -p <crate> --all-features
Failure case: follow the guide after a split and run those commands. Oxide is bypassed and build output lands in the checkout target/, which is why the :cargo selectors were removed.
This PR already rewrote the matching crate test comments to oxide test. Spell Oxide here too (oxide check / oxide test, or effigy rust:check / effigy rust:test).
Residual Cargo uses by class
Classified uses. Only 041 above is unexplained current THIS-workspace guidance.
-
Ordinary local routes (this checkout):
effigy.tomlrust:build|check|clippy|testandfmt:rust*spelloxide. Coverage wrapper:oxide exec -- cargo tarpaulin --workspace --out Xml(innercargobelongs to Tarpaulin). Presence check and install hint keep thecargo-tarpaulinbinary name. Effective catalog:rust:check:cargo,rust:clippy:cargo, andrust:test:cargoare undefined.rust:checkplansoxide check --workspace --all-features. -
Hosted CI:
.github/workflows/rust.ymlstill runscargo fmt/clippy/build/test(untouched). Guide CI snippets indocs/guides/130-testing.mdanddocs/guides/150-ci-cd.mdkeep Cargo. -
Generic consumer recipes:
cd apps/api && cargo testindocs/guides/README.md; consumer structure/testing/backend recipes in020,040,130,070,078,185; consumer templatestemplates/scripts/setup.shandreset-db.sh; contract 022 API-package minimum examplescargo build/cargo check.skills/underlay-buildnow falls back to Oxide for Underlay-based apps. -
Cargo as subject or metadata:
cargo-tarpaulin,oxide install cargo-tarpaulin,effigy deps link cargo,cargo:build-script directives, Cargo.toml schema,~/.cargo/binPATH notes in prerequisites. -
Product / fixture / live-tool behaviour:
scripts/check-env-manifest.shstill uses genericmktemp -dfor key-name extraction. This is a consumer-runnable live env check; binding it to/Volumes/Buildswould impose this host's scratch rule on other consumers. Product-managed temp, left as-is. -
Historical records: upgrade notes and sweeps that quote past
cargo test/cargo checkruns, includingdocs/guides/190-upgrade-compatibility.mdanddocs/sweeps/*. -
Scratch:
scripts/auth-webauthn-manual-dossier.sh,scripts/test-consumer-conformance-fixtures.sh, andrust/scripts/test-check-coverage.shuse unique dirs under/Volumes/Builds/scratch/underlay/and refuse when the volume is missing. No HOME override. The dossier script remains syntax/placement only (live consumer qualification). Oxide init block inAGENTS.mdis preserved.
Checks (once, Effigy)
effigy check:coverage-route— pass (fake-tool Oxide dispatch, threshold, stream passthrough, missingcargo-tarpaulin)effigy check:consumer-conformance-fixtures— pass (Builds scratch placement)effigy qa:docs— pass (links, agent-defaults, contracts local-paths)effigy fmt:rust:check— pass
No Rust build, Tarpaulin, install, or app runtime. Head left clean at dab4a5a.
Review verdicts
| ID | Subject | Verdict | Evidence | Note |
|---|---|---|---|---|
cargo-selectors-removed |
rust:check:cargo / rust:clippy:cargo / rust:test:cargo absent from effective catalog | pass |
effigy --json rust:check:cargo --plan, rust:clippy:cargo --plan, and rust:test:cargo --plan each fail with task not defined in catalog underlay. rust:check plans oxide check --workspace --all-features. | |
tarpaulin-oxide-exec |
check-coverage.sh Oxide exec route preserves args and behaviour | pass |
rust/scripts/check-coverage.sh line 28: oxide exec -- cargo tarpaulin --workspace --out Xml. Missing-tool hint retained. grep empty-match uses || true so unparsable output reaches the existing parse-failure path. | |
coverage-route-fake-tool-proof |
effigy check:coverage-route fake-tool dispatch proof | pass |
effigy check:coverage-route exit 0: Oxide argv exec/--/cargo/tarpaulin/--workspace/--out/Xml, threshold pass/fail, combined stream passthrough, missing cargo-tarpaulin refuses before oxide. Builds scratch, no real Tarpaulin/Cargo/Oxide. | |
scratch-placement-builds |
Agent/proof scratch under /Volumes/Builds/scratch/underlay with volume refusal | pass |
test-check-coverage.sh, test-consumer-conformance-fixtures.sh, and auth-webauthn-manual-dossier.sh mktemp unique dirs under /Volumes/Builds/scratch/underlay and exit 1 when the directory is missing. check-env-manifest.sh left on generic mktemp as consumer-runnable product temp. effigy check:consumer-conformance-fixtures exit 0. | |
this-workspace-guide-recipes |
Current THIS-workspace guide recipes instruct Oxide | fail |
docs/guides/041-rust-module-splitting.md lines 95-96 still say cargo check -p --all-features and cargo test -p --all-features for Underlay crates. Crate test comments in this PR already use oxide test. Consumer recipes, CI, and historical records remain classified Cargo. | |
docs-and-format-checks |
qa:docs (including agent-defaults) and fmt:rust:check | pass |
effigy qa:docs exit 0 (links, agent-defaults, contracts local-paths, including contract 123). effigy fmt:rust:check exit 0. |
Review finding: docs/guides/041-rust-module-splitting.md is a current guide for this workspace's crates and still told readers to run cargo check/test -p <crate>. Name oxide instead, and classify explicitly historical guide checklists as historical evidence with a re-routing recheck trigger.
inflatable-tester
left a comment
There was a problem hiding this comment.
Approve at 9cbbe29.
Re-review of PR 61 after dab4a5a. The previous blocking finding is gone: docs/guides/041-rust-module-splitting.md steps 5–6 now spell oxide check -p <crate> --all-features and oxide test -p <crate> --all-features. Contract 123 now classifies historical guide checklists (example: 205-legacy-migration-framework.md) as evidence with a re-routing recheck trigger. Ordinary local routing, Tarpaulin Oxide exec, fake-tool proof, Builds scratch, and covering checks still hold at this head.
No worker-published source value cites review ID 5645382565. The follow-up commit names the 041 finding in prose; that is not an equality check against the stored verdicts.
Blocking
None.
Residual Cargo uses by class
Classified. No unexplained current THIS-workspace ordinary local Cargo route remains.
- Ordinary local routes (this checkout):
effigy.tomlrust:build|check|clippy|testandfmt:rust*spell Oxide. Coverage wrapper:oxide exec -- cargo tarpaulin --workspace --out Xml(innercargobelongs to Tarpaulin). Presence check and install hint keep thecargo-tarpaulinbinary name. Effective catalog:rust:check:cargo,rust:clippy:cargo, andrust:test:cargoare undefined.rust:checkplansoxide check --workspace --all-features. Crate ignored-test comments and 041 useoxide test/oxide check. - Hosted CI:
.github/workflows/untouched. Guide CI snippets indocs/guides/130-testing.mdanddocs/guides/150-ci-cd.mdkeep Cargo. - Generic consumer recipes:
cd apps/api && cargo testindocs/guides/README.md; consumer structure/testing/backend recipes in020,040,130,070,078,185,200; consumer templatestemplates/scripts/setup.shandreset-db.sh; contract 022 API-package minimum examplescargo build/cargo check.skills/underlay-buildfalls back to Oxide for Underlay-based apps. - Cargo as subject or metadata:
cargo-tarpaulin,oxide install cargo-tarpaulin, Cargo.toml schema,cargo:build-script directives, workspace-shape checks that readCargo.toml. - Product / fixture / live-tool behaviour:
scripts/check-env-manifest.shstill uses genericmktemp -dfor key-name extraction. Consumer-runnable live env check; binding it to/Volumes/Buildswould impose this host's scratch rule on other consumers. Product-managed temp, left as-is. - Historical records: upgrade notes and sweeps that quote past
cargo test/cargo checkruns, includingdocs/guides/190-upgrade-compatibility.md, plus guides that declare themselves a historical reference (docs/guides/205-legacy-migration-framework.md). Recheck trigger is recorded in contract 123. - Scratch:
scripts/auth-webauthn-manual-dossier.sh,scripts/test-consumer-conformance-fixtures.sh, andrust/scripts/test-check-coverage.shuse unique dirs under/Volumes/Builds/scratch/underlay/and refuse when the volume is missing. No HOME override. The dossier script remains syntax/placement only (live consumer qualification). Oxide init block inAGENTS.mdis preserved.
Checks (once, Effigy, this head)
effigy --json rust:check:cargo --plan/rust:clippy:cargo --plan/rust:test:cargo --plan— each fail: task not defined in catalog underlayeffigy --json rust:check --plan—oxide check --workspace --all-features(not executed; comment-only Rust, brief forbids a product build)effigy check:coverage-route— pass (fake-tool Oxide dispatch, threshold, stream passthrough, missingcargo-tarpaulin)effigy check:consumer-conformance-fixtures— pass (Builds scratch placement)effigy qa:docs— pass (links including contract 123, agent-defaults, contracts local-paths)effigy fmt:rust:check— passbash -non the four changed shell scripts;git diff --check origin/main...HEAD— pass
No Rust build, Tarpaulin, install, or app runtime. Repo has no QA groups. Head left clean at 9cbbe29.
Papercut, not blocking: rust/scripts/test-check-coverage.sh defines unused assert_not_contains. Effigy also warns that [scan.attention_markers] is retired v0.15 config; pre-existing, not introduced by this PR.
Review verdicts
| ID | Subject | Verdict | Evidence | Note |
|---|---|---|---|---|
cargo-selectors-removed |
rust:check:cargo / rust:clippy:cargo / rust:test:cargo absent from effective catalog | pass | effigy --json rust:check:cargo --plan, rust:clippy:cargo --plan, and rust:test:cargo --plan each fail with task not defined in catalog underlay. rust:check plans oxide check --workspace --all-features. | |
tarpaulin-oxide-exec |
check-coverage.sh Oxide exec route preserves args and behaviour | pass | rust/scripts/check-coverage.sh line 28: oxide exec -- cargo tarpaulin --workspace --out Xml. Missing-tool hint retained. grep empty-match uses | |
coverage-route-fake-tool-proof |
effigy check:coverage-route fake-tool dispatch proof | pass | effigy check:coverage-route exit 0: Oxide argv exec/--/cargo/tarpaulin/--workspace/--out/Xml, threshold pass/fail, combined stream passthrough, missing cargo-tarpaulin refuses before oxide. Builds scratch, no real Tarpaulin/Cargo/Oxide. | |
scratch-placement-builds |
Agent/proof scratch under /Volumes/Builds/scratch/underlay with volume refusal | pass | test-check-coverage.sh, test-consumer-conformance-fixtures.sh, and auth-webauthn-manual-dossier.sh mktemp unique dirs under /Volumes/Builds/scratch/underlay and exit 1 when the directory is missing. check-env-manifest.sh left on generic mktemp as consumer-runnable product temp. effigy check:consumer-conformance-fixtures exit 0. | |
this-workspace-guide-recipes |
Current THIS-workspace guide recipes instruct Oxide | pass | docs/guides/041-rust-module-splitting.md lines 95–96 now say oxide check -p --all-features and oxide test -p --all-features. Crate ignored-test comments use oxide test. Consumer recipes, CI, and historical 190/205 remain classified Cargo. | Supersedes the fail on this id in review 5645382565. |
docs-and-format-checks |
qa:docs (including agent-defaults) and fmt:rust:check | pass | effigy qa:docs exit 0 (links, agent-defaults, contracts local-paths, including contract 123). effigy fmt:rust:check exit 0. |
Review verdicts
| ID | Subject | Verdict | Evidence | Note |
|---|---|---|---|---|
cargo-selectors-removed |
rust:check:cargo / rust:clippy:cargo / rust:test:cargo absent from effective catalog | pass |
effigy --json rust:check:cargo --plan, rust:clippy:cargo --plan, and rust:test:cargo --plan each fail with task not defined in catalog underlay. rust:check plans oxide check --workspace --all-features. | |
tarpaulin-oxide-exec |
check-coverage.sh Oxide exec route preserves args and behaviour | pass |
rust/scripts/check-coverage.sh line 28: oxide exec -- cargo tarpaulin --workspace --out Xml. Missing-tool hint retained. grep empty-match uses || true so unparsable output reaches the existing parse-failure path. | |
coverage-route-fake-tool-proof |
effigy check:coverage-route fake-tool dispatch proof | pass |
effigy check:coverage-route exit 0: Oxide argv exec/--/cargo/tarpaulin/--workspace/--out/Xml, threshold pass/fail, combined stream passthrough, missing cargo-tarpaulin refuses before oxide. Builds scratch, no real Tarpaulin/Cargo/Oxide. | |
scratch-placement-builds |
Agent/proof scratch under /Volumes/Builds/scratch/underlay with volume refusal | pass |
test-check-coverage.sh, test-consumer-conformance-fixtures.sh, and auth-webauthn-manual-dossier.sh mktemp unique dirs under /Volumes/Builds/scratch/underlay and exit 1 when the directory is missing. check-env-manifest.sh left on generic mktemp as consumer-runnable product temp. effigy check:consumer-conformance-fixtures exit 0. | |
this-workspace-guide-recipes |
Current THIS-workspace guide recipes instruct Oxide | pass |
docs/guides/041-rust-module-splitting.md lines 95-96 now say oxide check -p --all-features and oxide test -p --all-features. Crate ignored-test comments use oxide test. Consumer recipes, CI, and historical 190/205 remain classified Cargo. | Supersedes the fail on this id in review 5645382565. |
docs-and-format-checks |
qa:docs (including agent-defaults) and fmt:rust:check | pass |
effigy qa:docs exit 0 (links, agent-defaults, contracts local-paths, including contract 123). effigy fmt:rust:check exit 0. |
Outcome
Finishes the Oxide adoption without reopening #26/PR59 or #27/PR60 evidence. Ordinary local Rust routes use Oxide, no
:cargoselector remains, and agent/proof scratch sits on Builds.Changes
effigy.toml: removedrust:check:cargo,rust:clippy:cargo,rust:test:cargoand the fallback comment; the comment now states the only escapes (operatorEFFIGY_OXIDE_ESCAPE=cargoon a routed surface that honours it, or Cargo by hand) and theoxide exec -- <tool>rule. Addedcheck:coverage-route.rust/scripts/check-coverage.sh: Tarpaulin now runs asoxide exec -- cargo tarpaulin --workspace --out Xml; same arguments, threshold, stream capture and exit status. The declared parse-failure branch is reachable (|| trueon the summary pipeline) so unparsable output still exits 1 with diagnostics instead of silently.rust/scripts/test-check-coverage.sh(new,effigy check:coverage-route): fakeoxide/cargo-tarpaulinprove argv (exec -- cargo tarpaulin --workspace --out Xml), success/summary, below-threshold failure, tool-failure passthrough of stdout+stderr with exit normalised to 1, unparsable output, and the missing-cargo-tarpaulinrefusal before any dispatch.scripts/test-consumer-conformance-fixtures.shandscripts/auth-webauthn-manual-dossier.shcreate unique directories below/Volumes/Builds/scratch/underlayand refuse when the volume is absent (no$TMPDIR/$HOME/checkout fallback).docs/knowledge/contracts/123-local-rust-routing-and-scratch-placement.md(routing, escape posture, remaining Cargo words by class, scratch rules), indexed fromdocs/knowledge/README.mdanddocs/knowledge/contracts/README.md; contract 022 coverage section updated (routing superseded, Tarpaulin instrumentation still unqualified).AGENTS.md(escape wording + scratch section),rust/AGENTS.md,README.mdcoverage,skills/underlay-buildraw-fallback wording, and the seven Rust integration-test doc comments now nameoxide test.Not touched:
.github/workflows, CI examples, consumer-app recipes (cd apps/api && cargo test), historical release/upgrade/sweep records, Cargo-subject metadata (cargo-tarpaulin, manifest schema, dependencies), and runtime/guest/tmpbehavior.Local route inventory (Cargo words by class)
:cargoselectors in the effective manifest (effigy tasks --all --json→ 0cargomatches)..github/workflows/*, CI guide examples.cargo-*binary names, manifests, changelog, workspace-shape checks readingCargo.toml.Validation (each once, through Effigy)
effigy check:coverage-route— passed (fake tools only; no real coverage/Cargo/Oxide build).effigy check:consumer-conformance-fixtures— passed; exercised the Builds scratch path end to end.effigy qa:docs(links, agent-defaults, contract local paths) — passed.effigy fmt:rust:check— passed (Rust comment-only edits).bash -non both changed scratch scripts;git diff --check.Reviewer notes