Skip to content

028: Complete Underlay local Oxide routing and Builds scratch policy - #61

Merged
betterthanclay merged 2 commits into
mainfrom
ns-11deb8ad-5085-46c4-8b08-02148a72945f
Oct 25, 2026
Merged

betterthanclay merged 2 commits into
mainfrom
ns-11deb8ad-5085-46c4-8b08-02148a72945f

Conversation

@betterthanclay

Copy link
Copy Markdown
Contributor

Outcome

Finishes the Oxide adoption without reopening #26/PR59 or #27/PR60 evidence. Ordinary local Rust routes use Oxide, no :cargo selector remains, and agent/proof scratch sits on Builds.

Changes

  • effigy.toml: removed rust:check:cargo, rust:clippy:cargo, rust:test:cargo and the fallback comment; the comment now states the only escapes (operator EFFIGY_OXIDE_ESCAPE=cargo on a routed surface that honours it, or Cargo by hand) and the oxide exec -- <tool> rule. Added check:coverage-route.
  • rust/scripts/check-coverage.sh: Tarpaulin now runs as oxide exec -- cargo tarpaulin --workspace --out Xml; same arguments, threshold, stream capture and exit status. The declared parse-failure branch is reachable (|| true on 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): fake oxide/cargo-tarpaulin prove 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-tarpaulin refusal before any dispatch.
  • Scratch placement: scripts/test-consumer-conformance-fixtures.sh and scripts/auth-webauthn-manual-dossier.sh create unique directories below /Volumes/Builds/scratch/underlay and refuse when the volume is absent (no $TMPDIR/$HOME/checkout fallback).
  • Knowledge: new owner docs/knowledge/contracts/123-local-rust-routing-and-scratch-placement.md (routing, escape posture, remaining Cargo words by class, scratch rules), indexed from docs/knowledge/README.md and docs/knowledge/contracts/README.md; contract 022 coverage section updated (routing superseded, Tarpaulin instrumentation still unqualified).
  • Guidance: AGENTS.md (escape wording + scratch section), rust/AGENTS.md, README.md coverage, skills/underlay-build raw-fallback wording, and the seven Rust integration-test doc comments now name oxide 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 /tmp behavior.

Local route inventory (Cargo words by class)

  • ordinary local Rust routes: all Oxide, zero plain-Cargo routes, no :cargo selectors in the effective manifest (effigy tasks --all --json → 0 cargo matches).
  • hosted CI: .github/workflows/*, CI guide examples.
  • generic consumer recipes inside guides.
  • Cargo as subject/metadata: cargo-* binary names, manifests, changelog, workspace-shape checks reading Cargo.toml.
  • product/fixture/guest builds.
  • historical release, upgrade and sweep records.

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 -n on both changed scratch scripts; git diff --check.
  • No install, coverage activation, Rust build, app runtime, DB, or migration run.

Reviewer notes

  • Independent review should verify the fake-tool dispatch assertions and the scratch refusal path, and confirm the remaining Cargo words above are classified rather than pending.

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 inflatable-tester left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.toml rust:build|check|clippy|test and fmt:rust* spell oxide. Coverage wrapper: oxide exec -- cargo tarpaulin --workspace --out Xml (inner cargo belongs to Tarpaulin). Presence check and install hint keep the cargo-tarpaulin binary name. Effective catalog: rust:check:cargo, rust:clippy:cargo, and rust:test:cargo are undefined. rust:check plans oxide check --workspace --all-features.

  • Hosted CI: .github/workflows/rust.yml still runs cargo fmt/clippy/build/test (untouched). Guide CI snippets in docs/guides/130-testing.md and docs/guides/150-ci-cd.md keep Cargo.

  • Generic consumer recipes: cd apps/api && cargo test in docs/guides/README.md; consumer structure/testing/backend recipes in 020, 040, 130, 070, 078, 185; consumer templates templates/scripts/setup.sh and reset-db.sh; contract 022 API-package minimum examples cargo build / cargo check. skills/underlay-build now 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/bin PATH notes in prerequisites.

  • Product / fixture / live-tool behaviour: scripts/check-env-manifest.sh still uses generic mktemp -d for key-name extraction. This is a consumer-runnable live env check; binding it to /Volumes/Builds would 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 check runs, including docs/guides/190-upgrade-compatibility.md and docs/sweeps/*.

  • Scratch: scripts/auth-webauthn-manual-dossier.sh, scripts/test-consumer-conformance-fixtures.sh, and rust/scripts/test-check-coverage.sh use 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 in AGENTS.md is preserved.

Checks (once, Effigy)

  • effigy check:coverage-route — pass (fake-tool Oxide dispatch, threshold, stream passthrough, missing cargo-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 inflatable-tester left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.toml rust:build|check|clippy|test and fmt:rust* spell Oxide. Coverage wrapper: oxide exec -- cargo tarpaulin --workspace --out Xml (inner cargo belongs to Tarpaulin). Presence check and install hint keep the cargo-tarpaulin binary name. Effective catalog: rust:check:cargo, rust:clippy:cargo, and rust:test:cargo are undefined. rust:check plans oxide check --workspace --all-features. Crate ignored-test comments and 041 use oxide test / oxide check.
  • Hosted CI: .github/workflows/ untouched. Guide CI snippets in docs/guides/130-testing.md and docs/guides/150-ci-cd.md keep Cargo.
  • Generic consumer recipes: cd apps/api && cargo test in docs/guides/README.md; consumer structure/testing/backend recipes in 020, 040, 130, 070, 078, 185, 200; consumer templates templates/scripts/setup.sh and reset-db.sh; contract 022 API-package minimum examples cargo build / cargo check. skills/underlay-build falls 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 read Cargo.toml.
  • Product / fixture / live-tool behaviour: scripts/check-env-manifest.sh still uses generic mktemp -d for key-name extraction. Consumer-runnable live env check; binding it to /Volumes/Builds would 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 check runs, including docs/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, and rust/scripts/test-check-coverage.sh use 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 in AGENTS.md is 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 underlay
  • effigy --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, missing cargo-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 — pass
  • bash -n on 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.

@betterthanclay
betterthanclay merged commit 7061890 into main Oct 25, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants