VFS Right-Thing Restructure: five-crate workspace, correctness fixes, semantic unification

.agents/benchmarks/restructure-attestation/README.md

@@ -0,0 +1,137 @@
+# Final Mission Attestation — VFS Right-Thing Restructure
+
+Machine-readable definition-of-done record tying the full honest gate and the
+codex benchmark contract to the exact commit (VAL-GATE-012, VAL-CROSS-012).
+
+## Attested commit
+
+- Commit: `230c30a6f2e7184b0578eb2dec087b79c0f78078` (`dev`)
+- Binary: `target/release/agentfs` built from that commit by `scripts/gate.sh`
+  (release workspace build; `rust-toolchain.toml` nightly)
+- Runner: `Linux 7.1.2-3-cachyos x86_64 GNU/Linux`; toolchain
+  `cargo 1.97.0-nightly (4f9b52075 2026-05-01)`
+- Attestation artifacts: `full-gate.json` (gate + shell suite + phase8 + canon +
+  pjdfstest + cross-surface flows), `medians.json` (benchmark contract),
+  `bench-milestones.json` (per-milestone BENCH record, VAL-GATE-015)
+
+## Full gate (all green)
+
+`scripts/gate.sh` at the attested commit: fmt, clippy `--workspace
+--all-targets -D warnings`, `cargo test --workspace`, release build, strict
+shell suite (`AGENTFS_GATE_STRICT=1 crates/agentfs-cli/tests/all.sh`, both
+corruption-torture transport legs), `phase8-validation.py --smoke` (noopen /
+flush / external-base-drift coherence harnesses run inside it), and
+`scripts/validation/consistency-canon.sh`. Result: exit 0 —
+`PASS=24 SKIP=0 FAIL=0`, phase8 `failed_gates: []`, canon all rules PASS.
+Full detail: `full-gate.json`.
+
+pjdfstest: `scripts/validation/posix/run-pjdfstest.sh --profile phase5-ci
+--agentfs-bin target/release/agentfs` — PASS (311 tests, run standalone at the
+attested commit).
+
+## Benchmark contract
+
+Exact invocation (library/perf-contract.md, services.yaml `bench-multi`):
+
+```bash
+python3 scripts/validation/git-workload-benchmark-multi.py \
+  --label m7-opt-sandbox-bringup-repeat --iterations 5 --warmup 1 \
+  --agentfs-bin "$PWD/target/release/agentfs" \
+  --output <out.json> --keep-iterations \
+  --source .agents/benchmarks/fixtures/codex \
+  --read-files 64 --read-bytes 4096 --edit-files 8
+```
+
+Baseline: the ACTIVE post-M3 baseline
+`.agents/benchmarks/restructure-baseline/medians.json` (recorded at
+`2b811f0`, orchestrator-signed rebaseline; the archived M1 artifact is
+`medians-m1.json`). Gate rule: a phase is red iff its median regresses >5%
+relative AND >10ms absolute.
+
+Result (median-of-5 per phase, all 7 phases in band, `all_phases_passed: true`
+in `medians.json`):
+
+| phase | baseline (ms) | current (ms) | delta | verdict |
+| --- | ---: | ---: | ---: | --- |
+| checkout | 56.7 | 56.9 | +0.4% | OK |
+| clone | 2800.9 | 2882.8 | +2.9% | OK |
+| diff | 65.6 | 25.9 | -60.6% | OK |
+| edit | 5.0 | 4.9 | -1.6% | OK |
+| fsck | 215.0 | 177.9 | -17.2% | OK |
+| read_search | 8.8 | 8.0 | -8.6% | OK |
+| status | 178.0 | 145.8 | -18.1% | OK |
+
+Provenance: the official quiet-window candidate/sentinel pair plus the
+mandated brittle-phase repeat was recorded at `dae8aa6` (feature
+m7-opt-sandbox-bringup; the same-window sentinel of the baseline binary was
+green, and the first candidate run's clone red evaporated on the repeat per
+the perf-contract brittle-phase rule). The pair is cited at the attested
+commit per the orchestrator round-3 ruling: the only commit after `dae8aa6`
+(`230c30a`, darwin seatbelt read scoping) changes `cfg(target_os = "macos")`
+code, docs, and clap help text only — Linux binary perf semantics are
+unchanged. Raw run JSONs (`bench-cand.json`, `bench-cand-repeat.json`,
+`bench-sent.json`, with per-iteration walls) live in the mission evidence dir
+`evidence/m7-cli-docs/m7-opt-sandbox-bringup/`.
+
+The earlier attestation-round checkout reds (rounds 1-2, bisected to
+`ea416c8`) were closed with zero code change: the tax was the user's PATH
+git-ai shim taking a slow path inside the run-sandbox namespace, removed by
+`dae8aa6`'s universal /usr/bin/git pinning. Full history:
+`bench-milestones.json` M7 rows and library/perf-contract.md "M7 checkout red
+— CLOSED".
+
+## Per-milestone BENCH record (VAL-GATE-015)
+
+Every BENCH-flagged milestone held the band; the stored-artifact reds that
+occurred along the way (M2 fsck, M3 clone/fsck, M4a checkout/clone, M7
+checkout) were each adjudicated per the procedure in
+library/perf-contract.md — the M2-M4a set as ambient drift via same-window
+sentinel reruns of the baseline code (leading to the orchestrator-signed
+post-M3 rebaseline), and the M7 checkout red as the unpinned git-ai shim,
+closed by harness/sandbox git pinning with an all-green pair at `dae8aa6`.
+Full per-milestone table with sources: `bench-milestones.json`.
+
+## Cross-surface flows
+
+All flows executed end-to-end at the attested commit against the release
+binary (30/30 checks OK; transcript `cross-surface5.log` in the mission
+evidence dir, summary in `full-gate.json.cross_surface_flows`):
+
+- clone -> mount -> git workflow -> unmount -> remount persistence
+  (VAL-CROSS-001/002): clean clone status, `cross-persist` commit and hash
+  stable across remount.
+- moved single DB file reopens (VAL-CROSS-003): exactly one file in the DB
+  family, `mv` + `integrity --json` + remount all green.
+- sandboxed run leaves the host untouched (VAL-CROSS-004): before/after host
+  census identical outside `.agentfs/run/cross-host`.
+- run writes visible via `agentfs fs` (VAL-CROSS-005) and the session recorded
+  in `agentfs timeline` (VAL-CROSS-006).
+- mounted-FS and fs-CLI writes mutually visible byte-exact (VAL-CROSS-013).
+- combined kill-switch leg noopen=0 noflush=0 uring=0 (VAL-CROSS-011):
+  create/append/fsync/unlink-while-open/git all green, remount verified,
+  integrity clean.
+
+## File-size cap census (VAL-CONS-006)
+
+Binding rule (architecture.md section 7): no production file over 2,500 lines
+of NON-TEST CODE; sibling `tests.rs` files are excluded. The gate-enforced
+census (`consistency-canon.sh` line-count-cap, cfg(test)-aware, comment/blank
+stripping) reports zero offenders at the attested commit. For the audit trail,
+the three files whose RAW line counts exceed 2,500 are all under the cap by
+the binding rule:
+
+| file | raw lines | non-test code lines |
+| --- | ---: | ---: |
+| crates/agentfs-fuse/src/adapter/mod.rs | 3073 | 2213 |
+| crates/agentfs-nfs/src/server/nfs_handlers.rs | 3827 | 2354 |
+| crates/agentfs-cli/src/cmd/migrate.rs | 2546 | 1144 |
+
+## Notes
+
+- `.agents/benchmarks/restructure-baseline/attestation` is a symlink to this
+  directory for the mission feature's expected path.
+- Benchmark runs were serialized on this machine per the perf contract; load
+  at each accepted run start is recorded in the run logs.
+- All gate/flow harnesses pin `/usr/bin/git` with a hookless temp-HOME git
+  config (AGENTS.md universal-pinning rule); the post-run daemon census was
+  clean.

.agents/benchmarks/restructure-attestation/bench-milestones.json

@@ -0,0 +1,150 @@
+{
+  "record": "Per-milestone BENCH compliance (VAL-GATE-015)",
+  "contract": "library/perf-contract.md: median-of-5 per phase via git-workload-benchmark-multi.py; red iff >5% relative AND >10ms absolute vs the active baseline; single runs never gate; serialized on a quiet machine.",
+  "baselines": {
+    "m1": {
+      "artifact": ".agents/benchmarks/restructure-baseline/medians-m1.json",
+      "recorded_at_commit": "ae1e13f (benchmarked), 809d684 (artifact commit)",
+      "status": "archived; superseded by the post-M3 rebaseline after three independent drift adjudications proved it brittle on this machine for diff/fsck/clone/checkout"
+    },
+    "active_post_m3": {
+      "artifact": ".agents/benchmarks/restructure-baseline/medians.json",
+      "recorded_at_commit": "2b811f03493e861e5a7786592d25ac73b39e1aba",
+      "recorded_at": "2026-07-04T01:14:37Z",
+      "authorized_by": "orchestrator sign-off for misc-a-bench-rebaseline",
+      "provenance": ".agents/benchmarks/restructure-baseline/provenance-post-m3.md"
+    }
+  },
+  "milestones": [
+    {
+      "milestone": "M2 (dead-surface)",
+      "runs": [
+        {
+          "source": "m2-perf-triage-bench-red (HEAD 4e37c41, 2026-07-03)",
+          "verdict": "in band after adjudication",
+          "detail": "Stored-M1 compare red on fsck (+20.6ms/+11.0%; repeat +23.7ms/+12.7%). Rebuilt baseline code ae1e13f was red against its OWN stored artifact under identical conditions (diff +37.5%, fsck +11.5%), proving ambient drift, not a HEAD regression. Adjudication accepted by M2 scrutiny (PASS) and recorded in library/perf-contract.md."
+        }
+      ]
+    },
+    {
+      "milestone": "M3 (config/telemetry)",
+      "runs": [
+        {
+          "source": "m3-telemetry-registry feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout -18.0%, clone -9.7%, diff -53.7%, edit -3.9%, fsck -0.9%, read_search +1.9%, status -7.6%."
+        },
+        {
+          "source": "M3 user-testing VAL-CONF-013 (HEAD bc1753f)",
+          "verdict": "in band after adjudication",
+          "detail": "Moving red set across two stored-artifact runs (run1 clone +5.1%/fsck +8.3%; run2 diff/fsck/status); rebuilt ae1e13f sentinel red against its own artifact (clone +7.9%/+241ms, fsck +8.3%); direct HEAD-vs-sentinel showed HEAD equal or faster on the stored-red phases. Adjudicated noise; led to the orchestrator-signed post-M3 rebaseline (misc-a)."
+        },
+        {
+          "source": "misc-a-bench-rebaseline (post-M3 2b811f0)",
+          "verdict": "baseline re-recorded",
+          "detail": "Accepted run pair agreed 0-red in both directions; current-HEAD confirmation vs the new baseline: 0 red phases."
+        }
+      ]
+    },
+    {
+      "milestone": "M4a (core hot path)",
+      "runs": [
+        {
+          "source": "m4a-store-extraction feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout -14.2%, clone +2.2%, diff -41.5%, edit +1.0%, fsck +4.7%, read_search -9.5%, status -15.9%."
+        },
+        {
+          "source": "m4a-batcher-split feature BENCH (HEAD a687a84)",
+          "verdict": "in band after adjudication",
+          "detail": "Stored compare red on checkout/clone; rebuilt 2b811f0 sentinel equally red vs the same stored artifact under the same load; direct candidate-vs-sentinel: checkout +3.9ms, clone +3.9%, edit -0.8ms. Adjudicated ambient drift per perf-contract."
+        },
+        {
+          "source": "M4a user-testing VAL-CORE-008 (HEAD 9454886, load ~3.9)",
+          "verdict": "in band (0 red phases)",
+          "detail": "bench-compare exit 0; edit 5.2ms vs 5.0ms baseline (+3.8%, +0.2ms)."
+        }
+      ]
+    },
+    {
+      "milestone": "M4b (schema/overlay)",
+      "runs": [
+        {
+          "source": "m4b-overlay-directoryize feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "bench-compare exit 0, 7 within band."
+        },
+        {
+          "source": "m4b-overlay-partial-store feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout +9.4ms stayed below the >10ms absolute red threshold; all other phases faster than baseline."
+        },
+        {
+          "source": "m4b-agentfs-directoryize feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "clone -641.5ms / -22.9%; all other phases OK."
+        },
+        {
+          "source": "M4b user-testing VAL-CORE-018 (HEAD a62b0a1, load ~1.9-2.5)",
+          "verdict": "in band (0 red phases)",
+          "detail": "clone 2800.9ms -> 2741.3ms (-2.1%); diff +6.8ms and read_search +1.6ms sub-10ms absolute."
+        }
+      ]
+    },
+    {
+      "milestone": "M5 (crate split)",
+      "runs": [
+        {
+          "source": "m5-fuse-crate feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout 49.0ms, clone 2037.0ms, diff 31.1ms, edit 4.4ms, fsck 157.6ms, read_search 7.2ms, status 142.2ms."
+        },
+        {
+          "source": "m5-mount-crate feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout 43.1ms, clone 1872.2ms, diff 42.4ms, edit 3.7ms, fsck 180.3ms, read_search 7.7ms, status 121.1ms."
+        },
+        {
+          "source": "m5-fix-base-drift-coherence feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "All candidate medians faster than the active baseline (checkout 50.1ms, clone 1879.4ms, diff 33.2ms, edit 3.0ms, fsck 169.8ms, read_search 6.5ms, status 118.5ms)."
+        }
+      ]
+    },
+    {
+      "milestone": "M6 (semantics)",
+      "runs": [
+        {
+          "source": "m6-fix-readdir-scaling feature BENCH",
+          "verdict": "in band (0 red phases)",
+          "detail": "checkout 54.6ms, clone 2605.7ms, diff 33.1ms, edit 4.5ms, fsck 206.4ms, read_search 8.1ms, status 172.3ms; bench-compare 0 red, 7 within band."
+        }
+      ]
+    },
+    {
+      "milestone": "M7 (cli/docs + attestation)",
+      "runs": [
+        {
+          "source": "m7-attestation round 1 (HEAD ff91302, quiet load 1.4-2.1)",
+          "verdict": "red (checkout) — superseded by the round-3 closure",
+          "detail": "Stored compare red on checkout only (56.7 -> 133.5ms, +135%); same-window sentinel did NOT clear it (sentinel 70.3ms vs HEAD 133.5ms), so it could not be adjudicated as noise; all other phases in band or faster. Deferred to a wall-time bisect."
+        },
+        {
+          "source": "m7-attestation round 2 wall-time bisect (HEAD 5535368, quiet load 2.0-3.5)",
+          "verdict": "red reproduced; bisected to ea416c8 — superseded by the round-3 closure",
+          "detail": "Checkout red reproduced (104.5ms vs same-window sentinel 77.2ms). Median-of-5 wall bisect c1937a3..3669c7b in a detached worktree, alternating probe order: first bad commit ea416c8 (scope run reads; fork before tokio). Checkout-phase FUSE profile counters identical parent-vs-culprit, locating the tax in the run-sandbox environment, not the FUSE hot path. Round 2 also established the brittle-phase repeat rule after a first-run diff red (+45%) evaporated on repeat."
+        },
+        {
+          "source": "m7-opt-sandbox-bringup closure (HEAD dae8aa6, quiet load 3.4-4.2)",
+          "verdict": "in band (0 red phases) — checkout red CLOSED with zero code change",
+          "detail": "Root cause: the bisect-era workload ran PATH git = the ~/.git-ai/bin/git shim inside the sandbox namespace; ea416c8's namespace pushed the shim's daemon/state logic onto a slow path per git call. dae8aa6 pins /usr/bin/git through the sandbox and harnesses, removing the tax from both legs. Official candidate/sentinel pair plus mandated brittle-phase repeat vs the stored post-M3 baseline: repeat 0 red, all 7 phases in band (checkout 56.7 -> 56.9ms +0.4%, clone +2.9%; the first candidate run's clone +24.3% red evaporated on the repeat). Same-window sentinel green; candidate checkout beat the sentinel by 17%. Exact-bench-shape zone attribution showed no measurable sandbox cost on any variant. Evidence: evidence/m7-cli-docs/m7-opt-sandbox-bringup/, library/perf-contract.md CLOSED entry."
+        },
+        {
+          "source": "m7-attestation final (attested HEAD 230c30a)",
+          "verdict": "in band (0 red phases, cited pair)",
+          "detail": "medians.json records the dae8aa6 official repeat pair vs the active post-M3 baseline: all 7 phases passed (checkout +0.4%, clone +2.9%, every other phase faster than baseline). Cited at 230c30a per the orchestrator round-3 ruling: the only commit after dae8aa6 changes cfg(target_os=macos) code, docs, and clap help text only — Linux binary perf semantics unchanged."
+        }
+      ]
+    }
+  ]
+}