Cut the builders' and flake's comments to contracts, traps and pointers #103

Merged

vnprc merged 2 commits from agent/comments-builders into master

2026-09-22 13:32:57 +01:00

allod-agent commented

2026-09-22 04:15:56 +01:00

Member

flake.nix, the four builder files under nix/builders/, nix/vm-facts.nix and nix/build-zola-site.nix lose 164 comment lines and keep every contract and trap: each builder argument now carries a one-line contract, the shared "an argument, never a read of the input" rule is stated once in the README's Builders section, and every trap (the agenix path-versus-string closure leak, the SSH alias glob, hostname-keyed identities, the fixture-substitution seam) stays as one sentence plus a pointer. Nothing a machine builds changes: not one non-comment line moved, and every machine's and every check's derivation path is byte-identical to master. What proves it is the comment-only gate, the derivation-path comparison, and ./check.sh green on this branch. If it is wrong, revert the two commits; no other repository reads these files.

What changed

Comment lines: nix/builders/dev.nix 102 to 41, hypervisor.nix 29 to 13, privacy.nix 7 to 6, shared.nix 23 to 14, nix/vm-facts.nix 7 to 6, nix/build-zola-site.nix 14 to 11, flake.nix 138 to 65. Of 25 blocks of three or more lines, 10 became a pointer to the README or an issue, 12 traps were compressed to the sentence that names the wrong edit, 2 contracts were merged into one paragraph, none was deleted outright.
The secrets ? secretsInput paragraph in dev.nix and the "same widening the VM builders got" paragraph in hypervisor.nix, the two the allod/archetypes#93 review had to fix because they pointed by location, are one-line contracts per argument; the reasoning is one paragraph in README ## Builders, cited as allod/archetypes#88.
The agenix path-versus-string trap in dev.nix points at nix.md, where allod/memory#63 lands its long form.
No position word ("above", "below", "here", "this file", "the caller") remains in any comment in these files; history words are gone.
README ## Public hosts no longer points at a comment in flake.nix by position; it cites allod/archetypes#55.
Comments inside Nix indented strings were not touched. The rule these edits apply is the "Code comments" section in writing.md (allod/memory#63).

Risk

R1. Comment-only: the gate diffs the Nix parse tree (nix-instantiate --parse, which drops comments) against master and reports zero non-comment changes, and the derivation-path witness covers every machine and every check on both data sets. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block. Rollback is a straight revert.

Validation

Comment-only gate: non-comment lines changed: 0 (files checked: 7); README.md is the only other file changed.
Derivation paths captured one nix process per item on master and on this branch: 4 machines, 19 checks on template data, 19 checks on the fork fixtures, plus vmFacts, lib and nixosModules. All identical.
./check.sh on the move commit (2472fa5): All 32 steps passed (checks: 19 built). The one later commit changes a README line only.
One cold cross-family review of the diff (gpt-5.6-terra on codex, high effort), asked per deleted or compressed block what wrong edit it prevented and what prevents it now, with every new pointer verified against the README and the memory topic files: one finding, the README pointer by position, fixed in dd73908. The transcript shows the diff and ledger reads.

Refs allod/archetypes#101

`flake.nix`, the four builder files under `nix/builders/`, `nix/vm-facts.nix` and `nix/build-zola-site.nix` lose 164 comment lines and keep every contract and trap: each builder argument now carries a one-line contract, the shared "an argument, never a read of the input" rule is stated once in the README's Builders section, and every trap (the agenix path-versus-string closure leak, the SSH alias glob, hostname-keyed identities, the fixture-substitution seam) stays as one sentence plus a pointer. Nothing a machine builds changes: not one non-comment line moved, and every machine's and every check's derivation path is byte-identical to master. What proves it is the comment-only gate, the derivation-path comparison, and `./check.sh` green on this branch. If it is wrong, revert the two commits; no other repository reads these files. ## What changed - Comment lines: `nix/builders/dev.nix` 102 to 41, `hypervisor.nix` 29 to 13, `privacy.nix` 7 to 6, `shared.nix` 23 to 14, `nix/vm-facts.nix` 7 to 6, `nix/build-zola-site.nix` 14 to 11, `flake.nix` 138 to 65. Of 25 blocks of three or more lines, 10 became a pointer to the README or an issue, 12 traps were compressed to the sentence that names the wrong edit, 2 contracts were merged into one paragraph, none was deleted outright. - The `secrets ? secretsInput` paragraph in `dev.nix` and the "same widening the VM builders got" paragraph in `hypervisor.nix`, the two the allod/archetypes#93 review had to fix because they pointed by location, are one-line contracts per argument; the reasoning is one paragraph in README `## Builders`, cited as allod/archetypes#88. - The agenix path-versus-string trap in `dev.nix` points at `nix.md`, where allod/memory#63 lands its long form. - No position word ("above", "below", "here", "this file", "the caller") remains in any comment in these files; history words are gone. - README `## Public hosts` no longer points at a comment in `flake.nix` by position; it cites allod/archetypes#55. - Comments inside Nix indented strings were not touched. The rule these edits apply is the "Code comments" section in `writing.md` (allod/memory#63). ## Risk R1. Comment-only: the gate diffs the Nix parse tree (`nix-instantiate --parse`, which drops comments) against master and reports zero non-comment changes, and the derivation-path witness covers every machine and every check on both data sets. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block. Rollback is a straight revert. ## Validation - Comment-only gate: `non-comment lines changed: 0 (files checked: 7)`; README.md is the only other file changed. - Derivation paths captured one `nix` process per item on master and on this branch: 4 machines, 19 checks on template data, 19 checks on the fork fixtures, plus `vmFacts`, `lib` and `nixosModules`. All identical. - `./check.sh` on the move commit (`2472fa5`): `All 32 steps passed (checks: 19 built).` The one later commit changes a README line only. - One cold cross-family review of the diff (`gpt-5.6-terra` on codex, high effort), asked per deleted or compressed block what wrong edit it prevented and what prevents it now, with every new pointer verified against the README and the memory topic files: one finding, the README pointer by position, fixed in `dd73908`. The transcript shows the diff and ledger reads. Refs allod/archetypes#101

allod-agent added 2 commits

2026-09-22 04:15:57 +01:00

Cut nix/builders, flake.nix and the vm-facts/zola-site helpers to contract, trap and pointer comments 2472fa582e

Compresses argument-list and design-reasoning comments in nix/builders/,
nix/vm-facts.nix, nix/build-zola-site.nix and flake.nix down to a contract,
a trap, or a pointer per writing.md's Code comments rule. Position words
(above/below/here) are replaced by names; history narrative is dropped;
long reasoning that duplicated or belonged in README.md moves there and the
comment becomes the pointer. Adds one paragraph to README's Builders
section for the shared "argument, not a read of the input" contract so
per-argument comments in dev.nix/hypervisor.nix/privacy.nix can point at it
instead of repeating it.

Refs allod/archetypes#101

Review round: name the public-host builder note by its issue, not its position dd73908e1e