docs(v574): audit fixture comparisons and plan trace proof

2026-10-22 20:19:24 -05:00
1 parent 65e919e5ce
commit 7da3822443
@@ -0,0 +1,50 @@
+# Vikunja574: deterministic fixture Git before/after comparisons
+
+Owner Gander, gate Sage. mos-1369 A4 and mos-1370; sage-3107 and sage-3110. Take574 before573, as separate candidates. Base062646487451993302c768c6812b827c834e952b (origin/refactor at start), branchgander/v574. No queue move before Sage places the row. Build/push authorized now; every test/proof run waits Sage CLEAR after270+271 run5. Row292 remains independently held for final base and C1 review.
+
+## Exact authorized delta
+
+Only prepend `-c maintenance.auto=false -c gc.auto=0` to each fixture helper's Git argv. No production change, environment change, assertion change or fingerprint/snapshot change. Full-root comparisons still include .git. Production checkout.mjs's SAFE argv already contains both flags; gitEnv() alone does not. The helper called gitEnv() but skipped SAFE.
+
+- packages/seat/tests/checkout.test.mjs:git34-35 commits fixture roots; once():88-91 fingerprints root including.git. Whole clone comparison246-249 also covers it.
+- packages/seat/tests/working.test.mjs:git27-28 commits fixture repositories; fingerprint():40 and refusal checks83-86/120-122 cover the whole root.
+- packages/cli/tests/git-socket.test.mjs:gitIn32-33 commits projects; fingerprint():43 and once79-101 cover project/.git.
+- packages/cli/tests/lifecycle.test.mjs:gitIn47-49, commit71; snapshot459 walks every regular file, T11 compares pb.root831/839 including project/.git. Outside original list, explicitly authorized sage-3110 / mos-1370 before editing.
+
+Static preservation check removes only the four inserted argv elements from each candidate file and requires exact equality with its base blob. Thus every original assertion, fingerprint and snapshot byte stays intact. No new tests mirror the flags; runtime evidence is the requested trace over real fixture commits and whole files.
+
+## Named but unchanged
+
+- bus/grant-enroll.test.mjs imports fingerprint from host-grant.mjs for SSH host keys. No fixture Git helper or Git command; unchanged.
+- bus/grant-executor.test.mjs uses SSH-key fingerprints; its commit references are grant transaction steps, not Git fixture commits. No Git helper; unchanged.
+- bus/host-tools.test.mjs:28 hashes decoded SSH public-key bytes. No Git helper; unchanged.
+- conversation/reader.test.mjs:52/71/73 fingerprints session fixture files, but creates no Git repository and makes no Git call. Unchanged.
+
+## Other fixture audit, screened and unchanged
+
+- cli/lifecycle.test.mjs: whole-root .git snapshot is exposed; now included by explicit scope ruling above.
+- cli/launcher.test.mjs: fixture commits, but the before/after byte check961-971 names the sessions JSON file, not the repository tree or Git object directory. No maintenance-lock fingerprint exposure in that comparison.
+- cli/thread-launch.test.mjs and session-launch.test.mjs: fixture repositories, but compared before/transcripts/events/session-store values are application histories or evidence directories, not a whole .git tree. Unchanged.
+- cli/publish-socket.test.mjs and seat/publish.test.mjs: fixture commits, with ref values and fake-Gitea request/credential assertions. No whole-root fingerprint/snapshot; unchanged.
+- seat/landing.test.mjs: fixture commits support gate/root-path checks. The tree() helper builds a fixture and comparisons concern gate steps/results and output, not a whole-root byte inventory. Unchanged.
+- harness/git-tools.test.mjs: fixture commits support advertised object/ref and request assertions; no source-root byte fingerprint. Unchanged.
+- project/project.test.mjs, human-file.test.mjs and read.test.mjs: before/after checks use HEAD/status, spec content, or a record path; no full .git inventory including maintenance.lock. tester-init.test.mjs checks created records and identity. Unchanged.
+- bus/project-files.test.mjs via spec-fixtures.mjs: state() compares rev-parse HEAD and status --porcelain; detached maintenance changes neither asserted logical value. Unchanged.
+- library/mirror.test.mjs and sync.test.mjs via helpers.mjs: before/after byte checks name the sync-state file; comparison does not inventory Git objects/maintenance.lock. Unchanged.
+- cli/stack-copy.test.mjs: tree() compares published copies, which exclude source .git; source fixture already configures gc.auto0. No whole-source-repo .git fingerprint. Unchanged.
+- cli/stack-release-fixture.mjs and release tests: fp() compares unit, wrapper, pointer and store bytes, and tree() comparisons cover data/copies; source fixture.git is outside those roots and already sets gc.auto0. Unchanged.
+- webui/pinned-copy.test.mjs: fixture commits and gc.auto0; before/after assertion names config bytes and copied output, not source.git inventory. Unchanged.
+- queue/store.test.mjs via helpers.mjs: snap337 compares queue/view/.git/mosaic-queue.head only, not object/maintenance-lock paths. review tests compare request/log records. Unchanged.
+- ledger/ledger.test.mjs: Git fixture history is read as logical commits/timestamps, no whole-root .git fingerprint comparison found. Unchanged.
+
+This is an audit of fixture before/after comparisons, not a claim every unflagged fixture Git helper is fixed. No outside named scope was changed without approval. Mos's provided probe /mnt/storage/scratch/mos-1369/maint-lock-probe.py was read only, never executed.
+
+## Trace and gate plan, no execution yet
+
+Real Git: /usr/bin/git, `git version 2.55.0` (read-only version query). gitEnv() retains PATH and scrubs outer tracing env, so an outer GIT_TRACE2 alone would be vacuous. On CLEAR create an executable git shim in own scratch, outside the candidate. It only exports GIT_TRACE2 to a per-run absolute trace path and execs /usr/bin/git with the unchanged argv. The candidate contains no shim.
+
+Positive control first: a fresh fixture-style repo/commit WITHOUT either flag, traced through that shim, must show a maintenance child_start. Do not accept a missing/empty trace as success. Allow the detached positive-control child to finish and verify its scratch repo is idle before the flagged proof.
+
+Flagged control and four touched files whole then use the shim. Require observed fixture commit commands in each applicable trace and zero maintenance child_start. Classify a maintenance child by the trace's child_start and `maintenance run --auto` command, not by a substring in this plan. Save the raw trace, tested SHA, exact command/timeouts, command/child counts, and restored-tree check. No assertion weakening or .git exclusion is allowed. Any old red, timeout, maintenance child, or missing positive control stops for Sage/Mos before a retry.
+
+Recommended slot scope: positive/flagged fixture control plus the four touched files whole with GIT_TRACE2, and any broader seat/CLI suite Sage requests. Record per-file timeout-k10 at least3x successful historical whole-file receipt with headroom before launch; use900s where timing is unknown. TMPDIR from mktemp-d /mnt/storage/scratch/tmp/gXXXXXX, never /tmp. Pipefail/tee and busy check before each start. Trace runs are test work and are not authorized before CLEAR. No dependencies installed and no live ports/units/config accessed. Session registration remains Sage's.
@@ -0,0 +1,4 @@
+721af7a3745dae10d0dad9226e7ba5ce32754b5da7367aa13f970d7f03677a3c  packages/cli/tests/git-socket.test.mjs
+a0cae5797886b729600dcbcad8e38ec94f97143c77fd91648050417c2d5630f7  packages/cli/tests/lifecycle.test.mjs
+cb3941fed464fd4c88aac7c05bb32db1b1776858650979523f64dc6fc3baf7d3  packages/seat/tests/checkout.test.mjs
+22cbdd43fc11c6f234d0f2c1512d5039839d1242fd421e62f2aa3d3db1c9de05  packages/seat/tests/working.test.mjs
@@ -0,0 +1,30 @@
+[
+  {
+    "file": "packages/cli/tests/git-socket.test.mjs",
+    "base_sha256": "ec4bbbc98adab6561205e5ec8e2f2495f1f55224da53e567c7a72e36b5410709",
+    "candidate_sha256": "721af7a3745dae10d0dad9226e7ba5ce32754b5da7367aa13f970d7f03677a3c",
+    "only_inserted_argv_flags": true,
+    "assertions_and_fingerprint_unchanged": true
+  },
+  {
+    "file": "packages/cli/tests/lifecycle.test.mjs",
+    "base_sha256": "5ce79205c4ca6e5f6e77671968ce9d8b8ebfdbdde07b31676f2d05b284acb938",
+    "candidate_sha256": "a0cae5797886b729600dcbcad8e38ec94f97143c77fd91648050417c2d5630f7",
+    "only_inserted_argv_flags": true,
+    "assertions_and_fingerprint_unchanged": true
+  },
+  {
+    "file": "packages/seat/tests/checkout.test.mjs",
+    "base_sha256": "663040d7c737aba6403e6397bacf1325b558cc14df3e5677f0a28f9499c45127",
+    "candidate_sha256": "cb3941fed464fd4c88aac7c05bb32db1b1776858650979523f64dc6fc3baf7d3",
+    "only_inserted_argv_flags": true,
+    "assertions_and_fingerprint_unchanged": true
+  },
+  {
+    "file": "packages/seat/tests/working.test.mjs",
+    "base_sha256": "15234267a0e28c53b13a4219ea45e71608722fb137d1f266adfd3f80040eb7c6",
+    "candidate_sha256": "22cbdd43fc11c6f234d0f2c1512d5039839d1242fd421e62f2aa3d3db1c9de05",
+    "only_inserted_argv_flags": true,
+    "assertions_and_fingerprint_unchanged": true
+  }
+]
@@ -0,0 +1,15 @@
+{
+  "vikunja": 574,
+  "queue": "pending Sage placement",
+  "gate": "sage",
+  "base": "062646487451993302c768c6812b827c834e952b",
+  "source": "65e919e5cef30911b9902f410549da431423cec4",
+  "branch": "gander/v574",
+  "manifest": "cdda41f5baa6b04e6e5bb9b82beff8e00ceef440c6702565cc86944f249bb5d3",
+  "tests": "NOT RUN; no trace/Node/test until Sage CLEAR",
+  "scope_authority": [
+    "mos-1369",
+    "sage-3110",
+    "mos-1370"
+  ]
+}