assay_env: the capstone role — fingerprint to interchange file (proposed)

[mellanon]

Proposed — no obligation, and shaped to land around the in-flight base refactor. Implements the capstone role from the-metafactory/crucible#25: capture the machine's fingerprint (control-side, via scripts/vm-fingerprint.sh), and write the interchange file /etc/assay/environment.json that assay's runner reads (contract: assay environments/README.md).

What it does

• Runs the existing fingerprint script from the control node (delegate_to: localhost), capture to the gitignored fingerprints/ overlay.
• Parses the three DIGESTS lines with a fully-anchored regex over the script's stderr tail; refuses loudly on any missing/truncated digest.
• Writes the five contract fields (schema: 1, core_digest, provider_digest, provider, definition) via copy, root:root 0644.
• Fails closed: if capture or parse fails on a machine that has an environment file from an earlier run, the role withdraws that file before failing — a stale identity is worse than none (env@none is a true statement; an unverified digest is not).
• List it last in ansible_roles (it fingerprints what the earlier roles installed); inventory-example updated with the rationale.

Evidence

• ansible-lint production profile: 0/0, whole tree and role.
• Container harness (Linux, real /etc/assay): happy path byte-matches the capture's DIGESTS block; re-run on an unchanged machine changed=0; malformed capture → refusal observed red before any write, withdrawal observed (rescued=1, file gone); --check writes nothing and shows the honest diff.
• Two independent review passes (standard + adversarial); the adversarial pass tried delegation leakage, stderr-shift parse corruption, stale-file reuse, shell injection, and the §4a invariant (writing the file must not move the core digest — it can't; CORE reads a fixed enumeration that never includes /etc/assay). All refuted.

Your call, Vincent (deliberately not decided here)

1. Role name — assay_env follows the current underscore convention; if the base refactor lands a different naming scheme, rename at will, nothing depends on the string.
2. provider: proxmox-ve hardcoded in defaults — there is no provider fact in tofu.py's hostvars today and vm-pve is the only module, so defaults felt honest; the comment in the file records that it should move to tofu output when a second provider exists.

Known-outstanding (recorded, not hidden)

• crucible#25 ACs 2 and 5 need a live-guest run (no ProxMox target on our side) — the acceptance block in the issue is copy-pasteable; also worth one live check that the rescue's state: absent behaves over SSH.
• Cosmetic nit: under --check with a failing capture, the failure message says the old file "has been REMOVED" though check mode removed nothing (safe direction; fix if the file is touched again).

🤖 Generated with Claude Code

https://claude.ai/code/session_018PtJarXm8d8bSHDbhmskVm

[vpzed-dev-lux]

Review recommendation: do not merge yet.

There is one blocking fail-closed gap in ansible/roles/assay_env/tasks/main.yaml. The rescue block covers fingerprint capture and digest parsing, but ends before the interchange directory creation and final copy task. If capture succeeds and the write subsequently fails—for example because of a full disk, permissions, or connection loss—the environment file from an earlier run remains on the guest even though the machine may have changed. That contradicts the role’s core invariant that a stale identity is worse than none.

Please move directory creation, document assembly, and the final copy into the same rescued block so any unsuccessful refresh withdraws the previous file. Ideally, give preflight failures equivalent stale-file handling as well. A failure-path test where an old environment file exists and the final copy is forced to fail would lock this behavior down.

Everything else I reviewed looks sound: the JSON matches Assay’s interchange contract, digest parsing is strict, the capture contents are not registered, argv avoids shell injection, git diff --check passed, local syntax checking passed, and GitHub’s validate check is green. After closing the rescue-boundary gap, I would consider this ready to merge.

[mellanon]

Thanks — the boundary call was precise, and naming the specific failure modes (full disk, permissions, connection loss) is what made the second-order problem visible. Fixed in 101e27e.

Blocking item — the rescue boundary. Create the interchange directory, Assemble the interchange document and Write the assay environment file are now inside the same block. Any unsuccessful refresh withdraws the previous file, whichever end it failed at.

Widening the block widened the rescue's own failure mode, which turned out to be the more interesting half. Whatever breaks the write is frequently what breaks the removal: on a read-only filesystem the copy fails EROFS and the unlink fails too, and the old rescue would have died there — failing the play with the removal's errno and not one word about the stale file left standing. So the withdrawal now runs with failed_when: false, a stat confirms the outcome, and the message is written from the filesystem rather than from the module's report. When the file survives, the run says so in those words: COULD NOT BE REMOVED … STILL ON THE MACHINE … treat that digest as UNVERIFIED. A withdrawal this role only attempted is never reported as one that happened. While the message was open I also added the fourth branch for --check — the cosmetic nit recorded in the PR description; it no longer claims a removal that check mode never performs.

The test you asked for. Container harness, Linux, root, real /etc/assay, stubbed capture, run privileged so the failing filesystems can be mounted. Two new failure-path cases, both observed red against 40a164d first:

• write fails ENOSPC — tmpfs sized to 64k at /etc/assay, stale file present, filled to 100%. Pre-fix: rescued=0, the stale file survives, nothing in the output mentions it. Post-fix: rescued=1, failure names Write the assay environment file with [Errno 28] No space left on device, /etc/assay/environment.json is gone afterwards, message claims REMOVED with absence confirmed.
• write fails EROFS — read-only bind mount, stale file present. Pre-fix: rescued=0, no mention of the file at all. Post-fix: rescued=1, the removal fails, the run reports COULD NOT BE REMOVED / STILL ON THE MACHINE / UNVERIFIED, and the stale file is still byte-identical.

Regressions re-run alongside: happy path (0644 root:root, schema int 1, the capture's two digests, no combined), idempotent re-run changed=0, malformed digests refusing at the partial-file guard before any write with the file withdrawn, and --check on a correct machine changed=0 writing nothing (mtime, size and bytes identical). 38 assertions, 0 failures. ansible-lint production profile clean on the tree (25 files) and the role alone (3); site.yaml --syntax-check clean.

The harness is deliberately uncommitted: it needs a privileged Linux container to mount the filesystems these cases require, which CI does not have today. Happy to land it as scripts/test-assay-env.sh alongside test-vm-fingerprint.sh if you would rather have it in the tree — say the word and it comes in the next push.

Pre-flight refusals — keeping them outside the block, deliberately. This is the one place I have not followed the recommendation, and the tasks now carry a comment stating the trade so it is a documented decision rather than an oversight (ansible/roles/assay_env/tasks/main.yaml, the comment block directly above Refuse to capture without a capture path). All three pre-flight refusals are control-node misconfigurations: an empty assay_env_capture_path, no capture script in this checkout, an inventory serving no ansible_host/ansible_user. In every one, the role has not run, nothing has touched the guest, and the file already on it still describes the machine the last successful run confirmed. Withdrawing an identity because the operator launched the playbook from the wrong directory revokes a good machine's identity over a fault on this side of the SSH connection — it would make one bad checkout's blast radius the whole fleet. From the capture command onward the guest is in play, and everything from there down is inside the block. An adversarial review pass reached the same conclusion independently. If you read it the other way I will move them, but I would want the trade recorded either way.