From 86f32cf9ee93746a42d62f8734a6762f97e404c3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 01:47:29 +0000 Subject: [PATCH 01/14] fix: SPDX on ffi/zig main.zig, block-aware SPDX lint, alkahest pins - ffi/zig/src/main.zig: add `// SPDX-License-Identifier: MPL-2.0` on line 1 (owner-authorised; code is MPL-2.0 under standards LICENCE-POLICY Rule 1). Closes Hypatia SD009. - workflow-linter.yml: the SPDX check reads the leading comment block, the estate governance predicate, instead of line 1 only, so a `gh actions-lock` comment above the header no longer fails it (owner ruling 2026-11-17). - alkahest-shell-transmuter: there is no separate upstream repository, so the fix lands here. codeql-action init/analyze pinned to the real v3.28.0 commit (48ab28a); the fabricated trufflehog pin and the curl|sh Radicle install are replaced by the estate secret-scanner and mirror wrappers (metadatastician/standards@75bd599), as in the root. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .github/workflows/workflow-linter.yml | 11 +- .../.github/workflows/codeql.yml | 4 +- .../.github/workflows/mirror.yml | 126 +++--------------- .../.github/workflows/secret-scanner.yml | 53 ++------ ffi/zig/src/main.zig | 1 + 5 files changed, 42 insertions(+), 153 deletions(-) diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 67b6a824..99d645f7 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -20,12 +20,19 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4 - name: Check SPDX headers + # The identifier must be in the file's LEADING comment block, not on + # line 1 exactly: this is the predicate of the estate governance check + # (metadatastician/standards governance-reusable.yml, tested by + # scripts/tests/spdx-header-block-test.sh). `gh actions-lock` inserts + # a "managed by" comment at line 1, so a line-1 test fails headers + # that are present. run: | errors=0 for f in .github/workflows/*.yml .github/workflows/*.yaml; do [ -f "$f" ] || continue - if ! head -1 "$f" | grep -q "SPDX-License-Identifier"; then - echo "ERROR: $f missing SPDX header" + if ! awk '/^---[[:space:]]*$/ { next } /^#/ { print; next } { exit }' "$f" \ + | grep -q "^# SPDX-License-Identifier:"; then + echo "ERROR: $f has no SPDX-License-Identifier in its leading comment block" errors=$((errors + 1)) fi done diff --git a/alkahest-shell-transmuter/.github/workflows/codeql.yml b/alkahest-shell-transmuter/.github/workflows/codeql.yml index 55d4f909..73d1fcb0 100644 --- a/alkahest-shell-transmuter/.github/workflows/codeql.yml +++ b/alkahest-shell-transmuter/.github/workflows/codeql.yml @@ -38,7 +38,7 @@ jobs: - name: Checkout repository uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Initialize CodeQL - uses: github/codeql-action/init@ea9e4e37992a54ee68a9571571f9a567d8f90f78 # v3.28.0 + uses: github/codeql-action/init@48ab28a6f5dbc2a99bf1e0131198dd8f1df78169 # v3.28.0 with: languages: ${{ matrix.language }} build-mode: ${{ matrix.build-mode }} @@ -53,6 +53,6 @@ jobs: # Java: ./gradlew build || mvn compile echo "Configure your build command above for manual build mode languages" - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@ea9e4e37992a54ee68a9571571f9a567d8f90f78 # v3.28.0 + uses: github/codeql-action/analyze@48ab28a6f5dbc2a99bf1e0131198dd8f1df78169 # v3.28.0 with: category: "/language:${{ matrix.language }}" diff --git a/alkahest-shell-transmuter/.github/workflows/mirror.yml b/alkahest-shell-transmuter/.github/workflows/mirror.yml index 98c185d9..d7102959 100644 --- a/alkahest-shell-transmuter/.github/workflows/mirror.yml +++ b/alkahest-shell-transmuter/.github/workflows/mirror.yml @@ -1,115 +1,25 @@ # SPDX-License-Identifier: MPL-2.0 -# SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell name: Mirror to Git Forges + on: push: branches: [main] workflow_dispatch: -permissions: read-all + +permissions: + actions: read + contents: read + jobs: - mirror-gitlab: - runs-on: ubuntu-latest - if: vars.GITLAB_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.GITLAB_SSH_KEY }} - - name: Mirror to GitLab - run: | - ssh-keyscan -t ed25519 gitlab.com >> ~/.ssh/known_hosts - git remote add gitlab git@gitlab.com:hyperpolymath/${{ github.event.repository.name }}.git || true - git push --force gitlab main - mirror-bitbucket: - runs-on: ubuntu-latest - if: vars.BITBUCKET_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.BITBUCKET_SSH_KEY }} - - name: Mirror to Bitbucket - run: | - ssh-keyscan -t ed25519 bitbucket.org >> ~/.ssh/known_hosts - git remote add bitbucket git@bitbucket.org:hyperpolymath/${{ github.event.repository.name }}.git || true - git push --force bitbucket main - mirror-codeberg: - runs-on: ubuntu-latest - if: vars.CODEBERG_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.CODEBERG_SSH_KEY }} - - name: Mirror to Codeberg - run: | - ssh-keyscan -t ed25519 codeberg.org >> ~/.ssh/known_hosts - git remote add codeberg git@codeberg.org:hyperpolymath/${{ github.event.repository.name }}.git || true - git push --force codeberg main - mirror-sourcehut: - runs-on: ubuntu-latest - if: vars.SOURCEHUT_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.SOURCEHUT_SSH_KEY }} - - name: Mirror to SourceHut - run: | - ssh-keyscan -t ed25519 git.sr.ht >> ~/.ssh/known_hosts - git remote add sourcehut git@git.sr.ht:~hyperpolymath/${{ github.event.repository.name }} || true - git push --force sourcehut main - mirror-disroot: - runs-on: ubuntu-latest - if: vars.DISROOT_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.DISROOT_SSH_KEY }} - - name: Mirror to Disroot - run: | - ssh-keyscan -t ed25519 git.disroot.org >> ~/.ssh/known_hosts - git remote add disroot git@git.disroot.org:hyperpolymath/${{ github.event.repository.name }}.git || true - git push --force disroot main - mirror-gitea: - runs-on: ubuntu-latest - if: vars.GITEA_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - uses: webfactory/ssh-agent@dc588b651fe13675774614f8e6a936a468676387 # v0.9.0 - with: - ssh-private-key: ${{ secrets.GITEA_SSH_KEY }} - - name: Mirror to Gitea - run: | - ssh-keyscan -t ed25519 ${{ vars.GITEA_HOST }} >> ~/.ssh/known_hosts - git remote add gitea git@${{ vars.GITEA_HOST }}:hyperpolymath/${{ github.event.repository.name }}.git || true - git push --force gitea main - mirror-radicle: - runs-on: ubuntu-latest - if: vars.RADICLE_MIRROR_ENABLED == 'true' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 - - name: Install Radicle - run: | - curl -sSf https://radicle.xyz/install | sh - echo "$HOME/.radicle/bin" >> $GITHUB_PATH - - name: Mirror to Radicle - run: | - echo "${{ secrets.RADICLE_KEY }}" > ~/.radicle/keys/radicle - chmod 600 ~/.radicle/keys/radicle - rad sync --announce || echo "Radicle sync attempted" + mirror: + uses: metadatastician/standards/.github/workflows/mirror-reusable.yml@75bd5994470661a099df562d6d5ad2fe744dbd66 + # Explicit secrets map, not `secrets: inherit` (Hypatia WH008): the callee + # (standards@75bd5994) declares exactly these seven, all optional. + secrets: + GITLAB_SSH_KEY: ${{ secrets.GITLAB_SSH_KEY }} + BITBUCKET_SSH_KEY: ${{ secrets.BITBUCKET_SSH_KEY }} + CODEBERG_SSH_KEY: ${{ secrets.CODEBERG_SSH_KEY }} + SOURCEHUT_SSH_KEY: ${{ secrets.SOURCEHUT_SSH_KEY }} + DISROOT_SSH_KEY: ${{ secrets.DISROOT_SSH_KEY }} + GITEA_SSH_KEY: ${{ secrets.GITEA_SSH_KEY }} + RADICLE_KEY: ${{ secrets.RADICLE_KEY }} diff --git a/alkahest-shell-transmuter/.github/workflows/secret-scanner.yml b/alkahest-shell-transmuter/.github/workflows/secret-scanner.yml index 0899a46e..c3027f7a 100644 --- a/alkahest-shell-transmuter/.github/workflows/secret-scanner.yml +++ b/alkahest-shell-transmuter/.github/workflows/secret-scanner.yml @@ -1,49 +1,20 @@ # SPDX-License-Identifier: MPL-2.0 -# Prevention workflow - scans for hardcoded secrets before they reach main name: Secret Scanner + on: pull_request: push: branches: [main] -permissions: read-all -jobs: - trufflehog: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - with: - fetch-depth: 0 # Full history for scanning - - name: TruffleHog Secret Scan - uses: trufflesecurity/trufflehog@8a8ef8526528d8a4ff3e2c90be08e25ef8efbd9b # v3 - with: - extra_args: --only-verified --fail - # Rust-specific: Check for hardcoded crypto values - rust-secrets: - runs-on: ubuntu-latest - if: hashFiles('**/Cargo.toml') != '' - steps: - - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 - - name: Check for hardcoded secrets in Rust - run: | - # Patterns that suggest hardcoded secrets - PATTERNS=( - 'const.*SECRET.*=.*"' - 'const.*KEY.*=.*"[a-zA-Z0-9]{16,}"' - 'const.*TOKEN.*=.*"' - 'let.*api_key.*=.*"' - 'HMAC.*"[a-fA-F0-9]{32,}"' - 'password.*=.*"[^"]+"' - ) - found=0 - for pattern in "${PATTERNS[@]}"; do - if grep -rn --include="*.rs" -E "$pattern" src/; then - echo "WARNING: Potential hardcoded secret found matching: $pattern" - found=1 - fi - done +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true - if [ $found -eq 1 ]; then - echo "::error::Potential hardcoded secrets detected. Use environment variables instead." - exit 1 - fi +permissions: + contents: read + +jobs: + scan: + permissions: + contents: read + uses: metadatastician/standards/.github/workflows/secret-scanner-reusable.yml@75bd5994470661a099df562d6d5ad2fe744dbd66 diff --git a/ffi/zig/src/main.zig b/ffi/zig/src/main.zig index 945b777a..5de795e8 100644 --- a/ffi/zig/src/main.zig +++ b/ffi/zig/src/main.zig @@ -1,3 +1,4 @@ +// SPDX-License-Identifier: MPL-2.0 // VALENCE_SHELL FFI Implementation // // This module implements the C-compatible FFI declared in src/abi/Foreign.idr From 1dda7e938f712b3b4a152abd6b170be17f087a2a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 01:52:33 +0000 Subject: [PATCH 02/14] fix: harden-runner blocks egress in hypatia-scan; last parser expects Hypatia on #229 (13 findings, down from 98): - RE002: hypatia-scan's harden-runner was in audit mode on a push-to-main workflow. It now blocks, allowing only the hosts the job uses: GitHub (checkout, clones, API, SARIF upload), the BEAM/Hex builds that setup-beam and mix fetch, Actions artifact storage, and the Green Web Foundation API one Hypatia rule queries. - expect_in_hot_path: the three remaining expects in parser.rs (AssignDefault, ErrorIfUnset, the elif state machine) become matches or a returned parse error. Same behaviour; cargo test 827 passed. - SD022: the audit record's Agda tarball path is qualified. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .github/workflows/hypatia-scan.yml | 30 +++++++++++---- .../2026-11-16-hypatia-remediation.adoc | 2 +- impl/rust-cli/src/parser.rs | 38 +++++++------------ 3 files changed, 38 insertions(+), 32 deletions(-) diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 31da23c2..aedcd5df 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -47,15 +47,31 @@ jobs: timeout-minutes: 30 steps: - # Hypatia RE001: the scan job holds GITHUB_TOKEN and the fleet PAT next - # to fetched code (the Hypatia and gitbot-fleet clones, the mix build). - # Audit mode records every outbound connection without blocking; the - # job's endpoints (hex.pm, GitHub, the Elixir builds) are too many to - # enumerate safely as a block list here. - - name: Monitor outbound requests (audit) + # Hypatia RE001/RE002: the scan job holds GITHUB_TOKEN and the fleet PAT + # next to fetched code (the Hypatia and gitbot-fleet clones, the mix + # build), so outbound traffic is blocked except for the hosts it needs: + # GitHub (checkout, clones, API, SARIF upload, PR comment), the BEAM and + # Hex builds setup-beam and mix fetch, Actions artifact storage, and the + # Green Web Foundation API one Hypatia rule queries. If a run reports a + # blocked endpoint, add it here deliberately. + - name: Restrict outbound requests to the scan's known hosts uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: - egress-policy: audit + egress-policy: block + allowed-endpoints: >- + github.com:443 + api.github.com:443 + codeload.github.com:443 + objects.githubusercontent.com:443 + release-assets.githubusercontent.com:443 + raw.githubusercontent.com:443 + uploads.github.com:443 + builds.hex.pm:443 + repo.hex.pm:443 + hex.pm:443 + results-receiver.actions.githubusercontent.com:443 + *.blob.core.windows.net:443 + api.thegreenwebfoundation.org:443 - name: Checkout repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6.0.2 diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index dec3dd02..02fa449e 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -58,7 +58,7 @@ They close when the underlying alert closes. | RE001 (3) | fixed | `harden-runner`: `block` to `api.github.com` in `instant-sync.yml`, `block` to the SMTP endpoint in `push-email-notify.yml`, `audit` in `hypatia-scan.yml`. | RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; see <>. | WH008 (3) | fixed | See the Secret Scanner section. -| SD022 (2) | fixed | Both paths named another tree (`echidna/src/rust/`, the Agda tarball's `src/data/lib`); now qualified. +| SD022 (2) | fixed | Both paths named another tree (`echidna/src/rust/`, the Agda tarball path `agda-2.7.0.1/src/data/lib`); now qualified. | SD009 | left for the owner | `ffi/zig/src/main.zig` has no SPDX header. Licence edits are owner-only (estate doctrine 6). | SD004 (6), SD007 | left for the owner | Moving `.machine_readable/6a2/` into deed clauses needs the estate converter (kyX, standards D312/D313); writing the clauses by hand would guess at metadata. | `known_fake_action_sha` (3), `download_then_run_shell` (1) in `alkahest-shell-transmuter/` | left for upstream | Owner ruling: fix the canonical alkahest repository, then re-sync this copy. These workflows never run here. diff --git a/impl/rust-cli/src/parser.rs b/impl/rust-cli/src/parser.rs index da677ce3..9f31a40b 100644 --- a/impl/rust-cli/src/parser.rs +++ b/impl/rust-cli/src/parser.rs @@ -2281,17 +2281,11 @@ fn apply_expansion(expansion: &ParameterExpansion, state: &crate::state::ShellSt // Semantic assignment requires threading mutable state (and error // propagation) through the expansion API; tracked by #189. Until // that seam is redesigned this returns the default value only. - if is_unset || (*check_null && is_null) { + match var_value { + Some(v) if !(*check_null && is_null) => v.to_string(), // Note: In bash, this would also assign to VAR. // Requires signature change: &mut ShellState - expand_variables(value, state) - } else { - // var_value is Some by construction here: the surrounding - // `if is_unset || ...` branch is the unset/null path; this - // else branch only fires when var_value is Some. - var_value - .expect("var_value is Some when !is_unset (checked above)") - .to_string() + _ => expand_variables(value, state), } } @@ -2309,18 +2303,14 @@ fn apply_expansion(expansion: &ParameterExpansion, state: &crate::state::ShellSt check_null, } => { // ${VAR:?message} or ${VAR?message} - if is_unset || (*check_null && is_null) { - let error_msg = message.as_deref().unwrap_or("parameter null or not set"); - eprintln!("vsh: {}: {}", expansion.var_name, error_msg); - // Return empty string (bash exits non-interactively, but we continue) - String::new() - } else { - // var_value is Some by construction here: the surrounding - // `if is_unset || ...` branch is the unset/null path; this - // else branch only fires when var_value is Some. - var_value - .expect("var_value is Some when !is_unset (checked above)") - .to_string() + match var_value { + Some(v) if !(*check_null && is_null) => v.to_string(), + _ => { + let error_msg = message.as_deref().unwrap_or("parameter null or not set"); + eprintln!("vsh: {}: {}", expansion.var_name, error_msg); + // Return empty string (bash exits non-interactively, but we continue) + String::new() + } } } @@ -2925,9 +2915,9 @@ fn parse_if_command(input: &str) -> Result { // earlier ("elif", "after_then") arm set pending_condition // to Some. The match is exhaustive over (keyword, state) // shapes, so this take() is provably Some by construction. - let elif_cond = pending_condition - .take() - .expect("pending_condition: Some by state-machine invariant in after_elif"); + let elif_cond = pending_condition.take().ok_or_else(|| { + anyhow::anyhow!("parse error: `then` after `elif` with no pending condition") + })?; let body_str = content.trim().trim_end_matches(';').trim(); let elif_body = if !body_str.is_empty() { parse_command_block(body_str)? From 75ccf3fddc4991fc3311c61184908b095228ba82 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 01:53:35 +0000 Subject: [PATCH 03/14] ci(workflow-linter): send the SPDX error to stderr SonarCloud githubactions:S7677 on the SPDX step added in 86f32cf. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .github/workflows/workflow-linter.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 99d645f7..ae22f35a 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -32,7 +32,7 @@ jobs: [ -f "$f" ] || continue if ! awk '/^---[[:space:]]*$/ { next } /^#/ { print; next } { exit }' "$f" \ | grep -q "^# SPDX-License-Identifier:"; then - echo "ERROR: $f has no SPDX-License-Identifier in its leading comment block" + echo "ERROR: $f has no SPDX-License-Identifier in its leading comment block" >&2 errors=$((errors + 1)) fi done From cb0c908c47307146fa9798c24ff1a5dbab848627 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 01:56:26 +0000 Subject: [PATCH 04/14] chore(deed): move the retired 6a2 A2ML descriptiles into the repo deed Hypatia flags SD004 on the six .machine_readable/6a2/*.a2ml descriptiles and SD007 on .claude/CLAUDE.md. A2ML is retired (D99, D269c, D312, D313). - Archive the nine 6a2/ files verbatim with git mv under archive/a2ml-v1/6a2-*.txt (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK, the directory 0-AI-MANIFEST, anchor/ANCHOR, README). - Add valence-shell_chora.deed (repo-deed): the registry's v8 :repo-uuid and the hyperpolymath :beholding-chora, a (canon ...) pin to canon.lock 2.1.5, and the (ecosystem ...), (agentic ...), (neurosym ...) and (playbook ...) clauses, per the standards mapping specs. Fields with no table row stay as comments; nothing is invented. - Add archive/a2ml-v1/MIGRATION-LEDGER.adoc with a row for every field, the out-of-scope files and the items that need owner input (anchor :authority, maturity, the boj-server parent, the CLAUDE.md language row). - Repoint the docs that named the 6a2 paths; update the CLAUDE.md Machine-Readable Artefacts list. deed_lint (standards 151276d6): OK. SD007 stays open on the CLAUDE.md language-table row, which is owner policy (ledger U-2). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .claude/CLAUDE.md | 9 +- .machine_readable/bot_directives/README.adoc | 3 +- CHANGELOG.adoc | 12 + ROADMAP.adoc | 4 +- .../a2ml-v1/6a2-0-AI-MANIFEST.a2ml.txt | 0 .../a2ml-v1/6a2-AGENTIC.a2ml.txt | 0 .../a2ml-v1/6a2-ECOSYSTEM.a2ml.txt | 0 .../a2ml-v1/6a2-META.a2ml.txt | 0 .../a2ml-v1/6a2-NEUROSYM.a2ml.txt | 0 .../a2ml-v1/6a2-PLAYBOOK.a2ml.txt | 0 .../a2ml-v1/6a2-README.adoc.txt | 0 .../a2ml-v1/6a2-STATE.a2ml.txt | 0 .../a2ml-v1/6a2-anchor-ANCHOR.a2ml.txt | 0 archive/a2ml-v1/MIGRATION-LEDGER.adoc | 240 ++++++++++++++++++ docs/README.adoc | 6 +- proofs/coq/README.adoc | 14 +- valence-shell_chora.deed | 169 ++++++++++++ 17 files changed, 441 insertions(+), 16 deletions(-) rename .machine_readable/6a2/0-AI-MANIFEST.a2ml => archive/a2ml-v1/6a2-0-AI-MANIFEST.a2ml.txt (100%) rename .machine_readable/6a2/AGENTIC.a2ml => archive/a2ml-v1/6a2-AGENTIC.a2ml.txt (100%) rename .machine_readable/6a2/ECOSYSTEM.a2ml => archive/a2ml-v1/6a2-ECOSYSTEM.a2ml.txt (100%) rename .machine_readable/6a2/META.a2ml => archive/a2ml-v1/6a2-META.a2ml.txt (100%) rename .machine_readable/6a2/NEUROSYM.a2ml => archive/a2ml-v1/6a2-NEUROSYM.a2ml.txt (100%) rename .machine_readable/6a2/PLAYBOOK.a2ml => archive/a2ml-v1/6a2-PLAYBOOK.a2ml.txt (100%) rename .machine_readable/6a2/README.adoc => archive/a2ml-v1/6a2-README.adoc.txt (100%) rename .machine_readable/6a2/STATE.a2ml => archive/a2ml-v1/6a2-STATE.a2ml.txt (100%) rename .machine_readable/6a2/anchor/ANCHOR.a2ml => archive/a2ml-v1/6a2-anchor-ANCHOR.a2ml.txt (100%) create mode 100644 archive/a2ml-v1/MIGRATION-LEDGER.adoc create mode 100644 valence-shell_chora.deed diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index d45e019e..48f61b5f 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -18,12 +18,9 @@ The same discipline applies to `hyperpolymath/januskey` and its `reversible-core The following files in `.machine_readable/` contain structured project metadata: - `.machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml` - Bridge to echo-types + ochrance (READ FIRST) -- `.machine_readable/6a2/STATE.a2ml` - Current project state and progress -- `.machine_readable/6a2/META.a2ml` - Architecture decisions and development practices -- `.machine_readable/6a2/ECOSYSTEM.a2ml` - Position in the ecosystem and related projects -- `.machine_readable/6a2/AGENTIC.a2ml` - AI agent interaction patterns -- `.machine_readable/6a2/NEUROSYM.a2ml` - Neurosymbolic integration config -- `.machine_readable/6a2/PLAYBOOK.a2ml` - Operational runbook +- `valence-shell_chora.deed` (repo root) - The repo deed: identity, canon pin, and the descriptile clauses `(ecosystem …)`, `(agentic …)`, `(neurosym …)` and `(playbook …)`. A2ML is retired (D99, D269c, D312, D313) +- `archive/a2ml-v1/MIGRATION-LEDGER.adoc` - Where each field of the retired descriptiles went, and the items awaiting owner input +- `archive/a2ml-v1/6a2-*.txt` - The retired STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK and ANCHOR files, archived verbatim --- diff --git a/.machine_readable/bot_directives/README.adoc b/.machine_readable/bot_directives/README.adoc index 5e42adbd..07cfff53 100644 --- a/.machine_readable/bot_directives/README.adoc +++ b/.machine_readable/bot_directives/README.adoc @@ -32,7 +32,8 @@ Methodology-aware configuration for AI agents. Read by any AI agent == Relationship to Other Files -* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) +* The `(agentic …)` clause of `valence-shell_chora.deed` (formerly + `AGENTIC.a2ml`) says WHAT agents can do (permissions, gating) * `bot_directives/` says HOW agents should work (methodology) * `bot_directives/` says what the gitbot-fleet does (fleet-specific) * `CLAUDE.md` says how Claude specifically should work (Claude-specific) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index de48c3d5..0a23481a 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -11,6 +11,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 == [Unreleased] +=== Changed — 2026-11-17 (A2ML descriptiles moved into the repo deed) + +- The retired `.machine_readable/6a2/` A2ML files (STATE, META, ECOSYSTEM, + AGENTIC, NEUROSYM, PLAYBOOK, the directory manifest, the anchor and the + directory README) are archived verbatim under `archive/a2ml-v1/` with their + history. Their content now lives in `valence-shell_chora.deed`, a + `repo-deed` that passes the standards `deed_lint`. Fields with no mapping row + are kept as comments, and every field's disposition, including the items + that need owner input, is in `archive/a2ml-v1/MIGRATION-LEDGER.adoc`. + Addresses Hypatia SD004; SD007 stays open on one owner-policy line of + `.claude/CLAUDE.md` (ledger row U-2). + === Changed — 2026-11-01 (assurance-boundary re-audit) - Corrected prose that had drifted across the assurance boundary. The audit diff --git a/ROADMAP.adoc b/ROADMAP.adoc index a708b790..c42d486d 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -5,8 +5,8 @@ == Current Status -v0.9.0 (advanced research prototype, ~74% complete per -`.machine_readable/6a2/STATE.a2ml`). +v0.9.0 (advanced research prototype, ~74% complete per the retired +`STATE.a2ml`, archived at `archive/a2ml-v1/6a2-STATE.a2ml.txt`). The Rust CLI in `impl/rust-cli/` is a functional interactive shell with reversible filesystem operations, transaction grouping, and diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/archive/a2ml-v1/6a2-0-AI-MANIFEST.a2ml.txt similarity index 100% rename from .machine_readable/6a2/0-AI-MANIFEST.a2ml rename to archive/a2ml-v1/6a2-0-AI-MANIFEST.a2ml.txt diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/archive/a2ml-v1/6a2-AGENTIC.a2ml.txt similarity index 100% rename from .machine_readable/6a2/AGENTIC.a2ml rename to archive/a2ml-v1/6a2-AGENTIC.a2ml.txt diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/archive/a2ml-v1/6a2-ECOSYSTEM.a2ml.txt similarity index 100% rename from .machine_readable/6a2/ECOSYSTEM.a2ml rename to archive/a2ml-v1/6a2-ECOSYSTEM.a2ml.txt diff --git a/.machine_readable/6a2/META.a2ml b/archive/a2ml-v1/6a2-META.a2ml.txt similarity index 100% rename from .machine_readable/6a2/META.a2ml rename to archive/a2ml-v1/6a2-META.a2ml.txt diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/archive/a2ml-v1/6a2-NEUROSYM.a2ml.txt similarity index 100% rename from .machine_readable/6a2/NEUROSYM.a2ml rename to archive/a2ml-v1/6a2-NEUROSYM.a2ml.txt diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/archive/a2ml-v1/6a2-PLAYBOOK.a2ml.txt similarity index 100% rename from .machine_readable/6a2/PLAYBOOK.a2ml rename to archive/a2ml-v1/6a2-PLAYBOOK.a2ml.txt diff --git a/.machine_readable/6a2/README.adoc b/archive/a2ml-v1/6a2-README.adoc.txt similarity index 100% rename from .machine_readable/6a2/README.adoc rename to archive/a2ml-v1/6a2-README.adoc.txt diff --git a/.machine_readable/6a2/STATE.a2ml b/archive/a2ml-v1/6a2-STATE.a2ml.txt similarity index 100% rename from .machine_readable/6a2/STATE.a2ml rename to archive/a2ml-v1/6a2-STATE.a2ml.txt diff --git a/.machine_readable/6a2/anchor/ANCHOR.a2ml b/archive/a2ml-v1/6a2-anchor-ANCHOR.a2ml.txt similarity index 100% rename from .machine_readable/6a2/anchor/ANCHOR.a2ml rename to archive/a2ml-v1/6a2-anchor-ANCHOR.a2ml.txt diff --git a/archive/a2ml-v1/MIGRATION-LEDGER.adoc b/archive/a2ml-v1/MIGRATION-LEDGER.adoc new file mode 100644 index 00000000..c67afc73 --- /dev/null +++ b/archive/a2ml-v1/MIGRATION-LEDGER.adoc @@ -0,0 +1,240 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Migration ledger: `.machine_readable/6a2/` A2ML to the repo deed (valence-shell, 2026-11-17) +:toc: + +This ledger records every field of the retired `.machine_readable/6a2/` files: +where it went, why it did not move, or what the owner must supply. Row IDs match +the comments in `valence-shell_chora.deed`. + +Why now: Hypatia reported SD004 on the six `.machine_readable/6a2/*.a2ml` +descriptiles ("descriptile in retired location; the current canon keeps +descriptiles as clauses of the repo deed") and SD007 on `.claude/CLAUDE.md`, +which named `.machine_readable/6a2/`. A2ML is retired (D99, D269c, D312, D313). + +Authorities, all read on 2026-11-17: + +* `metadatastician/standards` at `151276d6`: `1-formats/deed/spec/abnf/deed.abnf` + (v2.0.0), `1-formats/deed/tools/README.adoc`, the mapping specs in + `1-formats/deed/mappings/` (`meta-ecosystem-to-repo-deed`, + `agentic-neurosym-playbook-to-repo-deed`, `state-v1-decision` (option B), + `ai-manifest-decision` (option A), `clade-to-repo-deed`, `README`), + `canon.lock`, `2-protocols/chora/CHORA-SPEC.adoc` (sections 9 and 11.1) and + `docs/estate-reconciliation/A7-contractiles-descriptiles-anchor.adoc` + (section 6.4, the anchor table). +* Precedent: `hyperpolymath/absolute-zero` at `8a3162a`, + `absolute-zero_chora.deed` and `archive/a2ml-v1/MIGRATION-LEDGER.adoc`. +* Registry: `hyperpolymath/gv-clade-index` at `09ef2838`, + `verisim/seed/chora-registry_praxis.deed`. + +== Archive map + +The nine files were moved with `git mv`, so their history is kept. The +`.machine_readable/6a2/` directory no longer exists. + +[cols="3,3",options="header"] +|=== +| Source (before) | Archived as +| `.machine_readable/6a2/STATE.a2ml` | `6a2-STATE.a2ml.txt` +| `.machine_readable/6a2/META.a2ml` | `6a2-META.a2ml.txt` +| `.machine_readable/6a2/ECOSYSTEM.a2ml` | `6a2-ECOSYSTEM.a2ml.txt` +| `.machine_readable/6a2/AGENTIC.a2ml` | `6a2-AGENTIC.a2ml.txt` +| `.machine_readable/6a2/NEUROSYM.a2ml` | `6a2-NEUROSYM.a2ml.txt` +| `.machine_readable/6a2/PLAYBOOK.a2ml` | `6a2-PLAYBOOK.a2ml.txt` +| `.machine_readable/6a2/0-AI-MANIFEST.a2ml` | `6a2-0-AI-MANIFEST.a2ml.txt` +| `.machine_readable/6a2/anchor/ANCHOR.a2ml` | `6a2-anchor-ANCHOR.a2ml.txt` +| `.machine_readable/6a2/README.adoc` | `6a2-README.adoc.txt` +|=== + +The archived files are byte-identical to their sources. Two of them, +`6a2-0-AI-MANIFEST.a2ml.txt` and `6a2-anchor-ANCHOR.a2ml.txt`, carried no SPDX +header in the source and still carry none: a header was not added, because an +archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). + +== Where each file went + +[cols="2,4",options="header"] +|=== +| Source | Destination +| META | Nothing emitted; every key fails closed (M-1 to M-5). Kept as deed comments. +| ECOSYSTEM | `(ecosystem :project :ecosystem :position-type)` in the deed; the rest as comments (E-1 to E-5). +| AGENTIC | `(agentic :version :last-updated (permissions …))` in the deed; constraints and bridge rules as comments (A-1 to A-4). +| NEUROSYM | `(neurosym :version :last-updated (hypatia …))` in the deed (N-1, N-2). +| PLAYBOOK | `(playbook :version :last-updated (deployment) (incident-response) (release-process))`; commented content kept as comments (P-1 to P-4). +| STATE | Option B: nothing emitted; journal archived (S-1 to S-9). +| 6a2/0-AI-MANIFEST | Archived only (G-1). +| 6a2/README | Archived only (R-1). +| anchor/ANCHOR | No `(anchor …)` clause yet; fields recorded as comments with their A7 6.4 destinations (AN-1 to AN-7). +|=== + +== Ledger rows + +=== Target form + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| T-1 | Clause form vs the A7 split form | The descriptiles are clauses of `valence-shell_chora.deed`, as the absolute-zero precedent and Hypatia SD004 name them. The *more elegant long-term option*, and the current mapping specs' stated target, is the A7 split: `.machine_readable/descriptiles/{META,ECOSYSTEM,AGENTIC,NEUROSYM}.deed` (`descriptile-deed`, J30, J33, J35), with `(playbook …)` staying in the chora deed. This change departs from it because (a) A7 is a draft and its profiles gate only their own fixtures; (b) every `descriptile-deed` requires `:affirmed` and `:affirmed-by` (J4), an affirmation no translator may give for the owner; (c) the readers today (Hypatia's RSR scorer, `deed_lint`) accept the chora clauses, and A7 reads a chora `(agentic …)` or `(neurosym …)` with a warning for one release (YF05, YF06). Owner decision: when to move to the split form. +|=== + +=== Identity and canon pin + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| I-1 | `:repo-uuid` | Emitted as `#uuid"4f114668-94c6-8a71-a7b1-cd69345c08ad"`. Source: the registry seed `verisim/seed/chora-registry_praxis.deed` in `hyperpolymath/gv-clade-index` at `09ef2838` holds `(repo :name "valence-shell" :owner "hyperpolymath" :uuid #uuid"4f114668-…" :minted-in gv-clade-index …)`, with no `(former …)`, so the birth path is `github.com/hyperpolymath/valence-shell`. Cross-check: the ADR-008 profile C UUIDv8 of `gv-clade-index:github.com/hyperpolymath/valence-shell` recomputes to the same value; the same recipe reproduces absolute-zero's registry id. The legacy UUID in `.machine_readable/CLADE.a2ml` is a version 5 value and was not used (V8, Q2). The opaque `#uuid` form is used (U4); no `deed_lint` older than `#uuid` is pinned here (the dogfood gate's validator scans `.a2ml` only). *Owner check recommended:* the value was read from a fresh public clone of the registry, not from a pinned copy. +| I-2 | `:beholding-chora` | Emitted as `#uuid"0889b37b-defb-831f-973c-e119500db00e"`, the hyperpolymath estate id in the CHORA-SPEC section 9 table, recomputed from `chora:estate/github.com/hyperpolymath`. The birth estate is hyperpolymath (B1). +| I-3 | `(identity …)`, `(clade …)`, `(forges …)`, `(lineage …)`, `(status …)` | Not emitted. Their source is `.machine_readable/CLADE.a2ml`, out of scope here (O-1). CHORA-SPEC 5.4 (draft) makes `(identity …)` required once; that lands with the CLADE migration. +| C-1 | `(canon …)` pin | Emitted with `:version "2.1.5"`, `:criteria-sha256` and `:gates-sha256` copied from `canon.lock` `[canon]` and `[canon.artifacts]` at standards `151276d6`, and read back with standards' own `deed_canon` reader. `canon.lock` marks the release `status = "draft"`. `:lockstep-since` is not emitted: it is a per-repo adoption date the source does not carry. +|=== + +=== META + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| M-1 | `[metadata] project = "valence-shell"` | No table row (the family-2 `[metadata]` rows are `version` and `last-updated`). The value equals the deed's `:canonical-name`. Kept as a comment. +| M-2 | `[metadata] author` | Fail closed: the table row is `[project-info] author`, not `[metadata] author`; a corner shape extends the table, it is never translated ad hoc. Kept as a comment. +| M-3 | `[metadata] license = "MPL-2.0"` | Fail closed for the same reason. A `:license` is also a licence surface, which is owner-only. Kept as a comment. +| M-4 | `[metadata] standard = "RSR 2026"` | No table row. Kept as a comment. +| M-5 | No `version`, `last-updated`, ADRs, development practices or maintenance axes in the source | Nothing emitted, nothing invented, so no `(meta …)` clause (drop doctrine: a clause exists when it carries content). Hypatia's RSR criterion for META therefore reads no deed carrier; it did not read `6a2/` either. +|=== + +=== ECOSYSTEM + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| E-1 | `[metadata] project`, `ecosystem`; `[position] type` | Emitted as `:project "valence-shell"` (equals `:canonical-name`, P-6), `:ecosystem "hyperpolymath"`, `:position-type "component"`. +| E-2 | `[position] role = "operational-shell-layer"` | No table row (the `[position]` rows are `type`, `purpose`, `what-this-is-not`). Kept as a comment. +| E-3 | `[architecture]` (layer, layer-name, semantics-layer, receipts-layer) | No table row. Kept as a comment. +| E-4 | `[bridges.echo-types]`, `[bridges.ochrance]` | No table row, and not `[related-projects]` entries, so no `(related …)` is emitted: the source states no `relationship` from the closed set and no `notes`. The bridge's authority is `docs/ECHO-TYPES-OCHRANCE-BRIDGE.adoc` and `.machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml` (O-4). Owner input if these should become `(related …)` edges: the relationship term for each. +| E-5 | `[bridge-entry-points]` | No table row. Both paths still resolve; kept as a comment. +| E-6 | Source header comment "Forbidden-moves codified in `.machine_readable/MUST.contractile`" | Stale: no such file exists in the tree. Recorded, not fixed (the AGENTIC constraints text repeats it, A-2). +|=== + +=== AGENTIC + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| A-1 | `[metadata] version`, `last-updated`; `[agent-permissions]` | Emitted: `:version "0.1.0"`, `:last-updated "2026-03-16"`, `(permissions :source #t :tests #t :docs #t :config #t :create-files #t)`. +| A-2 | `[agent-constraints]` (comment-carried) | D4-1: the block diverges from template canon (it adds the bridge forbidden moves), so it fails closed. The family-4 table says a populated constraint is an edict, a `(rule …)` in `Mustfile.deed` (A7 YL3), and the contractiles are out of scope (O-2). Kept verbatim as deed comments. Owner input: the edicts, when the contractiles migrate. +| A-3 | `[bridge-aware-rules]` | No table row. Kept verbatim as deed comments. The CI script and workflow it names exist and still run. +| A-4 | `[maintenance-integrity]`, `[methodology]`, `[automation-hooks]` | Absent from the source, so `(integrity …)`, `(methodology …)` and `(hooks …)` are not emitted. The integrity booleans are not copied from the estate template: that would invent per-repo state. +|=== + +=== NEUROSYM + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| N-1 | `[metadata]`; `[hypatia-config] scan-enabled`, `scan-depth` | Emitted: `:version "0.1.0"`, `:last-updated "2026-03-16"`, `(hypatia :scan-enabled #t :scan-depth standard …)`. +| N-2 | `[hypatia-config] report-format = "logtalk"` | Emitted as `:report-format "json"`. This is the table's migration rule, not a guess: "`logtalk`", a retired format, becomes `"json"` and is never carried across. (absolute-zero, migrated before the rule, carried its value verbatim.) +|=== + +=== PLAYBOOK + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| P-1 | `[metadata] version`, `last-updated` | Emitted. +| P-2 | `[deployment]`, `[incident-response]`, `[release-process]` | They hold no keys, only commented text, so they are slot-preserved as empty clauses (family-1 slot doctrine, as the table rules). The commented text is kept verbatim as deed comments. +| P-3 | `[docs-format]`, `[maintenance-operations]`, `@profile` | Absent from the source. Not emitted: a slot with no source section would be invented structure. +| P-4 | Commented steps name `.machine_readable/STATE.a2ml` and `META.a2ml` | Stale: neither path is live. Owner input: the replacement steps (the deed and the archive). +|=== + +=== STATE (option B) + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| S-1 | `[metadata] status = "active"` | Not emitted. It duplicates the CLADE phase; the one lifecycle claim is the `(status …)` clause of `STATE.deed` (A7 J15), whose source is CLADE (O-1). +| S-2 | `[project-context] phase = "advanced-research-prototype"` | Not emitted. It is neither a lifecycle phase nor a maturity level (`experimental alpha beta production lts`), and picking one would be a judgement, not a translation. Owner input: the `(maturity :level …)` value. +| S-3 | `[metadata] version = "0.9.0"`, `last-updated` | Not emitted; no row in option B. The semver pin is `impl/rust-cli/Cargo.toml`. +| S-4 | `[project-context] completion-percentage = 78` | Dropped (derivable, state-v1-decision section 3). Note: `ROADMAP.adoc` quotes "~74%" from this file, which held 78; recorded, not corrected. +| S-5 | `[project-context] name`, `bridge-status`, `bridge-doc`, `bridge-a2ml` | Not emitted; the name is `:canonical-name`, and the bridge facts are carried by the bridge documents (E-4). +| S-6 | `[recent-work-2026-07-01]`, `[recent-work-2026-06-02]`, `[recent-work]`, `[session-history]` | Journal. Archived, not translated (v2 thin-journal doctrine). The record continues in `CHANGELOG.adoc` and git history. +| S-7 | `[coq-proof-status]` | Derivable counts and their prose. Archived. The live authorities are `docs/PROOF_HOLES_AUDIT.adoc` and `EXPLAINME.adoc` (Proof Ledger); the docs that pointed at this block now point there or at the archive (U-3, U-4). +| S-8 | `[dogfooding-status]` | Journal-shaped disclosure. Archived. `ROADMAP.adoc` still asks for it to be added to `STATE.a2ml` (U-6). +| S-9 | `[crg]` (grade C, audit notes) | No home in option B. Archived; the dated audit is `docs/governance/CRG-AUDIT-2026-04-18.adoc`. +|=== + +=== Directory manifest, README and anchor + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| G-1 | `6a2/0-AI-MANIFEST.a2ml` | A directory manifest for the six-file `6a2/` layout (canonical locations, lock-file protocol), not the root agent-allocation manifest of ai-manifest-decision. Its keys match no family table, so it fails closed. Archived only; the layout it describes no longer exists. +| R-1 | `6a2/README.adoc` | Archived only (`6a2-README.adoc.txt`); it described the retired directory. +| AN-1 | `(anchor …)` clause | Not emitted. The legacy anchor has no `authority`, and the clause requires `:authority` exactly once; A7 6.4 says such a translation is incomplete and the translator never invents one. *Owner input:* the `:authority` value, then the clause `(anchor :schema "hyperpolymath.anchor/2" :authority "…" (metadata :version "0.9.0"))`. +| AN-2 | `id: "org.hyperpolymath.valence-shell"` | Dropped (A7 6.4): the chora `:repo-uuid` is the id. +| AN-3 | `version: "0.9.0"` | Destination `(anchor (metadata :version "0.9.0"))`; waits for AN-1. Kept as a comment. +| AN-4 | `clade: "unknown"` | Dropped from the anchor. Placements come from chora-registry, which holds `clade-12` fv (primary) and ix (rank 1) for this repo; a chora `(clade …)` lands with the CLADE migration (O-1). +| AN-5 | `status: "active"` | Dropped from the anchor; lifecycle is `STATE.deed`'s (S-1). +| AN-6 | `ssg` (engine `casket`, output_dir `public`, boj_trigger `true`, cartridge `ssg-mcp`) | Destination `META.deed` `(ssg …)` (J29), which does not exist here (T-1). Kept as a comment. Owner input: confirm the values are this repo's and not template boilerplate. +| AN-7 | `parents: ["org.hyperpolymath.boj-server"]` | Destination an ECOSYSTEM `(related … :relationship parent :uuid …)` (J26). Not emitted: the registry records valence-shell as `standalone` with no parent, so this edge conflicts with the registry. Owner ruling needed. +|=== + +=== Out of scope (not migrated in this change) + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Reason +| O-1 | `.machine_readable/CLADE.a2ml` | Excluded by the task. CLADE is not folded into a descriptile: its identity content goes to the chora deed and its lifecycle to `STATE.deed` (CHORA-SPEC 11.1, clade-to-repo-deed). Its own change. +| O-2 | `.machine_readable/contractiles/*.a2ml` | Excluded. Contractiles become edicts (`file.deed`) and K9 contracts, a separate migration. `Mustfile.a2ml` checks `six-directory-present` and `anchors-directory` name `.machine_readable/6a2/` and now fail; they already failed before (`6a2/anchors` never existed, and the `bust/`, `dust/` and `self-validating` checks name absent paths). No runner here executes them: `contractile.just` generates other checks. A2ML is frozen, so they were not edited. +| O-3 | `.machine_readable/bot_directives/*.a2ml` | Excluded. `methodology.a2ml` line 112 still says "Phase 0 reads STATE.a2ml first". Not edited (frozen A2ML). Its prose `README.adoc` was updated (U-7). +| O-4 | `.machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml` | Excluded. Named by `.github/scripts/check-bridge-forbidden-phrases.sh` as a required artefact and by `.claude/CLAUDE.md`. +| O-5 | `.machine_readable/IDRIS2_AXIOMS.a2ml` | Excluded and must stay in place: `.github/scripts/check-idris2-believe-me.sh` reads it, and `idris-verification.yml` triggers on it. +| O-6 | `.machine_readable/integrations/*.a2ml` (feedback-o-tron, proven, verisimdb, vexometer) | Not descriptiles; no mapping spec. Not touched. +| O-7 | Root `0-AI-MANIFEST.a2ml` | Not in `6a2/`. The root agent-allocation manifest has its own decision (ai-manifest-decision, option A, `(manifest …)`). Read by `Mustfile.a2ml`, `www/.well-known/ai.txt` and docs. Its own change. +| O-8 | `audits/assail-classifications.a2ml` | Not a descriptile. Not touched. +| O-9 | `alkahest-shell-transmuter/.machine_readable/6a2/` | A nested subproject with its own six `6a2/` files. Hypatia's SD004 reads only the repo root's `.machine_readable/6a2/`. Its own change. +|=== + +=== Consumers of the moved paths + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| U-1 | `.claude/CLAUDE.md` "Machine-Readable Artefacts" list | Updated to name the deed, this ledger and the archive (SD007). Nothing else in the file was changed. +| U-2 | `.claude/CLAUDE.md` language-policy table, row "Guile Scheme" | Still names `.machine_readable/6a2/STATE.a2ml`, `META.a2ml` and `ECOSYSTEM.a2ml`. Left as written: the rest of the file is owner policy. Hypatia's SD007 pattern `.machine_readable/6a2/` still matches that row, so *SD007 stays open until the owner edits it.* +| U-3 | `docs/README.adoc` (two references) | Updated to the deed, `PROOF_HOLES_AUDIT.adoc` and the archived STATE. +| U-4 | `proofs/coq/README.adoc` (three references) | Updated to the archived STATE and the live authorities. The file's own counts (`admitted = 1`) disagree with `docs/PROOF_HOLES_AUDIT.adoc` (0 admits); recorded, not corrected. +| U-5 | `ROADMAP.adoc` "Current Status" | The path updated to the archived STATE. The "~74%" figure is left as written (S-4). +| U-6 | `ROADMAP.adoc` open items "Add `[dogfooding-status]` to STATE.a2ml" and "Add 3+ ADRs to META.a2ml" | Left as written (owner's roadmap). Both name retired files, which may no longer be written; the ADR target is now `(adr …)` entries (T-1). Owner input. +| U-7 | `.machine_readable/bot_directives/README.adoc` | The `AGENTIC.a2ml` line now names the deed's `(agentic …)` clause. +| U-8 | Dated records: `CHANGELOG.adoc` history, `docs/audits/*`, `docs/governance/CRG-AUDIT-2026-04-18.adoc`, `docs/reports/*` | Left as written. +|=== + +=== Other + +[cols="1,3,4",options="header"] +|=== +| ID | Item | Disposition +| X-1 | No SPDX header in two archived sources (`6a2-0-AI-MANIFEST.a2ml.txt`, `6a2-anchor-ANCHOR.a2ml.txt`) | Not added; owner-only (licence edits are manual). +|=== + +== Validation (2026-11-17) + +[cols="3,2,5",options="header"] +|=== +| Check | Result | Notes +| `bun deed_lint.js valence-shell_chora.deed` (standards `151276d6`) | PASS | `OK valence-shell_chora.deed`. +| `deed_lint.js --ast-json` | PASS | Head `repo-deed`; top-level `:schema-version`, `:canonical-name`, `:beholding-chora`, `:repo-uuid`, and the clauses `canon`, `ecosystem`, `agentic`, `neurosym`, `playbook`. +| `deed_lint.js --anchor`, `--egress`, `--contractiles`, `--rsr-profile` | PASS | Each reports no such clause. +| standards `deed_canon` reader (from `scripts/check-canon-lockstep.sh`) | PASS | Reads `2.1.5` and both hashes. +| `.github/scripts/check-bridge-forbidden-phrases.sh` | PASS | Run after the edits. +| `git grep -n '6a2/'` | 2 live hits, both owner items | `.claude/CLAUDE.md` language table (U-2) and the frozen `Mustfile.a2ml` checks (O-2). Every other hit is in this archive and ledger, a `CHANGELOG.adoc` history entry (this change's included), a dated audit record, or the out-of-scope subproject (O-9). +|=== + +== Open items (owner) + +. Anchor `:authority` (AN-1), then the `(anchor …)` clause. +. The boj-server parent edge against the registry's `standalone` (AN-7); the `ssg` values (AN-6). +. The maturity level (S-2). +. Whether the bridges become `(related …)` edges, and with which relationship (E-4). +. The AGENTIC constraints as `Mustfile.deed` edicts (A-2). +. The `.claude/CLAUDE.md` language-table row (U-2); the `ROADMAP.adoc` items (U-6); the PLAYBOOK steps (P-4). +. When to move to the A7 split descriptile deeds, with their affirmation (T-1). +. Confirm the `:repo-uuid` read from the registry (I-1). +. SPDX headers on the two archived files that lack them (X-1). diff --git a/docs/README.adoc b/docs/README.adoc index 785b3df6..9df974eb 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -50,7 +50,8 @@ This README provides orientation; individual files are self-describing. | `PROOF_HOLES_AUDIT.adoc` | Active proof-debt ledger across the 6-system stack (Coq/Lean4/Agda/Isabelle/Mizar/Z3 + Idris2 ABI). Source of truth for - the `[coq-proof-status]` block in `../.machine_readable/6a2/STATE.a2ml`. + the `[coq-proof-status]` block of the retired `STATE.a2ml`, archived at + `../archive/a2ml-v1/6a2-STATE.a2ml.txt`. | `POSIX_COMPLIANCE.md` | Per-feature POSIX compliance tracker (M1-M11 milestones; M1-M9 @@ -105,4 +106,5 @@ This README provides orientation; individual files are self-describing. * `../README.md` / `../EXPLAINME.adoc` — repo entry points * `../CLAUDE.md` — AI-assistant honest-status document * `../ROADMAP.adoc` — release track + audit closure list -* `../.machine_readable/6a2/STATE.a2ml` — machine-readable state +* `../valence-shell_chora.deed` — the repo deed (machine-readable descriptiles); + migration record in `../archive/a2ml-v1/MIGRATION-LEDGER.adoc` diff --git a/proofs/coq/README.adoc b/proofs/coq/README.adoc index ec48ad25..96f81216 100644 --- a/proofs/coq/README.adoc +++ b/proofs/coq/README.adoc @@ -17,13 +17,15 @@ extraction. | `filesystem_model.v` | Core `Filesystem = Path -> option FSNode` model + structural lemmas. Note: this finite-domain model is the source of the - `is_empty_dir_dec` axiom (justified per `STATE.a2ml - [coq-proof-status] axiom-detail`). + `is_empty_dir_dec` axiom (justified per `[coq-proof-status] + axiom-detail` in the archived + `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`). | `filesystem_composition.v` | Composition theorems. Carries one declared `admit.` at line ~199 (`single_op_reversible` OpRmdir branch — pre-existing model gap; - see `STATE.a2ml [coq-proof-status] admitted-detail`). + see `[coq-proof-status] admitted-detail` in the archived + `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`). | `filesystem_equivalence.v` | State-equivalence relations. @@ -72,8 +74,10 @@ make all # via auto-emitted Makefile decidability; migration path: switch to `FMaps.t FSNode`). * All other proofs constructively closed. -Authoritative status in `../../.machine_readable/6a2/STATE.a2ml` -under `[coq-proof-status]`. +Authoritative status in `../../docs/PROOF_HOLES_AUDIT.adoc` and the +Proof Ledger of `../../EXPLAINME.adoc`. The former `[coq-proof-status]` +block of `STATE.a2ml` is archived at +`../../archive/a2ml-v1/6a2-STATE.a2ml.txt`. == See also diff --git a/valence-shell_chora.deed b/valence-shell_chora.deed new file mode 100644 index 00000000..ba855d81 --- /dev/null +++ b/valence-shell_chora.deed @@ -0,0 +1,169 @@ +;; SPDX-License-Identifier: MPL-2.0 +; +; The repo deed of valence-shell: the machine-readable description of this +; repository (standards#837, one deed per repo, D312). It replaces the retired +; A2ML descriptiles that lived in .machine_readable/6a2/ (AGENTIC, ECOSYSTEM, +; META, NEUROSYM, PLAYBOOK, STATE, the directory 0-AI-MANIFEST, anchor/ANCHOR +; and the directory README). They are archived verbatim, with git history, +; under archive/a2ml-v1/6a2-*.txt (D99, D269c, D312, D313). +; +; Migration ledger, fail-closed items and per-field provenance: +; archive/a2ml-v1/MIGRATION-LEDGER.adoc (row IDs below cite it) +; Mapping specs followed, from metadatastician/standards at 151276d6: +; 1-formats/deed/mappings/{meta-ecosystem-to-repo-deed, +; agentic-neurosym-playbook-to-repo-deed, state-v1-decision (option B), +; ai-manifest-decision (option A)}.adoc, and the A7 section 6.4 anchor table. +; Worked precedent: hyperpolymath/absolute-zero absolute-zero_chora.deed. +; +; Target form (ledger T-1): the descriptiles are clauses of this chora deed, +; as the absolute-zero precedent and Hypatia SD004 name them. The A7 split +; into .machine_readable/descriptiles/{META,ECOSYSTEM,AGENTIC,NEUROSYM}.deed +; is the long-term canonical form, but A7 is a draft and those heads need an +; owner affirmation (:affirmed, :affirmed-by) that no translator may supply. +; +; Anything with no mapping-table row is kept as a comment in the clause it +; belonged to, with a ledger row. Nothing was invented to fill a field. +; Out of scope for this change (ledger O-1 to O-9): .machine_readable/CLADE.a2ml, +; the contractiles, bot_directives, ECHO_TYPES_OCHRANCE_BRIDGE.a2ml, +; IDRIS2_AXIOMS.a2ml, integrations/*.a2ml, the root 0-AI-MANIFEST.a2ml, +; audits/assail-classifications.a2ml and alkahest-shell-transmuter/. +(repo-deed + :schema-version "1.0.0" + :canonical-name "valence-shell" + + ; Identity (ledger I-1, I-2). Both values are opaque v8 chora ids (U4, V8), + ; copied, never minted here. + ; :repo-uuid is the registry's id for the birth path hyperpolymath/valence-shell, + ; :minted-in gv-clade-index, read from gv-clade-index + ; verisim/seed/chora-registry_praxis.deed at 09ef2838 and re-derived with the + ; ADR-008 profile C recipe (they agree). + ; :beholding-chora is the hyperpolymath estate id, CHORA-SPEC section 9 table. + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + :repo-uuid #uuid"4f114668-94c6-8a71-a7b1-cd69345c08ad" + + ; The canon pin (vocabulary/canon.adoc): standards canon.lock [canon] version + ; and the [canon.artifacts] criteria and gates hashes, copied from + ; metadatastician/standards at 151276d6. :lockstep-since is not emitted: it + ; is a per-repo adoption date with no source here (ledger C-1). + (canon + :version "2.1.5" + :criteria-sha256 "6a5aa8857bd0d0d58ef48827938ca17c251b6b854dacf59d306388d61694d82a" + :gates-sha256 "5c510bba025be718deebb12d0333bfe7db2da43c66578b728b1a334df65290b1") + + ; ---- META.a2ml (family 2) ------------------------------------------------ + ; No (meta …) clause: every source key sits under [metadata], and the family-2 + ; table carries only version and last-updated there, which the source lacks. + ; The keys fail closed (ledger M-1 to M-5). Verbatim, for reference: + ; [metadata] project = "valence-shell" (the deed's :canonical-name) + ; [metadata] author = "Jonathan D.A. Jewell " + ; [metadata] license = "MPL-2.0" (licence surface: owner only) + ; [metadata] standard = "RSR 2026" + ; header: "Converted from META.scm on 2026-03-15" + + ; ---- ECOSYSTEM.a2ml (family 2) ------------------------------------------- + ; [position] role "operational-shell-layer" has no table row (ledger E-2). + ; [architecture] (layer 1 "operational-shell"; semantics-layer echo-types; + ; receipts-layer ochrance), [bridges.echo-types], [bridges.ochrance] and + ; [bridge-entry-points] have no table row and are not [related-projects] + ; entries, so they fail closed (ledger E-3 to E-5). Their authority is + ; docs/ECHO-TYPES-OCHRANCE-BRIDGE.adoc and + ; .machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml: the bridge is + ; documentation-and-orientation-only, mechanised = false, for both + ; hyperpolymath/echo-types and hyperpolymath/ochrance. + (ecosystem + :project "valence-shell" + :ecosystem "hyperpolymath" + :position-type "component") + + ; ---- AGENTIC.a2ml (family 4) --------------------------------------------- + ; The source has no [maintenance-integrity], [methodology] or + ; [automation-hooks], so no (integrity …), (methodology …) or (hooks …) is + ; emitted (ledger A-4). + ; [agent-constraints] is comment-carried and DIVERGES from template canon + ; (it adds the bridge forbidden moves), so D4-1 fails it closed. A populated + ; constraint is an edict for Mustfile.deed (A7 YL3), which is out of scope. + ; Kept verbatim (ledger A-2): + ; - Never use banned language patterns (believe_me, unsafeCoerce, etc.) + ; - Never commit secrets or credentials + ; - Never use banned languages (TypeScript, Python, Go, etc.) + ; - Never place state files in repository root (must be in .machine_readable/) + ; - Never use AGPL license (use MPL-2.0) + ; - Never violate the Echo Types / Ochrance bridge forbidden-moves: + ; no "production-ready", no "mechanised Lean-to-Rust", no "RMO/GDPR beyond stubs", + ; no "Echo Types proves Valence Shell implementation correctness", + ; no "Ochrance cryptographic integrity" while upstream gaps remain. + ; See docs/ECHO-TYPES-OCHRANCE-BRIDGE.adoc + MUST.contractile invariants-bridge. + ; CI-enforced via .github/scripts/check-bridge-forbidden-phrases.sh. + ; [bridge-aware-rules] has no table row (ledger A-3). Verbatim: + ; read-first = "docs/ECHO-TYPES-OCHRANCE-BRIDGE.adoc" + ; manifest = ".machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml" + ; status = "documentation-and-orientation-only"; mechanised = false + ; echo-types-audit-required = true + ; ci-enforcement-script = ".github/scripts/check-bridge-forbidden-phrases.sh" + ; ci-workflow = ".github/workflows/bridge-forbidden-phrases.yml" + (agentic + :version "0.1.0" + :last-updated "2026-03-16" + (permissions :source #t :tests #t :docs #t :config #t :create-files #t)) + + ; ---- NEUROSYM.a2ml (family 4) -------------------------------------------- + ; report-format: the source value "logtalk" is a retired format. The + ; family-4 migration rule rewrites it to "json" and never carries it across + ; (ledger N-2). + (neurosym + :version "0.1.0" + :last-updated "2026-03-16" + (hypatia + :scan-enabled #t + :scan-depth standard + :report-format "json")) + + ; ---- PLAYBOOK.a2ml (family 4) -------------------------------------------- + ; The three source sections hold no keys, only commented text, so they are + ; slot-preserved as empty clauses. Their comments, verbatim (ledger P-2, P-4): + ; [deployment] # method = "gitops" # target = "container" + ; [incident-response] 1. Check .machine_readable/STATE.a2ml for current status + ; 2. Review recent commits and CI results + ; 3. Run just validate to check compliance + ; [release-process] 1. Update version in STATE.a2ml, META.a2ml + ; 2. Run just quality (format, lint, test) + ; 3. Tag and push + ; The source has no [docs-format] or [maintenance-operations] section and no + ; @profile line, so neither slot nor (profile …) is emitted (ledger P-3). + (playbook + :version "0.1.0" + :last-updated "2026-03-16" + (deployment) + (incident-response) + (release-process)) + + ; ---- STATE.a2ml (family 3, option B) ------------------------------------- + ; Nothing is emitted (ledger S-1 to S-9). The lifecycle claim + ; ([metadata] status "active") duplicates the CLADE phase and belongs to the + ; (status …) clause of STATE.deed (A7 J15), fed from CLADE, which is out of + ; scope. [project-context] phase "advanced-research-prototype" is not a + ; maturity level (experimental alpha beta production lts), so no + ; (maturity …) is emitted: the owner picks the level. The journal sections, + ; [coq-proof-status], [dogfooding-status] and [crg] are archived, not + ; translated. Live proof status: docs/PROOF_HOLES_AUDIT.adoc and + ; EXPLAINME.adoc (Proof Ledger). + + ; ---- 6a2/0-AI-MANIFEST.a2ml and 6a2/README.adoc --------------------------- + ; Directory manifest and directory README for the retired 6a2/ layout. + ; Archived only; they describe a layout that no longer exists (ledger G-1, R-1). + + ; ---- 6a2/anchor/ANCHOR.a2ml (A7 section 6.4) ------------------------------ + ; No (anchor …) clause yet: the legacy anchor has no `authority`, which the + ; clause requires exactly once, and the translator never invents one. The + ; translation is incomplete until the owner supplies it (ledger AN-1). + ; Legacy fields and their A7 6.4 destinations: + ; id "org.hyperpolymath.valence-shell" -> dropped; :repo-uuid is the id (AN-2) + ; version "0.9.0" -> (anchor (metadata :version "0.9.0")) once the clause lands (AN-3) + ; clade "unknown" -> dropped; placements come from chora-registry (AN-4) + ; status "active" -> dropped; lifecycle is STATE.deed's (AN-5) + ; ssg engine "casket", output_dir "public", boj_trigger true, cartridge "ssg-mcp" + ; -> META.deed (ssg …) under J29; not emitted here (AN-6) + ; parents "org.hyperpolymath.boj-server" -> ECOSYSTEM (related … :relationship parent); + ; not emitted: the registry records valence-shell as standalone with no + ; parent, so the owner rules first (AN-7) +) From dd088ff0327b9d5fade595a71a574d34740e5daa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:00:07 +0000 Subject: [PATCH 05/14] docs(claude): point the Guile Scheme row at the repo deed The language table's Guile Scheme row still named the retired .machine_readable/6a2/ files, which Hypatia flags as SD007. It now says metadata is valence-shell_chora.deed, the wording absolute-zero uses for the same row. The row's language rule is unchanged. Ledger row U-2 is marked resolved. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .claude/CLAUDE.md | 2 +- archive/a2ml-v1/MIGRATION-LEDGER.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 48f61b5f..58893e8d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -42,7 +42,7 @@ The following files in `.machine_readable/` contain structured project metadata: | **JavaScript** | Only where AffineScript cannot | MCP protocol glue, Bun APIs | | **Python** | SaltStack only | No other Python permitted | | **Nickel** | Configuration language | For complex configs | -| **Guile Scheme** | State/meta files | .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml | +| **Guile Scheme** | Scripting where needed | (metadata is `valence-shell_chora.deed`; see Machine-Readable Artefacts) | | **Julia** | Batch scripts, data processing | Per RSR | | **OCaml** | AffineScript compiler | Language-specific | | **Ada** | Safety-critical systems | Where required | diff --git a/archive/a2ml-v1/MIGRATION-LEDGER.adoc b/archive/a2ml-v1/MIGRATION-LEDGER.adoc index c67afc73..e3ba3781 100644 --- a/archive/a2ml-v1/MIGRATION-LEDGER.adoc +++ b/archive/a2ml-v1/MIGRATION-LEDGER.adoc @@ -197,7 +197,7 @@ archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). |=== | ID | Item | Disposition | U-1 | `.claude/CLAUDE.md` "Machine-Readable Artefacts" list | Updated to name the deed, this ledger and the archive (SD007). Nothing else in the file was changed. -| U-2 | `.claude/CLAUDE.md` language-policy table, row "Guile Scheme" | Still names `.machine_readable/6a2/STATE.a2ml`, `META.a2ml` and `ECOSYSTEM.a2ml`. Left as written: the rest of the file is owner policy. Hypatia's SD007 pattern `.machine_readable/6a2/` still matches that row, so *SD007 stays open until the owner edits it.* +| U-2 | `.claude/CLAUDE.md` language-policy table, row "Guile Scheme" | Named `.machine_readable/6a2/STATE.a2ml`, `META.a2ml` and `ECOSYSTEM.a2ml`. *Resolved 2026-11-17:* the row now points at `valence-shell_chora.deed`, following the absolute-zero precedent; the row's language rule is unchanged. SD007 clears. | U-3 | `docs/README.adoc` (two references) | Updated to the deed, `PROOF_HOLES_AUDIT.adoc` and the archived STATE. | U-4 | `proofs/coq/README.adoc` (three references) | Updated to the archived STATE and the live authorities. The file's own counts (`admitted = 1`) disagree with `docs/PROOF_HOLES_AUDIT.adoc` (0 admits); recorded, not corrected. | U-5 | `ROADMAP.adoc` "Current Status" | The path updated to the archived STATE. The "~74%" figure is left as written (S-4). @@ -224,7 +224,7 @@ archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). | `deed_lint.js --anchor`, `--egress`, `--contractiles`, `--rsr-profile` | PASS | Each reports no such clause. | standards `deed_canon` reader (from `scripts/check-canon-lockstep.sh`) | PASS | Reads `2.1.5` and both hashes. | `.github/scripts/check-bridge-forbidden-phrases.sh` | PASS | Run after the edits. -| `git grep -n '6a2/'` | 2 live hits, both owner items | `.claude/CLAUDE.md` language table (U-2) and the frozen `Mustfile.a2ml` checks (O-2). Every other hit is in this archive and ledger, a `CHANGELOG.adoc` history entry (this change's included), a dated audit record, or the out-of-scope subproject (O-9). +| `git grep -n '6a2/'` | 1 live hit, an owner item | The frozen `Mustfile.a2ml` checks (O-2). Every other hit is in this archive and ledger, a `CHANGELOG.adoc` history entry (this change's included), a dated audit record, or the out-of-scope subproject (O-9). |=== == Open items (owner) @@ -234,7 +234,7 @@ archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). . The maturity level (S-2). . Whether the bridges become `(related …)` edges, and with which relationship (E-4). . The AGENTIC constraints as `Mustfile.deed` edicts (A-2). -. The `.claude/CLAUDE.md` language-table row (U-2); the `ROADMAP.adoc` items (U-6); the PLAYBOOK steps (P-4). +. The `ROADMAP.adoc` items (U-6); the PLAYBOOK steps (P-4). . When to move to the A7 split descriptile deeds, with their affirmation (T-1). . Confirm the `:repo-uuid` read from the registry (I-1). . SPDX headers on the two archived files that lack them (X-1). From 52ed14977af969d8d5feafa0c01a4b6f7c9610cf Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:08:51 +0000 Subject: [PATCH 06/14] fix(state): repair the stress suite and gate it in CI again Shell bugs, fixed at source: - Persistence was O(n^2): every recorded or undone operation cloned the whole history and rewrote .vsh_state.json pretty-printed. 1,000 touches took 5.9 s, and 10,000 or 100,000 never finished. Hot-path mutations now append one line to .vsh_state.journal; the snapshot is rewritten only once the journal reaches half the history length (at least 1,024 entries), so the cost is amortised O(1). Snapshots are written via temp file + rename and record the last journal sequence they contain, so replay never applies an entry twice; a torn line or sequence gap ends replay. - Single-step undo was O(n^2): each undo walked past every undone op to pick its target, then searched for it again from the oldest end. A checked hint for the undone block removes the rescan (10,000 undos: 1.8 s -> 0.34 s). - rollback cleared the active transaction without saving; it now goes through ShellState::abort_transaction. Stale test expectations corrected (no test removed, no assertion loosened): listings now exclude only the shell's own .vsh_state* files; deep nesting uses one-character names within PATH_MAX and drives mkdir/undo through the shell; the 5,000-level test builds its tree with mkdirat/openat and checks the shell fails cleanly; the large-file tests use rm/undo and chmod/mv instead of touch (create-only in vsh); undo/redo efficiency calls commands::redo; the max-history test asserts the cap and bounded state. CI: the stress step is back in compilation_tests.yml on Linux with timeout-minutes: 5 and no continue-on-error. The audit record lists what remains open (non-streamed undo data, O(limit) trim, macOS). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .github/workflows/compilation_tests.yml | 18 +- .gitignore | 2 + .../2026-11-16-hypatia-remediation.adoc | 105 ++- impl/rust-cli/src/commands.rs | 12 +- impl/rust-cli/src/state.rs | 600 ++++++++++++++++-- impl/rust-cli/tests/stress_tests.rs | 304 +++++++-- 6 files changed, 921 insertions(+), 120 deletions(-) diff --git a/.github/workflows/compilation_tests.yml b/.github/workflows/compilation_tests.yml index be36564a..96280c18 100644 --- a/.github/workflows/compilation_tests.yml +++ b/.github/workflows/compilation_tests.yml @@ -85,12 +85,18 @@ jobs: working-directory: impl/rust-cli run: cargo test --verbose - # The ignored stress suite (tests/stress_tests.rs) is not run here. It ran - # under `continue-on-error: true`, which hid its state (Hypatia RE005): - # on 2026-11-16, 5 of its tests fail outright and 2 run for more than two - # minutes each, so this step only ever burned the job's 30-minute timeout. - # Run it by hand with `cargo test --test stress_tests -- --ignored` until - # the suite is repaired and can gate honestly. + # The ignored stress suite (tests/stress_tests.rs) gates the build. It was + # repaired on 2026-11-17 (see docs/audits/2026-11-16-hypatia-remediation.adoc) + # and runs in 30-50 s locally, so 5 minutes leaves wide margin for a slow + # runner; there is deliberately no continue-on-error (Hypatia RE005). + # Linux only: stress_deep_nesting_1000_levels needs 1000 directory levels + # in one absolute path (~2,000 bytes), which fits Linux's PATH_MAX of 4096 + # but not macOS's 1024. + - name: Run ignored tests (stress) + if: runner.os == 'Linux' + working-directory: impl/rust-cli + timeout-minutes: 5 + run: cargo test --test stress_tests -- --ignored --test-threads=1 # ============================================================ # MSRV (Minimum Supported Rust Version) diff --git a/.gitignore b/.gitignore index a3b59c58..1eccccf4 100644 --- a/.gitignore +++ b/.gitignore @@ -122,6 +122,8 @@ htmlcov/ ai-cli-crash-capture/ .cache/ .vsh_state.json +.vsh_state.journal +.vsh_state.json.*.tmp # ============ # Strategic diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index 02fa449e..1ecccbd1 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -56,7 +56,7 @@ They close when the underlying alert closes. | `npx_in_workflow` (2) | fixed | `bunx --no-install --bun rescript build`, which never fetches an unpinned package. | `missing_timeout_minutes`, WH006 | fixed | `labels.yml`, `label-triage.yml` (echo-types versions). | RE001 (3) | fixed | `harden-runner`: `block` to `api.github.com` in `instant-sync.yml`, `block` to the SMTP endpoint in `push-email-notify.yml`, `audit` in `hypatia-scan.yml`. -| RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; see <>. +| RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; after its repair it gates the Linux test jobs again. See <>. | WH008 (3) | fixed | See the Secret Scanner section. | SD022 (2) | fixed | Both paths named another tree (`echidna/src/rust/`, the Agda tarball path `agda-2.7.0.1/src/data/lib`); now qualified. | SD009 | left for the owner | `ffi/zig/src/main.zig` has no SPDX header. Licence edits are owner-only (estate doctrine 6). @@ -94,3 +94,106 @@ Run one test at a time on 2026-11-16, 120 s limit each: 5 fail (`stress_many_operations_10000`, `stress_resource_limits_max_history`), 3 pass; `stress_large_file_1gb` was not run. The CI step only ever reached the 30-minute job timeout. Repairing the suite is separate work. + +=== Repair (2026-11-17) + +All 11 tests now pass. The step is back in `compilation_tests.yml` as +`cargo test --test stress_tests -- --ignored --test-threads=1`, Linux only, +with `timeout-minutes: 5` and no `continue-on-error`. No test was deleted or +skipped, and no assertion was loosened. + +Shell bugs fixed (`src/state.rs`, `src/commands.rs`): + +* *O(n²) persistence.* Every recorded or undone operation rewrote the whole + history to `.vsh_state.json` (cloned, then pretty-printed). 1,000 touches + took 5.9 s; 10,000 and 100,000 never finished. The hot path now appends + one line to `.vsh_state.journal`; the snapshot is rewritten only when the + journal reaches half the history length (at least 1,024 entries), which + keeps the cost amortised O(1). Snapshots are written to a temporary file + and renamed, and record the last journal sequence number they contain, so + a crash cannot tear the snapshot or replay an entry twice. A torn journal + line or a sequence gap ends replay. After the fix, 1,000 touches take + 0.04 s. Seven new unit tests in `state.rs` cover replay, compaction, trim, + a torn tail, crash-after-rename and transactions. +* *O(n²) single-step undo.* Each `undo 1` walked past every already-undone + operation to pick its target, then searched for that target again from the + oldest end of the history to mark it. A checked hint for the block of undone operations removes the rescan: + undoing 10,000 operations one at a time went from 1.8 s to 0.34 s. A unit + test compares it against a full scan through undo, record, trim and an + out-of-order mark. +* *Rollback not persisted.* `rollback` cleared the active transaction + without saving. That had been masked by the next operation's full rewrite, + and the journal would have exposed it. It now goes through + `ShellState::abort_transaction`, which saves. + +Test expectations corrected (`tests/stress_tests.rs`): + +* `stress_concurrent_multiple_instances`, `stress_many_operations_10000`: + the listings counted the shell's own `.vsh_state*` files. They now exclude + only those files, and the concurrent test checks the exact set of 1,000 + names. +* `stress_deep_nesting_1000_levels`: `level_NNNN` names give an + 11,000-byte path, past `PATH_MAX`, and the test then ran `mkdir` on paths + that already existed. It now builds the 1,000 levels through the shell + with one-character names (about 2,000 bytes, asserted against `PATH_MAX`) + and undoes them all. +* `stress_deep_nesting_no_stack_overflow`: it only called + `fs::create_dir_all`, which fails with ENAMETOOLONG at 5,000 levels. It + now builds the tree with `mkdirat`/`openat`, checks that shell `mkdir` and + `touch` at that depth fail cleanly without recording anything, and removes + the tree. +* `stress_large_file_undo_streaming`, `stress_large_file_1gb`: both called + `touch` on an existing file, but vsh's `touch` only creates files + (EEXIST). The 100 MB test now runs `rm` (the operation that saves file + content as undo data) plus `undo` and checks the restored bytes. The 1 GB + test times `chmod`, `mv` and their undos. +* `stress_undo_redo_efficiency`: "redo" popped the redo stack without + redoing. It now calls `commands::redo` and checks the files return. +* `stress_resource_limits_max_history`: it now asserts the history is capped + at `max_history_size` and that the persisted state stays under 32 MiB + (measured: 2.3 MB). + +Measured (debug build, 4 cores, each test run alone with the CI flags): +whole suite 29-51 s across three runs. + +[cols="3,1",options="header"] +|=== +| Test | Wall time +| `stress_concurrent_multiple_instances` | 0.6 s +| `stress_concurrent_no_corruption` | 0.2 s +| `stress_deep_nesting_1000_levels` | 0.5 s +| `stress_deep_nesting_no_stack_overflow` | 0.7 s +| `stress_history_memory_efficiency` | 0.5 s +| `stress_large_file_1gb` | 1.8 s +| `stress_large_file_undo_streaming` | 12.6 s +| `stress_many_operations_10000` | 2.3 s +| `stress_many_small_files` | 1.2 s +| `stress_resource_limits_max_history` | 10-32 s +| `stress_undo_redo_efficiency` | 0.2 s +|=== + +Still open: + +* *Undo data is not streamed.* `rm` reads the whole file into + `undo_data`, and the journal stores those bytes as a JSON number array + (about 3 bytes per byte). Removing a 100 MB file takes about 11.5 s in a + debug build and writes about 300 MB of state. The test name promises + streaming; the test comment now says it is not implemented. The fix is + out-of-line undo storage (for example, renaming the file into a store + under the root), which changes the reversibility implementation, so it is + left for the owner. +* *History trimming is O(limit) per operation.* At the cap, each new + operation drains the oldest entry from the front of a `Vec`, moving about + 1.2 MB at the default 10,000 limit. That is about 7 s of the 100,000-op + test. A `VecDeque` would remove it but changes the public + `ShellState::history` type that tests and `CLAUDE.md` document as a `Vec`. +* *macOS.* The suite is not run there: `PATH_MAX` is 1024, so the + 1,000-level test cannot pass with absolute paths, and the rest was not + measured on macOS. +* `previous_dir` (set by `cd` without a save) reaches disk at the next + snapshot, not at the next operation as before. +* Neither the journal nor the snapshot is `fsync`ed (the old `fs::write` + was not either), the files keep the default mode, and they still live in + the session root. Route plan items E1d and G2 + (`docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc`) cover fsync, 0600 and moving + state out of the root; the journal is a new file they must include. diff --git a/impl/rust-cli/src/commands.rs b/impl/rust-cli/src/commands.rs index 4f91625d..cd9f879c 100644 --- a/impl/rust-cli/src/commands.rs +++ b/impl/rust-cli/src/commands.rs @@ -860,11 +860,11 @@ pub fn undo(state: &mut ShellState, count: usize, verbose: bool) -> Result<()> { fs::remove_file(&path).context("Undo touch failed")?; } OperationType::CreateFile => { - let content = op.undo_data.as_ref().cloned().unwrap_or_default(); + let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); fs::write(&path, content).context("Undo rm failed")?; } OperationType::WriteFile => { - let content = op.undo_data.as_ref().cloned().unwrap_or_default(); + let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); fs::write(&path, content).context("Undo write failed")?; } OperationType::FileAppended => { @@ -1364,11 +1364,11 @@ pub fn rollback_transaction(state: &mut ShellState) -> Result<()> { fs::remove_file(&path).context("Failed to remove file") } OperationType::CreateFile => { - let content = op.undo_data.as_ref().cloned().unwrap_or_default(); + let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); fs::write(&path, content).context("Failed to restore file") } OperationType::WriteFile => { - let content = op.undo_data.as_ref().cloned().unwrap_or_default(); + let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); fs::write(&path, content).context("Failed to restore file content") } OperationType::FileAppended => { @@ -1521,8 +1521,8 @@ pub fn rollback_transaction(state: &mut ShellState) -> Result<()> { } } - // Clear the transaction - state.active_transaction = None; + // Clear the transaction (and persist that it is gone) + state.abort_transaction(); // Report results if failed_rollbacks.is_empty() { diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index 7f75389b..23df51f6 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -278,9 +278,40 @@ pub struct ShellState { /// Completed transactions pub transactions: Vec, - /// State file path for persistence + /// State file path for persistence (the snapshot) state_file: PathBuf, + /// Append-only journal of the history mutations made since the last + /// snapshot. + /// + /// Rewriting the whole snapshot on every operation made each operation + /// cost O(history length), so a session of n operations cost O(n²) in + /// serialisation and disk writes. Hot-path mutations (record, mark-undone, + /// trim) are appended here in O(1); the snapshot is rewritten only when + /// the journal outgrows it (amortised O(1) per operation) or at the rare + /// transaction boundaries. + journal_file: PathBuf, + + /// Sequence number of the last journal entry written or replayed. + /// Each snapshot records it, so replay skips entries already folded in. + journal_seq: u64, + + /// Journal entries written or replayed since the last snapshot. + journal_entries: usize, + + /// Indices of a contiguous block of `history` known to be all undone. + /// + /// Repeated single-step undo used to rescan every already-undone + /// operation at the end of the history (twice: to pick the next target + /// and to mark it), so undoing n operations one at a time cost O(n²). + /// Undo skips this block instead. It is a hint: it is checked before + /// use and an empty range means "no hint". + undone_run: std::ops::Range, + + /// A journal append failed (possibly leaving a torn line), so the next + /// persist must write a full snapshot rather than append. + snapshot_pending: bool, + /// Last exit code from external command (for $? support) pub last_exit_code: i32, @@ -337,6 +368,7 @@ impl ShellState { let root_path = fs::canonicalize(&root_path).context("Failed to canonicalize sandbox root")?; let state_file = root_path.join(".vsh_state.json"); + let journal_file = root_path.join(".vsh_state.journal"); let mut state = Self { root: root_path, @@ -345,6 +377,11 @@ impl ShellState { active_transaction: None, transactions: Vec::new(), state_file, + journal_file, + journal_seq: 0, + journal_entries: 0, + undone_run: 0..0, + snapshot_pending: false, last_exit_code: 0, previous_dir: None, variables: HashMap::new(), @@ -377,13 +414,13 @@ impl ShellState { self.history.push(op); // Enforce history size limit - self.enforce_history_limit(); + let trimmed = self.enforce_history_limit(); // Clear redo stack when new operation is performed self.redo_stack.clear(); // Persist state - warn on failure but don't abort - if let Err(e) = self.save() { + if let Err(e) = self.persist_recorded(trimmed) { eprintln!("{} Failed to save state: {}", "Warning:".bright_yellow(), e); eprintln!("Operation succeeded but may not persist across restarts"); } @@ -400,10 +437,10 @@ impl ShellState { } self.history.push(op); - self.enforce_history_limit(); + let trimmed = self.enforce_history_limit(); // Persist state - warn on failure but don't abort - if let Err(e) = self.save() { + if let Err(e) = self.persist_recorded(trimmed) { eprintln!("{} Failed to save state: {}", "Warning:".bright_yellow(), e); eprintln!("Redo succeeded but may not persist across restarts"); } @@ -413,7 +450,8 @@ impl ShellState { /// /// When history exceeds max_history_size, removes the oldest operations. /// If history_archive_path is set, saves removed operations to archive. - fn enforce_history_limit(&mut self) { + /// Returns the number of operations removed. + fn enforce_history_limit(&mut self) -> usize { if let Some(limit) = self.max_history_size { if self.history.len() > limit { let excess = self.history.len() - limit; @@ -432,11 +470,14 @@ impl ShellState { // Remove oldest operations self.history.drain(0..excess); + self.shift_undone_run(excess); // Note: This means undo can only go back `limit` operations // Users should be aware via configuration + return excess; } } + 0 } /// Archive operations to disk for later reference @@ -466,26 +507,103 @@ impl ShellState { /// Get the last N undoable operations pub fn last_n_undoable(&self, n: usize) -> Vec<&Operation> { - self.history - .iter() - .rev() - .filter(|op| !op.undone) + self.undoable_indices_rev() .take(n) + .map(|i| &self.history[i]) .collect() } - /// Mark an operation as undone - pub fn mark_undone(&mut self, op_id: Uuid, undone_by: Uuid) { - if let Some(op) = self.history.iter_mut().find(|o| o.id == op_id) { - op.undone = true; - op.undone_by = Some(undone_by); + /// Indices of operations not yet undone, newest first, skipping the + /// known-undone block instead of rescanning it. + fn undoable_indices_rev(&self) -> impl Iterator + '_ { + let run = self.checked_undone_run(); + let mut next = self.history.len(); + std::iter::from_fn(move || { + while next > 0 { + next -= 1; + if next + 1 == run.end { + next = run.start; + continue; + } + if !self.history[next].undone { + return Some(next); + } + } + None + }) + } - // Push to redo stack - self.redo_stack.push_front(op.clone()); + /// The undone-block hint, or an empty range if it does not hold. + fn checked_undone_run(&self) -> std::ops::Range { + let run = self.undone_run.clone(); + let holds = !run.is_empty() + && run.end <= self.history.len() + && self.history[run.start].undone + && self.history[run.end - 1].undone; + if holds { + run + } else { + 0..0 } + } + + /// Record that `history[index]` is now undone in the block hint. + fn extend_undone_run(&mut self, index: usize) { + let run = self.checked_undone_run(); + self.undone_run = if run.is_empty() { + index..index + 1 + } else if index + 1 == run.start { + index..run.end + } else if index == run.end { + run.start..index + 1 + } else if run.contains(&index) { + run + } else { + index..index + 1 + }; + } + + /// Keep the block hint aligned after the oldest `removed` operations + /// were dropped from the front of the history. + fn shift_undone_run(&mut self, removed: usize) { + let start = self.undone_run.start.saturating_sub(removed); + let end = self.undone_run.end.saturating_sub(removed); + self.undone_run = start..end; + } + + /// Mark an operation as undone + pub fn mark_undone(&mut self, op_id: Uuid, undone_by: Uuid) { + // Undo targets the newest operations that are not yet undone, so look + // there first; fall back to a full scan for any other id. + let index = self + .undoable_indices_rev() + .find(|&i| self.history[i].id == op_id) + .or_else(|| self.history.iter().rposition(|o| o.id == op_id)); + + let found = match index { + Some(i) => { + let op = &mut self.history[i]; + op.undone = true; + op.undone_by = Some(undone_by); + + // Push to redo stack + self.redo_stack.push_front(op.clone()); + self.extend_undone_run(i); + true + } + None => false, + }; // Persist state - warn on failure - if let Err(e) = self.save() { + let persisted = if found { + self.persist_entries(&[JournalEntryRef::Undone { + id: op_id, + undone_by, + }]) + } else { + Ok(()) + }; + if let Err(e) = persisted { eprintln!( "{} Failed to save undo state: {}", "Warning:".bright_yellow(), @@ -546,6 +664,21 @@ impl ShellState { Ok(()) } + /// Drop the active transaction without committing it (after a rollback) + /// and persist that, so a restart does not resurrect it. + pub fn abort_transaction(&mut self) { + self.active_transaction = None; + + // Persist state - warn on failure + if let Err(e) = self.save() { + eprintln!( + "{} Failed to save transaction rollback: {}", + "Warning:".bright_yellow(), + e + ); + } + } + /// Get operations in current transaction pub fn current_transaction_ops(&self) -> Vec<&Operation> { match &self.active_transaction { @@ -584,38 +717,169 @@ impl ShellState { self.redo_stack.pop_front() } - /// Save state to file - fn save(&self) -> Result<()> { - let state = SerializableState { - history: self.history.clone(), - transactions: self.transactions.clone(), - active_transaction: self.active_transaction.clone(), - previous_dir: self.previous_dir.clone(), + /// Persist the operation just pushed by `record_operation` or + /// `record_redo_operation`, plus the history trim it caused. + fn persist_recorded(&mut self, trimmed: usize) -> Result<()> { + if self.journal_due_for_snapshot() { + return self.save(); + } + // With `max_history_size == Some(0)` the operation is trimmed at once + // and there is nothing to journal; fall back to a snapshot. + let Some(op) = self.history.last() else { + return self.save(); }; + let mut entries = vec![JournalEntryRef::Record(op)]; + if trimmed > 0 { + entries.push(JournalEntryRef::Trim(trimmed)); + } + let appended = append_journal(&self.journal_file, self.journal_seq, &entries); + let count = entries.len(); + self.after_append(appended, count) + } - let json = serde_json::to_string_pretty(&state)?; - fs::write(&self.state_file, json)?; + /// Persist journal entries that do not borrow from `self`. + fn persist_entries(&mut self, entries: &[JournalEntryRef<'_>]) -> Result<()> { + if self.journal_due_for_snapshot() { + return self.save(); + } + let appended = append_journal(&self.journal_file, self.journal_seq, entries); + self.after_append(appended, entries.len()) + } + + /// Account for a journal append of `count` entries. A failed append may + /// have left a torn line, which ends replay, so the next persist writes a + /// full snapshot (and empties the journal) instead of appending after it. + fn after_append(&mut self, appended: Result<()>, count: usize) -> Result<()> { + if appended.is_err() { + self.snapshot_pending = true; + } else { + self.journal_seq += count as u64; + self.journal_entries += count; + } + appended + } + + /// The journal is folded into a fresh snapshot once it holds at least + /// half as many entries as the history has operations (and at least + /// `JOURNAL_MIN_ENTRIES`). A snapshot costs O(history length), which is + /// then at most twice the number of entries it absorbs, so persistence + /// stays amortised O(1) per operation. + fn journal_due_for_snapshot(&self) -> bool { + self.snapshot_pending + || (self.journal_entries >= JOURNAL_MIN_ENTRIES + && 2 * self.journal_entries >= self.history.len()) + } + + /// Write a full snapshot and empty the journal. + /// + /// The snapshot is written to a temporary file and renamed over the old + /// one, so a crash leaves either the old or the new snapshot. It records + /// the journal sequence number it includes, so a crash between the rename + /// and the journal truncation cannot replay entries twice. + fn save(&mut self) -> Result<()> { + use std::io::Write; + + let state = SerializableStateRef { + history: &self.history, + transactions: &self.transactions, + active_transaction: self.active_transaction.as_ref(), + previous_dir: self.previous_dir.as_ref(), + journal_seq: self.journal_seq, + }; + + let file_name = format!(".vsh_state.json.{}.tmp", Uuid::new_v4().simple()); + let tmp = self.state_file.with_file_name(file_name); + let written = (|| -> Result<()> { + let mut out = std::io::BufWriter::new(fs::File::create(&tmp)?); + serde_json::to_writer(&mut out, &state)?; + out.flush()?; + fs::rename(&tmp, &self.state_file)?; + Ok(()) + })(); + if written.is_err() { + let _ = fs::remove_file(&tmp); + } + written?; + + // Everything journalled so far is now in the snapshot. + if self.journal_file.exists() { + fs::OpenOptions::new() + .write(true) + .open(&self.journal_file)? + .set_len(0)?; + } + self.journal_entries = 0; + self.snapshot_pending = false; Ok(()) } - /// Load state from file + /// Load state from the snapshot, then replay the journal on top of it. fn load(&mut self) -> Result<()> { - if !self.state_file.exists() { - return Ok(()); + if self.state_file.exists() { + let json = crate::fs_pure::read_to_string(&self.state_file)?; + let state: SerializableState = serde_json::from_str(&json)?; + + self.history = state.history; + self.transactions = state.transactions; + self.active_transaction = state.active_transaction; + self.previous_dir = state.previous_dir; + self.journal_seq = state.journal_seq; } - let json = crate::fs_pure::read_to_string(&self.state_file)?; - let state: SerializableState = serde_json::from_str(&json)?; + if self.journal_file.exists() { + let journal = crate::fs_pure::read_to_string(&self.journal_file)?; + for line in journal.lines() { + // A torn line (crash mid-append) ends the replay, and so does + // a sequence gap: replay keeps the longest consistent prefix. + let Ok(JournalLine { seq, entry }) = serde_json::from_str::(line) + else { + break; + }; + if seq <= self.journal_seq { + continue; // already folded into the snapshot + } + if seq != self.journal_seq + 1 { + break; + } + self.replay(entry); + self.journal_seq = seq; + self.journal_entries += 1; + } + } - self.history = state.history; - self.transactions = state.transactions; - self.active_transaction = state.active_transaction; - self.previous_dir = state.previous_dir; + // The history was replaced wholesale; drop the undone-block hint. + self.undone_run = 0..0; Ok(()) } + /// Apply one journal entry to the in-memory history. Mirrors what the + /// live mutation did, minus side effects (archiving, redo stack, I/O); + /// the redo stack is not persisted, as before. + fn replay(&mut self, entry: JournalEntry) { + match entry { + JournalEntry::Record(op) => { + if let Some(txn) = self.active_transaction.as_mut() { + if op.transaction_id == Some(txn.id) { + txn.operations.push(op.id); + } + } + self.history.push(op); + } + JournalEntry::Undone { id, undone_by } => { + if let Some(op) = self.history.iter_mut().rev().find(|o| o.id == id) { + op.undone = true; + op.undone_by = Some(undone_by); + } + } + JournalEntry::Trim(n) => { + let n = n.min(self.history.len()); + self.history.drain(0..n); + } + } + } + // ========================================================================= // Variable Management // ========================================================================= @@ -909,13 +1173,81 @@ impl ShellState { } } -#[derive(Serialize, Deserialize)] +#[derive(Deserialize)] struct SerializableState { history: Vec, transactions: Vec, active_transaction: Option, #[serde(default)] previous_dir: Option, + /// Last journal sequence number folded into this snapshot (0 for + /// snapshots written before the journal existed). + #[serde(default)] + journal_seq: u64, +} + +/// Borrowing twin of [`SerializableState`], so a snapshot does not clone the +/// whole history first. +#[derive(Serialize)] +struct SerializableStateRef<'a> { + history: &'a [Operation], + transactions: &'a [Transaction], + active_transaction: Option<&'a Transaction>, + previous_dir: Option<&'a PathBuf>, + journal_seq: u64, +} + +/// Minimum journal length before it is folded into a snapshot. +const JOURNAL_MIN_ENTRIES: usize = 1024; + +/// One history mutation in the journal (`.vsh_state.journal`, JSON lines). +#[derive(Deserialize)] +enum JournalEntry { + /// An operation appended to the history. + Record(Operation), + /// An operation marked undone. + Undone { id: Uuid, undone_by: Uuid }, + /// The oldest `n` operations dropped by the history size limit. + Trim(usize), +} + +/// Borrowing twin of [`JournalEntry`]; serialises to the same shape. +#[derive(Serialize)] +enum JournalEntryRef<'a> { + Record(&'a Operation), + Undone { id: Uuid, undone_by: Uuid }, + Trim(usize), +} + +#[derive(Deserialize)] +struct JournalLine { + seq: u64, + entry: JournalEntry, +} + +#[derive(Serialize)] +struct JournalLineRef<'a, 'b> { + seq: u64, + entry: &'b JournalEntryRef<'a>, +} + +/// Append `entries` to the journal as JSON lines numbered from +/// `last_seq + 1`. Lines are streamed to the file rather than built in memory +/// first, since a `Record` can carry a large `undo_data` payload; small +/// entries still reach the file in a single write. +fn append_journal(path: &Path, last_seq: u64, entries: &[JournalEntryRef<'_>]) -> Result<()> { + use std::io::Write; + let file = fs::OpenOptions::new() + .create(true) + .append(true) + .open(path)?; + let mut out = std::io::BufWriter::with_capacity(64 * 1024, file); + for (seq, entry) in (last_seq + 1..).zip(entries) { + serde_json::to_writer(&mut out, &JournalLineRef { seq, entry })?; + out.write_all(b"\n")?; + } + out.flush()?; + Ok(()) } /// Resolve `path` against the sandbox `root`, clamping any `..` traversal so @@ -1323,4 +1655,198 @@ mod tests { fn test_chown_display() { assert_eq!(format!("{}", OperationType::Chown), "chown"); } + + // ======================================================================== + // Persistence: snapshot + journal + // ======================================================================== + + fn persisted_root() -> tempfile::TempDir { + tempfile::TempDir::new().unwrap() + } + + fn reopen(root: &tempfile::TempDir) -> ShellState { + ShellState::new(root.path().to_str().unwrap()).unwrap() + } + + fn record(state: &mut ShellState, path: &str) -> Uuid { + let op = Operation::new(OperationType::CreateFile, path.to_string(), None); + let id = op.id; + state.record_operation(op); + id + } + + fn summary(state: &ShellState) -> Vec<(Uuid, bool, Option)> { + state + .history + .iter() + .map(|op| (op.id, op.undone, op.undone_by)) + .collect() + } + + #[test] + fn test_journal_replay_restores_history_and_undo_marks() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + let b = record(&mut state, "b"); + record(&mut state, "c"); + state.mark_undone(b, Uuid::new_v4()); + + // Hot-path operations only append to the journal. + assert!(state.journal_file.exists()); + assert!(!state.state_file.exists()); + + let reloaded = reopen(&root); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_journal_folds_into_snapshot_and_reloads() { + let root = persisted_root(); + let mut state = reopen(&root); + for i in 0..(JOURNAL_MIN_ENTRIES + 10) { + record(&mut state, &format!("f{i}")); + } + assert!(state.state_file.exists(), "journal should have compacted"); + assert!(state.journal_entries < JOURNAL_MIN_ENTRIES); + + let reloaded = reopen(&root); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_journal_replays_history_trim() { + let root = persisted_root(); + let mut state = reopen(&root); + state.max_history_size = Some(3); + for i in 0..5 { + record(&mut state, &format!("f{i}")); + } + assert_eq!(state.history.len(), 3); + + // The reopened state has the default (larger) limit, so the trim must + // come from the journal, not from re-applying a limit. + let reloaded = reopen(&root); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_journal_torn_tail_is_ignored() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + record(&mut state, "b"); + { + use std::io::Write; + let mut journal = fs::OpenOptions::new() + .append(true) + .open(&state.journal_file) + .unwrap(); + journal.write_all(b"{\"seq\":3,\"entry\":{\"Rec").unwrap(); + } + + let reloaded = reopen(&root); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_snapshot_skips_already_folded_journal_entries() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + record(&mut state, "b"); + let stale_journal = fs::read(&state.journal_file).unwrap(); + + // Simulate a crash after the snapshot rename but before the journal + // was truncated: the journal still holds entries the snapshot has. + state.save().unwrap(); + fs::write(&state.journal_file, stale_journal).unwrap(); + + let reloaded = reopen(&root); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_rolled_back_transaction_does_not_survive_reload() { + let root = persisted_root(); + let mut state = reopen(&root); + state.begin_transaction("t").unwrap(); + record(&mut state, "a"); + state.abort_transaction(); + + let reloaded = reopen(&root); + assert!(reloaded.active_transaction.is_none()); + assert_eq!(summary(&reloaded), summary(&state)); + } + + /// `last_n_undoable` must agree with a plain newest-first scan for + /// non-undone operations, whatever the undone-block hint holds. + fn assert_undoable_matches_scan(state: &ShellState) { + let naive: Vec = state + .history + .iter() + .rev() + .filter(|op| !op.undone) + .map(|op| op.id) + .collect(); + let fast: Vec = state + .last_n_undoable(usize::MAX) + .iter() + .map(|op| op.id) + .collect(); + assert_eq!(fast, naive); + } + + fn undo_one(state: &mut ShellState) { + let id = state.last_n_undoable(1)[0].id; + state.mark_undone(id, Uuid::new_v4()); + } + + #[test] + fn test_undone_block_hint_agrees_with_full_scan() { + let root = persisted_root(); + let mut state = reopen(&root); + state.max_history_size = Some(12); + for i in 0..10 { + record(&mut state, &format!("a{i}")); + } + for _ in 0..3 { + undo_one(&mut state); + assert_undoable_matches_scan(&state); + } + // New operations after an undone block, then undo across it. + for i in 0..4 { + record(&mut state, &format!("b{i}")); + assert_undoable_matches_scan(&state); + } + for _ in 0..6 { + undo_one(&mut state); + assert_undoable_matches_scan(&state); + } + // Out-of-order mark of an older operation. + let oldest_live = state.last_n_undoable(usize::MAX).last().unwrap().id; + state.mark_undone(oldest_live, Uuid::new_v4()); + assert_undoable_matches_scan(&state); + // Trims from the front shift the block. + for i in 0..8 { + record(&mut state, &format!("c{i}")); + assert_undoable_matches_scan(&state); + } + while !state.last_n_undoable(1).is_empty() { + undo_one(&mut state); + assert_undoable_matches_scan(&state); + } + } + + #[test] + fn test_transaction_membership_survives_journal_replay() { + let root = persisted_root(); + let mut state = reopen(&root); + state.begin_transaction("t").unwrap(); + let a = record(&mut state, "a"); + + let reloaded = reopen(&root); + let txn = reloaded.active_transaction.as_ref().unwrap(); + assert_eq!(txn.operations, vec![a]); + } } diff --git a/impl/rust-cli/tests/stress_tests.rs b/impl/rust-cli/tests/stress_tests.rs index 34628f05..c08912c1 100644 --- a/impl/rust-cli/tests/stress_tests.rs +++ b/impl/rust-cli/tests/stress_tests.rs @@ -10,17 +10,54 @@ //! //! These tests validate that the shell remains stable, performant, //! and correct even under stress. +//! +//! All tests are `#[ignore]`d; CI runs them on Linux with +//! `cargo test --test stress_tests -- --ignored --test-threads=1` +//! (see `.github/workflows/compilation_tests.yml`). +//! +//! The shell keeps its persisted state in `.vsh_state.json` (snapshot) and +//! `.vsh_state.journal` inside the sandbox root, so directory listings below +//! account for those files explicitly. mod fixtures; use fixtures::tempfile::TempDir; use std::fs; use std::io::Write; +use std::path::Path; use std::sync::{Arc, Mutex}; use std::thread; use std::time::Instant; use vsh::state::ShellState; +/// Prefix shared by the shell's own state files in the sandbox root. +const STATE_FILE_PREFIX: &str = ".vsh_state"; + +/// Names of the entries in `dir` that are not the shell's own state files. +fn user_entries(dir: &Path) -> Vec { + let mut names: Vec = fs::read_dir(dir) + .unwrap() + .map(|e| e.unwrap().file_name().to_string_lossy().into_owned()) + .filter(|name| !name.starts_with(STATE_FILE_PREFIX)) + .collect(); + names.sort(); + names +} + +/// Total size in bytes of the shell's own state files in `dir`. +fn state_files_size(dir: &Path) -> u64 { + fs::read_dir(dir) + .unwrap() + .map(|e| e.unwrap()) + .filter(|e| { + e.file_name() + .to_string_lossy() + .starts_with(STATE_FILE_PREFIX) + }) + .map(|e| e.metadata().unwrap().len()) + .sum() +} + // ============================================================ // Stress Test 1: Deep Directory Nesting // ============================================================ @@ -28,46 +65,59 @@ use vsh::state::ShellState; #[test] #[ignore] // Run with: cargo test --test stress_tests -- --ignored fn stress_deep_nesting_1000_levels() { - let temp = TempDir::new().unwrap(); - let start = Instant::now(); + const DEPTH: usize = 1000; - // Create 1000-level deep directory structure - let mut current_path = temp.path().to_path_buf(); - for i in 0..1000 { - current_path.push(format!("level_{:04}", i)); - } + let temp = TempDir::new().unwrap(); + let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Create the entire nested structure - fs::create_dir_all(¤t_path).unwrap(); + // The shell resolves every path to an absolute one, so the deepest path + // must fit in PATH_MAX. One-character components ("d/d/.../d") cost two + // bytes per level: about 2,000 bytes plus the root, which fits Linux's + // 4096. (Ten-character names would need ~11,000 bytes, which no + // absolute-path API accepts; macOS's PATH_MAX of 1024 cannot hold 1000 + // levels at all.) + let deepest_len = state.root.as_os_str().len() + 2 * DEPTH; + let path_max = libc::PATH_MAX as usize; + assert!( + deepest_len < path_max, + "{DEPTH}-level nesting needs a {deepest_len}-byte absolute path; \ + this platform's PATH_MAX is {path_max}" + ); + // Create the 1000-level structure through the shell, one level per op. + let start = Instant::now(); + let mut rel = String::from("d"); + for level in 0..DEPTH { + if level > 0 { + rel.push_str("/d"); + } + vsh::commands::mkdir(&mut state, &rel, false).unwrap(); + } let create_time = start.elapsed(); println!( "✓ Created 1000-level nested directories in {:?}", create_time ); - // Verify it exists - assert!(current_path.exists()); - assert!(current_path.is_dir()); + // Verify it exists and every level was recorded + let deepest = state.resolve_path(&rel); + assert!(deepest.exists()); + assert!(deepest.is_dir()); + assert_eq!(state.history.len(), DEPTH, "Each mkdir should be recorded"); - // Test undo (remove all levels) + // Undo all 1000 operations (innermost first) let undo_start = Instant::now(); - let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - - // Record the creation in state - for i in 0..1000 { - let path = format!("level_{:04}", i); - vsh::commands::mkdir(&mut state, &path, true).unwrap(); - } - - // Undo all 1000 operations - for _ in 0..1000 { + for _ in 0..DEPTH { vsh::commands::undo(&mut state, 1, false).unwrap(); } - let undo_time = undo_start.elapsed(); println!("✓ Undid 1000 operations in {:?}", undo_time); + assert!( + user_entries(temp.path()).is_empty(), + "Undo should remove every level" + ); + // Verify requirements assert!(create_time.as_secs() < 5, "Should create in <5s"); assert!(undo_time.as_secs() < 2, "Should undo in <2s"); @@ -76,30 +126,69 @@ fn stress_deep_nesting_1000_levels() { #[test] #[ignore] fn stress_deep_nesting_no_stack_overflow() { + use nix::fcntl::{openat, OFlag}; + use nix::sys::stat::{mkdirat, Mode}; + use std::os::fd::OwnedFd; + + const DEPTH: usize = 5000; + let temp = TempDir::new().unwrap(); + let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Create even deeper nesting (5000 levels) to test for stack overflow - let mut current_path = temp.path().to_path_buf(); - for i in 0..5000 { - current_path.push(format!("d{}", i)); + // Even deeper nesting (5000 levels) to test for stack overflow. Its + // absolute path is far longer than PATH_MAX, so it cannot be created + // with path-based calls (`fs::create_dir_all` fails with ENAMETOOLONG). + // Build it one level at a time relative to the parent's descriptor. + let deep_rel = vec!["d"; DEPTH].join("/"); + assert!( + state.root.join(&deep_rel).as_os_str().len() > libc::PATH_MAX as usize, + "this test is meant to go beyond PATH_MAX" + ); + let mut dir: OwnedFd = fs::File::open(&state.root).unwrap().into(); + for _ in 0..DEPTH { + mkdirat(&dir, "d", Mode::from_bits_truncate(0o755)).unwrap(); + dir = openat( + &dir, + "d", + OFlag::O_RDONLY | OFlag::O_DIRECTORY, + Mode::empty(), + ) + .unwrap(); } - - // Should not cause stack overflow - let result = fs::create_dir_all(¤t_path); + drop(dir); + + // The shell must stay stable when handed a path this deep: resolving it + // is pure normalisation, and filesystem operations on it fail with an + // error instead of overflowing the stack or panicking. + assert_eq!(state.resolve_path(&deep_rel), state.root.join(&deep_rel)); + let before = state.history.len(); + let mkdir_result = vsh::commands::mkdir(&mut state, &format!("{deep_rel}/x"), false); + assert!( + mkdir_result.is_err(), + "mkdir beyond PATH_MAX should fail cleanly" + ); + let touch_result = vsh::commands::touch(&mut state, &format!("{deep_rel}/f"), false); assert!( - result.is_ok(), - "Should handle 5000 levels without stack overflow" + touch_result.is_err(), + "touch beyond PATH_MAX should fail cleanly" + ); + assert_eq!( + state.history.len(), + before, + "Failed operations must not be recorded" ); // Cleanup should also not overflow - let cleanup_result = fs::remove_dir_all(temp.path().join("d0")); + let cleanup_result = fs::remove_dir_all(temp.path().join("d")); assert!(cleanup_result.is_ok(), "Cleanup should not overflow"); + assert!(user_entries(temp.path()).is_empty()); } // ============================================================ // Stress Test 2: Large Files // ============================================================ +/// Writes 1 GB of temporary data to disk (about 1.5 s on a local SSD). #[test] #[ignore] fn stress_large_file_1gb() { @@ -119,44 +208,69 @@ fn stress_large_file_1gb() { file.write_all(&chunk).unwrap(); } file.sync_all().unwrap(); + drop(file); let create_time = start.elapsed(); println!("✓ Created 1GB file in {:?}", create_time); // Verify size + const SIZE: u64 = 1024 * 1024 * 1024; let metadata = fs::metadata(&large_file).unwrap(); - assert_eq!( - metadata.len(), - 1024 * 1024 * 1024, - "File should be exactly 1GB" - ); + assert_eq!(metadata.len(), SIZE, "File should be exactly 1GB"); // Test operations on large file let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Touch shouldn't fail on large file (just updates metadata) - let touch_start = Instant::now(); - vsh::commands::touch(&mut state, "large.bin", true).unwrap(); - let touch_time = touch_start.elapsed(); - println!("✓ Touch on 1GB file in {:?}", touch_time); - - assert!( - touch_time.as_millis() < 100, - "Touch should be <100ms even for large files" + // Metadata-only operations must not depend on the file size. (`touch` + // in vsh only creates files, so it cannot be applied to this one; the + // reversible metadata operations are `chmod` and `mv`.) Each operation + // and its undo should be <100ms even for a 1GB file. + let timed = |label: &str, op: &mut dyn FnMut()| { + let t = Instant::now(); + op(); + let elapsed = t.elapsed(); + println!("✓ {label} on 1GB file in {elapsed:?}"); + assert!( + elapsed.as_millis() < 100, + "{label} should be <100ms even for large files (was {elapsed:?})" + ); + }; + + timed("chmod", &mut || { + vsh::commands::chmod(&mut state, "600", "large.bin", false).unwrap() + }); + timed("undo chmod", &mut || { + vsh::commands::undo(&mut state, 1, false).unwrap() + }); + timed("mv", &mut || { + vsh::commands::mv(&mut state, "large.bin", "moved.bin", false).unwrap() + }); + assert_eq!( + fs::metadata(temp.path().join("moved.bin")).unwrap().len(), + SIZE ); + timed("undo mv", &mut || { + vsh::commands::undo(&mut state, 1, false).unwrap() + }); - // Memory usage check: should not load entire file into memory - // This test would fail if implementation naively reads entire file + // Memory usage check: should not load entire file into memory. + // These operations never read file content: the file is intact. + assert_eq!(fs::metadata(&large_file).unwrap().len(), SIZE); + assert_eq!( + metadata.permissions(), + fs::metadata(&large_file).unwrap().permissions() + ); } #[test] #[ignore] fn stress_large_file_undo_streaming() { + const SIZE: usize = 100 * 1024 * 1024; + let temp = TempDir::new().unwrap(); let file_path = temp.path().join("large.txt"); // Create 100MB file - let _size = 100 * 1024 * 1024; let mut file = fs::File::create(&file_path).unwrap(); let chunk = vec![b'A'; 1024 * 1024]; // 1MB chunks @@ -165,19 +279,24 @@ fn stress_large_file_undo_streaming() { } drop(file); - // Verify we don't OOM when saving undo data for large file let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // This should use streaming, not load all 100MB into memory + // Removing a file is the operation that saves the file's content as undo + // data. (`touch` cannot be used here: in vsh it only creates files.) + // + // NOT streaming: `rm` currently holds the whole content in memory as + // `undo_data` and persists it in the state journal as JSON. This test + // checks that a 100MB rm/undo round trip completes, restores the content + // byte for byte, and that the undo itself stays fast. Out-of-line + // (streamed) undo storage is open work, recorded in + // docs/audits/2026-11-16-hypatia-remediation.adoc. let undo_save_start = Instant::now(); - vsh::commands::touch(&mut state, "large.txt", true).unwrap(); + vsh::commands::rm(&mut state, "large.txt", false).unwrap(); let undo_save_time = undo_save_start.elapsed(); + assert!(!file_path.exists(), "rm should remove the file"); println!("✓ Saved undo data for 100MB file in {:?}", undo_save_time); - // Check memory didn't spike (we can't easily test this in Rust, - // but in practice this would be monitored externally) - // Undo should also be fast let undo_start = Instant::now(); vsh::commands::undo(&mut state, 1, false).unwrap(); @@ -185,6 +304,14 @@ fn stress_large_file_undo_streaming() { println!("✓ Undid large file operation in {:?}", undo_time); assert!(undo_time.as_millis() < 500, "Undo should be <500ms"); + + // The restored file must be the original, byte for byte. + let restored = fs::read(&file_path).unwrap(); + assert_eq!(restored.len(), SIZE, "Restored file should be 100MB"); + assert!( + restored.iter().all(|&b| b == b'A'), + "Restored content should match the original" + ); } // ============================================================ @@ -225,9 +352,14 @@ fn stress_many_operations_10000() { assert!(create_time.as_secs() < 30, "Should complete in <30s"); assert!(undo_time.as_secs() < 30, "Should undo in <30s"); - // Verify all files removed - let entries: Vec<_> = fs::read_dir(temp.path()).unwrap().collect(); - assert_eq!(entries.len(), 0, "All files should be undone"); + // Verify all files removed (only the shell's own state files remain) + let entries = user_entries(temp.path()); + assert!( + entries.is_empty(), + "All files should be undone, found {} (first: {:?})", + entries.len(), + entries.first() + ); } #[test] @@ -273,13 +405,22 @@ fn stress_undo_redo_efficiency() { vsh::commands::undo(&mut state, 1, false).unwrap(); } let undo_time = start.elapsed(); + assert!( + user_entries(temp.path()).is_empty(), + "Undo should remove all files" + ); // Redo should also be O(1) per operation let redo_start = Instant::now(); for _ in 0..100 { - state.pop_redo().unwrap(); + vsh::commands::redo(&mut state, 1, false).unwrap(); } let redo_time = redo_start.elapsed(); + assert_eq!( + user_entries(temp.path()).len(), + 100, + "Redo should recreate all files" + ); println!("✓ Undo 100: {:?}, Redo 100: {:?}", undo_time, redo_time); @@ -342,9 +483,16 @@ fn stress_concurrent_multiple_instances() { handle.join().unwrap(); } - // Verify total files created (10 threads * 100 files = 1000) - let entries: Vec<_> = fs::read_dir(&temp_path).unwrap().collect(); + // Verify total files created (10 threads * 100 files = 1000). The + // instances share one sandbox root, so its state files are there too; + // nothing else may be. + let entries = user_entries(&temp_path); assert_eq!(entries.len(), 1000, "Should have 1000 total files"); + let mut expected: Vec = (0..10) + .flat_map(|t| (0..100).map(move |i| format!("thread_{}_file_{}.txt", t, i))) + .collect(); + expected.sort(); + assert_eq!(entries, expected, "Exactly the threads' files should exist"); println!("✓ Concurrent access: 10 threads, 100 ops each = 1000 files"); } @@ -402,8 +550,11 @@ fn stress_resource_limits_max_history() { let temp = TempDir::new().unwrap(); let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Create operations until we hit a reasonable limit - // In practice, there should be a configurable max history size + // ShellState bounds its history (`max_history_size`, 10,000 by default); + // a user-facing setting for it remains tracked by #190. + let limit = state + .max_history_size + .expect("ShellState should bound its history by default"); for i in 0..100_000 { let path = format!("file_{}.txt", i); @@ -412,17 +563,30 @@ fn stress_resource_limits_max_history() { // Every 10k operations, check if we have a limit if i % 10_000 == 0 { println!(" {} operations...", i); + assert!(state.history.len() <= limit); } } - // Even with 100k operations, should not OOM - // (This test would be better with actual memory monitoring) - + // Even with 100k operations, should not OOM: the in-memory history is + // capped at the limit... let history_size = state.history.len(); println!("✓ Completed {} operations without OOM", history_size); + assert_eq!( + history_size, limit, + "History should be capped at max_history_size" + ); - // A configurable production history bound remains tracked by #190. - // assert!(history_size <= MAX_HISTORY_SIZE); + // ...and so is the persisted state, which must not grow with the total + // number of operations. A touch op serialises to ~200 bytes, so a + // snapshot plus journal of a capped history stays within a few MB; + // 32 MiB leaves ample headroom while catching unbounded growth (100k + // uncapped ops alone would exceed it). + let persisted = state_files_size(temp.path()); + println!("✓ Persisted state: {} bytes", persisted); + assert!( + persisted < 32 * 1024 * 1024, + "Persisted state should be bounded by the history limit (was {persisted} bytes)" + ); } #[test] From 2273913d12969ecb812da660953ebaa649081fe1 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:23:00 +0000 Subject: [PATCH 07/14] fix(state): recover from a torn journal; journal cd's previous_dir Two findings from the Codex review on #229, both regressions from the journal introduced in 52ed149: - A torn journal line (crash mid-append) ended replay but left the line in place, so operations appended after the restart were skipped by every later reload and could no longer be undone. load() now marks a snapshot as pending when replay stops early, so the next persist writes a full snapshot and truncates the journal. - cd set previous_dir without persisting it; before the journal, the next operation's full rewrite carried it. cd now goes through ShellState::set_previous_dir, which journals a PreviousDir entry, so cd - survives a restart. Two regression tests; the torn-tail one fails without the fix. cargo test 837 passed; stress suite 11 passed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .../2026-11-16-hypatia-remediation.adoc | 10 +-- impl/rust-cli/src/executable.rs | 2 +- impl/rust-cli/src/state.rs | 70 +++++++++++++++++++ 3 files changed, 77 insertions(+), 5 deletions(-) diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index 1ecccbd1..b4829ce0 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -112,9 +112,13 @@ Shell bugs fixed (`src/state.rs`, `src/commands.rs`): keeps the cost amortised O(1). Snapshots are written to a temporary file and renamed, and record the last journal sequence number they contain, so a crash cannot tear the snapshot or replay an entry twice. A torn journal - line or a sequence gap ends replay. After the fix, 1,000 touches take + line or a sequence gap ends replay and forces the next save to be a full + snapshot, so operations made after a crash are not stranded behind the + bad line (Codex review on #229). After the fix, 1,000 touches take 0.04 s. Seven new unit tests in `state.rs` cover replay, compaction, trim, - a torn tail, crash-after-rename and transactions. + a torn tail, crash-after-rename and transactions; two more cover + operations after a torn tail and `cd -` surviving a restart (`cd` now + journals `previous_dir`). * *O(n²) single-step undo.* Each `undo 1` walked past every already-undone operation to pick its target, then searched for that target again from the oldest end of the history to mark it. A checked hint for the block of undone operations removes the rescan: @@ -190,8 +194,6 @@ Still open: * *macOS.* The suite is not run there: `PATH_MAX` is 1024, so the 1,000-level test cannot pass with absolute paths, and the rest was not measured on macOS. -* `previous_dir` (set by `cd` without a save) reaches disk at the next - snapshot, not at the next operation as before. * Neither the journal nor the snapshot is `fsync`ed (the old `fs::write` was not either), the files keep the default mode, and they still live in the session root. Route plan items E1d and G2 diff --git a/impl/rust-cli/src/executable.rs b/impl/rust-cli/src/executable.rs index aeb72a25..698df7f4 100644 --- a/impl/rust-cli/src/executable.rs +++ b/impl/rust-cli/src/executable.rs @@ -402,7 +402,7 @@ impl ExecutableCommand for Command { } // Store current directory as previous before changing - state.previous_dir = Some(state.root.clone()); + state.set_previous_dir(state.root.clone()); // Change the shell's working directory std::env::set_current_dir(&target)?; diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index 23df51f6..d1f1101c 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -664,6 +664,21 @@ impl ShellState { Ok(()) } + /// Set the directory `cd -` returns to, and journal it so it survives a + /// restart without waiting for the next snapshot. + pub fn set_previous_dir(&mut self, dir: PathBuf) { + self.previous_dir = Some(dir); + let persisted = + self.persist_entries(&[JournalEntryRef::PreviousDir(self.previous_dir.clone())]); + if let Err(e) = persisted { + eprintln!( + "{} Failed to save previous directory: {}", + "Warning:".bright_yellow(), + e + ); + } + } + /// Drop the active transaction without committing it (after a rollback) /// and persist that, so a restart does not resurrect it. pub fn abort_transaction(&mut self) { @@ -829,23 +844,32 @@ impl ShellState { if self.journal_file.exists() { let journal = crate::fs_pure::read_to_string(&self.journal_file)?; + let mut replayed_all = true; for line in journal.lines() { // A torn line (crash mid-append) ends the replay, and so does // a sequence gap: replay keeps the longest consistent prefix. let Ok(JournalLine { seq, entry }) = serde_json::from_str::(line) else { + replayed_all = false; break; }; if seq <= self.journal_seq { continue; // already folded into the snapshot } if seq != self.journal_seq + 1 { + replayed_all = false; break; } self.replay(entry); self.journal_seq = seq; self.journal_entries += 1; } + // Entries appended after a torn line or gap would be skipped by + // every later reload. Make the next persist write a full snapshot, + // which also truncates the journal, instead of appending. + if !replayed_all { + self.snapshot_pending = true; + } } // The history was replaced wholesale; drop the undone-block hint. @@ -877,6 +901,9 @@ impl ShellState { let n = n.min(self.history.len()); self.history.drain(0..n); } + JournalEntry::PreviousDir(dir) => { + self.previous_dir = dir; + } } } @@ -1209,6 +1236,8 @@ enum JournalEntry { Undone { id: Uuid, undone_by: Uuid }, /// The oldest `n` operations dropped by the history size limit. Trim(usize), + /// The directory `cd -` returns to, as set by `cd`. + PreviousDir(Option), } /// Borrowing twin of [`JournalEntry`]; serialises to the same shape. @@ -1217,6 +1246,7 @@ enum JournalEntryRef<'a> { Record(&'a Operation), Undone { id: Uuid, undone_by: Uuid }, Trim(usize), + PreviousDir(Option), } #[derive(Deserialize)] @@ -1749,6 +1779,46 @@ mod tests { assert_eq!(summary(&reloaded), summary(&state)); } + #[test] + fn test_operations_after_torn_tail_survive_reload() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + { + use std::io::Write; + let mut journal = fs::OpenOptions::new() + .append(true) + .open(&state.journal_file) + .unwrap(); + journal.write_all(b"{\"seq\":2,\"entry\":{\"Rec").unwrap(); + } + + // The restarted shell keeps working after the crash... + let mut restarted = reopen(&root); + record(&mut restarted, "b"); + record(&mut restarted, "c"); + + // ...and those later operations must not hide behind the torn line. + let reloaded = reopen(&root); + assert_eq!(reloaded.history.len(), 3); + assert_eq!(summary(&reloaded), summary(&restarted)); + } + + #[test] + fn test_previous_dir_survives_reload_without_snapshot() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + state.set_previous_dir(PathBuf::from("/tmp/elsewhere")); + assert!(!state.state_file.exists(), "no snapshot should be needed"); + + let reloaded = reopen(&root); + assert_eq!( + reloaded.previous_dir.as_deref(), + Some(Path::new("/tmp/elsewhere")) + ); + } + #[test] fn test_snapshot_skips_already_folded_journal_entries() { let root = persisted_root(); From bd24f5442ea1b94b5facb87ae45b2f4d2932cbf3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:28:56 +0000 Subject: [PATCH 08/14] fix(state): treat invalid UTF-8 in the journal tail as a torn line A crash can tear the last journal line inside a multi-byte character (a path with non-ASCII text). read_to_string then failed with InvalidData before per-line recovery ran, so ShellState::new failed and the workspace could not be reopened. The journal is now read as bytes and each line parsed with serde_json::from_slice, so an invalid tail ends replay like any other torn line. Codex review on #229. Regression test fails without the fix. cargo test 838 passed; stress suite 11 passed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- impl/rust-cli/src/state.rs | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index d1f1101c..55ddcb9c 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -843,12 +843,16 @@ impl ShellState { } if self.journal_file.exists() { - let journal = crate::fs_pure::read_to_string(&self.journal_file)?; + // Read bytes, not a string: a crash can tear the last line inside + // a multi-byte character, and that must count as a torn line + // rather than make the whole file unreadable. + let journal = crate::fs_pure::read_to_end(&self.journal_file)?; + let body = journal.strip_suffix(b"\n").unwrap_or(&journal); let mut replayed_all = true; - for line in journal.lines() { + for line in body.split(|&b| b == b'\n').filter(|_| !body.is_empty()) { // A torn line (crash mid-append) ends the replay, and so does // a sequence gap: replay keeps the longest consistent prefix. - let Ok(JournalLine { seq, entry }) = serde_json::from_str::(line) + let Ok(JournalLine { seq, entry }) = serde_json::from_slice::(line) else { replayed_all = false; break; @@ -1804,6 +1808,30 @@ mod tests { assert_eq!(summary(&reloaded), summary(&restarted)); } + #[test] + fn test_journal_torn_inside_multibyte_char_reopens() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + { + use std::io::Write; + let mut journal = fs::OpenOptions::new() + .append(true) + .open(&state.journal_file) + .unwrap(); + // "é" is 0xC3 0xA9; stop after the first byte. + journal + .write_all(b"{\"seq\":2,\"entry\":{\"Record\":{\"path\":\"caf\xC3") + .unwrap(); + } + + let mut reopened = reopen(&root); + assert_eq!(summary(&reopened), summary(&state)); + record(&mut reopened, "b"); + let reloaded = reopen(&root); + assert_eq!(reloaded.history.len(), 2); + } + #[test] fn test_previous_dir_survives_reload_without_snapshot() { let root = persisted_root(); From 56f9611d5554bb5cba839e0a37aa98ac51dfc670 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:38:11 +0000 Subject: [PATCH 09/14] fix(state): repair newline-less journal tail; atomic record+trim; 0600 files Three findings from the Codex review of bd24f54 on #229: - A last journal line with no newline (crash between the record and its newline) parsed, but the next append was glued onto it and both were lost on the following reload. A missing final newline now counts as a torn tail: the complete record is kept and the next persist writes a snapshot instead of appending. - A record and the history-limit trim it caused were two journal lines, so a crash between them reloaded a history over the limit. They are now one Record { op, trim } line. (The journal format is new in this PR, so nothing on disk uses the old shape.) - The journal and the snapshot temp file were created with the process umask, so a 0600 snapshot became world-readable after compaction, and history can hold deleted files' contents. Both are now created 0600 on Unix. Three regression tests; the newline and mode tests fail without their fixes. cargo test 841 passed; stress suite 11 passed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .../2026-11-16-hypatia-remediation.adoc | 7 +- impl/rust-cli/src/state.rs | 113 ++++++++++++++---- 2 files changed, 94 insertions(+), 26 deletions(-) diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index b4829ce0..d28c8625 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -195,7 +195,8 @@ Still open: 1,000-level test cannot pass with absolute paths, and the rest was not measured on macOS. * Neither the journal nor the snapshot is `fsync`ed (the old `fs::write` - was not either), the files keep the default mode, and they still live in - the session root. Route plan items E1d and G2 - (`docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc`) cover fsync, 0600 and moving + was not either), and they still live in the session root. Both are now + created with mode 0600 on Unix, since history can hold deleted file + contents (Codex review on #229). Route plan items E1d and G2 + (`docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc`) still cover fsync and moving state out of the root; the journal is a new file they must include. diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index 55ddcb9c..b81c18aa 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -743,13 +743,11 @@ impl ShellState { let Some(op) = self.history.last() else { return self.save(); }; - let mut entries = vec![JournalEntryRef::Record(op)]; - if trimmed > 0 { - entries.push(JournalEntryRef::Trim(trimmed)); - } + // The record and its trim are one line, so a crash cannot persist the + // new operation without the history-limit trim it caused. + let entries = [JournalEntryRef::Record { op, trim: trimmed }]; let appended = append_journal(&self.journal_file, self.journal_seq, &entries); - let count = entries.len(); - self.after_append(appended, count) + self.after_append(appended, entries.len()) } /// Persist journal entries that do not borrow from `self`. @@ -805,7 +803,7 @@ impl ShellState { let file_name = format!(".vsh_state.json.{}.tmp", Uuid::new_v4().simple()); let tmp = self.state_file.with_file_name(file_name); let written = (|| -> Result<()> { - let mut out = std::io::BufWriter::new(fs::File::create(&tmp)?); + let mut out = std::io::BufWriter::new(create_private(&tmp)?); serde_json::to_writer(&mut out, &state)?; out.flush()?; fs::rename(&tmp, &self.state_file)?; @@ -848,7 +846,11 @@ impl ShellState { // rather than make the whole file unreadable. let journal = crate::fs_pure::read_to_end(&self.journal_file)?; let body = journal.strip_suffix(b"\n").unwrap_or(&journal); - let mut replayed_all = true; + // A last line with no newline may parse, but the next append + // would be glued onto it (`}{`), losing both lines on the + // following reload. Treat it like a torn tail: keep what parses, + // then snapshot before appending again. + let mut replayed_all = journal.is_empty() || journal.ends_with(b"\n"); for line in body.split(|&b| b == b'\n').filter(|_| !body.is_empty()) { // A torn line (crash mid-append) ends the replay, and so does // a sequence gap: replay keeps the longest consistent prefix. @@ -887,13 +889,15 @@ impl ShellState { /// the redo stack is not persisted, as before. fn replay(&mut self, entry: JournalEntry) { match entry { - JournalEntry::Record(op) => { + JournalEntry::Record { op, trim } => { if let Some(txn) = self.active_transaction.as_mut() { if op.transaction_id == Some(txn.id) { txn.operations.push(op.id); } } self.history.push(op); + let trim = trim.min(self.history.len()); + self.history.drain(0..trim); } JournalEntry::Undone { id, undone_by } => { if let Some(op) = self.history.iter_mut().rev().find(|o| o.id == id) { @@ -901,10 +905,6 @@ impl ShellState { op.undone_by = Some(undone_by); } } - JournalEntry::Trim(n) => { - let n = n.min(self.history.len()); - self.history.drain(0..n); - } JournalEntry::PreviousDir(dir) => { self.previous_dir = dir; } @@ -1234,12 +1234,15 @@ const JOURNAL_MIN_ENTRIES: usize = 1024; /// One history mutation in the journal (`.vsh_state.journal`, JSON lines). #[derive(Deserialize)] enum JournalEntry { - /// An operation appended to the history. - Record(Operation), + /// An operation appended to the history, then the oldest `trim` + /// operations dropped by the history size limit (0 when under it). + Record { + op: Operation, + #[serde(default)] + trim: usize, + }, /// An operation marked undone. Undone { id: Uuid, undone_by: Uuid }, - /// The oldest `n` operations dropped by the history size limit. - Trim(usize), /// The directory `cd -` returns to, as set by `cd`. PreviousDir(Option), } @@ -1247,12 +1250,25 @@ enum JournalEntry { /// Borrowing twin of [`JournalEntry`]; serialises to the same shape. #[derive(Serialize)] enum JournalEntryRef<'a> { - Record(&'a Operation), + Record { op: &'a Operation, trim: usize }, Undone { id: Uuid, undone_by: Uuid }, - Trim(usize), PreviousDir(Option), } +/// Create (or truncate) a persistence file readable only by its owner. +/// History can hold the contents of deleted files in `undo_data`, so the +/// journal and snapshot must not inherit a permissive umask. +fn create_private(path: &Path) -> std::io::Result { + let mut options = fs::OpenOptions::new(); + options.write(true).create(true).truncate(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + options.open(path) +} + #[derive(Deserialize)] struct JournalLine { seq: u64, @@ -1271,10 +1287,14 @@ struct JournalLineRef<'a, 'b> { /// entries still reach the file in a single write. fn append_journal(path: &Path, last_seq: u64, entries: &[JournalEntryRef<'_>]) -> Result<()> { use std::io::Write; - let file = fs::OpenOptions::new() - .create(true) - .append(true) - .open(path)?; + let mut options = fs::OpenOptions::new(); + options.create(true).append(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); // see create_private + } + let file = options.open(path)?; let mut out = std::io::BufWriter::with_capacity(64 * 1024, file); for (seq, entry) in (last_seq + 1..).zip(entries) { serde_json::to_writer(&mut out, &JournalLineRef { seq, entry })?; @@ -1808,6 +1828,53 @@ mod tests { assert_eq!(summary(&reloaded), summary(&restarted)); } + #[test] + fn test_journal_without_final_newline_is_repaired() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + // Crash after the last record but before its newline. + let journal = fs::read(&state.journal_file).unwrap(); + fs::write(&state.journal_file, journal.strip_suffix(b"\n").unwrap()).unwrap(); + + let mut restarted = reopen(&root); + assert_eq!(restarted.history.len(), 1, "the complete record is kept"); + record(&mut restarted, "b"); + + let reloaded = reopen(&root); + assert_eq!(reloaded.history.len(), 2); + assert_eq!(summary(&reloaded), summary(&restarted)); + } + + #[test] + fn test_record_and_trim_share_one_journal_line() { + let root = persisted_root(); + let mut state = reopen(&root); + state.max_history_size = Some(3); + for i in 0..5 { + record(&mut state, &format!("f{i}")); + } + let journal = fs::read_to_string(&state.journal_file).unwrap(); + // One line per operation: no trim can be split from its record. + assert_eq!(journal.lines().count(), 5); + assert!(journal.lines().last().unwrap().contains("\"trim\":1")); + } + + #[cfg(unix)] + #[test] + fn test_persistence_files_are_private() { + use std::os::unix::fs::PermissionsExt; + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + state.save().unwrap(); + record(&mut state, "b"); + for file in [&state.journal_file, &state.state_file] { + let mode = fs::metadata(file).unwrap().permissions().mode() & 0o777; + assert_eq!(mode, 0o600, "{}", file.display()); + } + } + #[test] fn test_journal_torn_inside_multibyte_char_reopens() { let root = persisted_root(); From 0991b17fb973cef517a18725f68fa89a8e438f5d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:49:43 +0000 Subject: [PATCH 10/14] fix(state): rebuild instead of gapping when state files vanish; retry failed snapshots Three findings from the Codex review of 56f9611 on #229: - The journal and snapshot live in the command root, so a user can rm or mv them from the shell. The next append then recreated the journal at the in-memory sequence number, and reload saw a gap and dropped the whole history. ShellState now tracks the journal's expected size and whether its base snapshot exists; if either changed, the next persist writes a full snapshot from memory instead of appending. - A failed snapshot (the only record of transaction begin, commit and rollback) did not set snapshot_pending, so a later append could lose or resurrect a transaction. save() now marks the snapshot pending on any error. - Mustfile.a2ml still required .machine_readable/6a2/, which the deed migration removed, so that critical invariant failed on every checkout. The two 6a2 checks are replaced by repo-deed-present. Ledger O-2 updated. Three regression tests, each failing without its fix. cargo test 844 passed; stress suite 11 passed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .machine_readable/contractiles/Mustfile.a2ml | 11 +-- archive/a2ml-v1/MIGRATION-LEDGER.adoc | 2 +- impl/rust-cli/src/state.rs | 77 ++++++++++++++++++++ 3 files changed, 81 insertions(+), 9 deletions(-) diff --git a/.machine_readable/contractiles/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml index 55f8ab48..6a62791d 100644 --- a/.machine_readable/contractiles/Mustfile.a2ml +++ b/.machine_readable/contractiles/Mustfile.a2ml @@ -61,16 +61,11 @@ hooks fail if any check fails. - run: test -f .machine_readable/contractiles/bust/Bustfile.a2ml && test -f .machine_readable/contractiles/dust/Dustfile.a2ml - severity: critical -### six-directory-present -- description: 6a2 directory exists with required files -- run: test -d .machine_readable/6a2 && test -f .machine_readable/6a2/META.a2ml && test -f .machine_readable/6a2/ECOSYSTEM.a2ml && test -f .machine_readable/6a2/STATE.a2ml && test -f .machine_readable/6a2/PLAYBOOK.a2ml && test -f .machine_readable/6a2/AGENTIC.a2ml && test -f .machine_readable/6a2/NEUROSYM.a2ml +### repo-deed-present +- description: The repo deed holds the descriptiles; the retired 6a2 A2ML files are archived (D312, D313) +- run: test -f valence-shell_chora.deed && test -f archive/a2ml-v1/MIGRATION-LEDGER.adoc && test ! -e .machine_readable/6a2 - severity: critical -### anchors-directory -- description: anchors directory exists in 6a2 -- run: test -d .machine_readable/6a2/anchors -- severity: warning - ### self-validating-structure - description: self-validating directory has k9-svc and examples - run: test -d .machine_readable/self-validating && test -d .machine_readable/self-validating/k9-svc && test -d .machine_readable/self-validating/examples diff --git a/archive/a2ml-v1/MIGRATION-LEDGER.adoc b/archive/a2ml-v1/MIGRATION-LEDGER.adoc index e3ba3781..190ea3b2 100644 --- a/archive/a2ml-v1/MIGRATION-LEDGER.adoc +++ b/archive/a2ml-v1/MIGRATION-LEDGER.adoc @@ -181,7 +181,7 @@ archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). |=== | ID | Item | Reason | O-1 | `.machine_readable/CLADE.a2ml` | Excluded by the task. CLADE is not folded into a descriptile: its identity content goes to the chora deed and its lifecycle to `STATE.deed` (CHORA-SPEC 11.1, clade-to-repo-deed). Its own change. -| O-2 | `.machine_readable/contractiles/*.a2ml` | Excluded. Contractiles become edicts (`file.deed`) and K9 contracts, a separate migration. `Mustfile.a2ml` checks `six-directory-present` and `anchors-directory` name `.machine_readable/6a2/` and now fail; they already failed before (`6a2/anchors` never existed, and the `bust/`, `dust/` and `self-validating` checks name absent paths). No runner here executes them: `contractile.just` generates other checks. A2ML is frozen, so they were not edited. +| O-2 | `.machine_readable/contractiles/*.a2ml` | Excluded. Contractiles become edicts (`file.deed`) and K9 contracts, a separate migration. `Mustfile.a2ml`: the `six-directory-present` (critical) and `anchors-directory` checks named `.machine_readable/6a2/`; the first passed before this migration. Both are replaced by one `repo-deed-present` check (deed and ledger exist, `6a2/` is gone), so the invariant follows the layout instead of failing on every checkout (Codex review on #229). The `bust/`, `dust/` and `self-validating` checks name paths that were already absent and are unchanged. | O-3 | `.machine_readable/bot_directives/*.a2ml` | Excluded. `methodology.a2ml` line 112 still says "Phase 0 reads STATE.a2ml first". Not edited (frozen A2ML). Its prose `README.adoc` was updated (U-7). | O-4 | `.machine_readable/ECHO_TYPES_OCHRANCE_BRIDGE.a2ml` | Excluded. Named by `.github/scripts/check-bridge-forbidden-phrases.sh` as a required artefact and by `.claude/CLAUDE.md`. | O-5 | `.machine_readable/IDRIS2_AXIOMS.a2ml` | Excluded and must stay in place: `.github/scripts/check-idris2-believe-me.sh` reads it, and `idris-verification.yml` triggers on it. diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index b81c18aa..0f311444 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -312,6 +312,12 @@ pub struct ShellState { /// persist must write a full snapshot rather than append. snapshot_pending: bool, + /// Size in bytes the journal file should have on disk. If the file is + /// removed, moved or rewritten from inside the shell (it lives in the + /// command root), appending would leave a sequence gap that discards the + /// whole history on reload, so a mismatch forces a full snapshot. + journal_len: u64, + /// Last exit code from external command (for $? support) pub last_exit_code: i32, @@ -382,6 +388,7 @@ impl ShellState { journal_entries: 0, undone_run: 0..0, snapshot_pending: false, + journal_len: 0, last_exit_code: 0, previous_dir: None, variables: HashMap::new(), @@ -768,10 +775,21 @@ impl ShellState { } else { self.journal_seq += count as u64; self.journal_entries += count; + self.journal_len = fs::metadata(&self.journal_file).map_or(0, |m| m.len()); } appended } + /// Whether the files on disk are still the ones this state wrote: the + /// journal has the expected size, and the snapshot the journal builds on + /// still exists. Either can be removed or moved by a command, since both + /// live in the command root. + fn persistence_intact(&self) -> bool { + let journal_len = fs::metadata(&self.journal_file).map_or(0, |m| m.len()); + let snapshot_seq = self.journal_seq - self.journal_entries as u64; + journal_len == self.journal_len && (snapshot_seq == 0 || self.state_file.exists()) + } + /// The journal is folded into a fresh snapshot once it holds at least /// half as many entries as the history has operations (and at least /// `JOURNAL_MIN_ENTRIES`). A snapshot costs O(history length), which is @@ -781,6 +799,7 @@ impl ShellState { self.snapshot_pending || (self.journal_entries >= JOURNAL_MIN_ENTRIES && 2 * self.journal_entries >= self.history.len()) + || !self.persistence_intact() } /// Write a full snapshot and empty the journal. @@ -790,6 +809,16 @@ impl ShellState { /// the journal sequence number it includes, so a crash between the rename /// and the journal truncation cannot replay entries twice. fn save(&mut self) -> Result<()> { + let saved = self.write_snapshot(); + // Transaction boundaries are only recorded by a snapshot, so a failed + // one must be retried before anything is appended to the journal. + if saved.is_err() { + self.snapshot_pending = true; + } + saved + } + + fn write_snapshot(&mut self) -> Result<()> { use std::io::Write; let state = SerializableStateRef { @@ -822,6 +851,7 @@ impl ShellState { .set_len(0)?; } self.journal_entries = 0; + self.journal_len = 0; self.snapshot_pending = false; Ok(()) @@ -845,6 +875,7 @@ impl ShellState { // a multi-byte character, and that must count as a torn line // rather than make the whole file unreadable. let journal = crate::fs_pure::read_to_end(&self.journal_file)?; + self.journal_len = journal.len() as u64; let body = journal.strip_suffix(b"\n").unwrap_or(&journal); // A last line with no newline may parse, but the next append // would be glued onto it (`}{`), losing both lines on the @@ -1828,6 +1859,52 @@ mod tests { assert_eq!(summary(&reloaded), summary(&restarted)); } + #[test] + fn test_removed_journal_is_rebuilt_not_gapped() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + record(&mut state, "b"); + // e.g. `rm .vsh_state.journal` from inside the shell. + fs::remove_file(&state.journal_file).unwrap(); + record(&mut state, "c"); + + let reloaded = reopen(&root); + assert_eq!(reloaded.history.len(), 3); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_removed_snapshot_is_rebuilt_not_gapped() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + state.save().unwrap(); + record(&mut state, "b"); + fs::remove_file(&state.state_file).unwrap(); + record(&mut state, "c"); + + let reloaded = reopen(&root); + assert_eq!(reloaded.history.len(), 3); + assert_eq!(summary(&reloaded), summary(&state)); + } + + #[test] + fn test_failed_snapshot_is_retried_before_appending() { + let root = persisted_root(); + let mut state = reopen(&root); + record(&mut state, "a"); + // A directory in the snapshot's place makes the rename fail. + fs::create_dir(&state.state_file).unwrap(); + assert!(state.save().is_err()); + assert!(state.snapshot_pending); + + fs::remove_dir(&state.state_file).unwrap(); + record(&mut state, "b"); + assert!(state.state_file.is_file(), "the next persist must snapshot"); + assert!(!state.snapshot_pending); + } + #[test] fn test_journal_without_final_newline_is_repaired() { let root = persisted_root(); From ee5380e355101fe433b044e82657d61511a3505e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:15:16 +0000 Subject: [PATCH 11/14] revert: move the stress-suite repair and history journal to their own PR Owner ruling 2026-11-17: split this PR. This reverts the state.rs, commands.rs, executable.rs, stress_tests.rs, compilation_tests.yml and .gitignore changes of 52ed149, 2273913, bd24f54, 56f9611 and 0991b17. impl/rust-cli now differs from main only in parser.rs. Why: the repair replaced whole-file state saves with a journal beside the snapshot. Review raised fifteen crash-consistency findings against it, six still open, which point fixes were not closing. The route plan schedules the journal with a formal model and crash testing (E4, P8); it continues on its own branch with that design. Kept from 0991b17: the Mustfile repo-deed-present check and ledger row O-2, which belong to the deed migration. Also: proofs/coq/README.adoc said filesystem_composition.v carried one admit and called is_empty_dir_dec an axiom. The sources contain no admit or Admitted, and is_empty_dir_dec is a theorem proved with Classical.classic (CodeRabbit review). cargo test 827 passed (as on main); fmt, clippy, bridge check, deed_lint and the Mustfile check pass. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .github/workflows/compilation_tests.yml | 18 +- .gitignore | 2 - .../2026-11-16-hypatia-remediation.adoc | 112 +-- impl/rust-cli/src/commands.rs | 12 +- impl/rust-cli/src/executable.rs | 2 +- impl/rust-cli/src/state.rs | 842 +----------------- impl/rust-cli/tests/stress_tests.rs | 304 ++----- proofs/coq/README.adoc | 24 +- 8 files changed, 139 insertions(+), 1177 deletions(-) diff --git a/.github/workflows/compilation_tests.yml b/.github/workflows/compilation_tests.yml index 96280c18..be36564a 100644 --- a/.github/workflows/compilation_tests.yml +++ b/.github/workflows/compilation_tests.yml @@ -85,18 +85,12 @@ jobs: working-directory: impl/rust-cli run: cargo test --verbose - # The ignored stress suite (tests/stress_tests.rs) gates the build. It was - # repaired on 2026-11-17 (see docs/audits/2026-11-16-hypatia-remediation.adoc) - # and runs in 30-50 s locally, so 5 minutes leaves wide margin for a slow - # runner; there is deliberately no continue-on-error (Hypatia RE005). - # Linux only: stress_deep_nesting_1000_levels needs 1000 directory levels - # in one absolute path (~2,000 bytes), which fits Linux's PATH_MAX of 4096 - # but not macOS's 1024. - - name: Run ignored tests (stress) - if: runner.os == 'Linux' - working-directory: impl/rust-cli - timeout-minutes: 5 - run: cargo test --test stress_tests -- --ignored --test-threads=1 + # The ignored stress suite (tests/stress_tests.rs) is not run here. It ran + # under `continue-on-error: true`, which hid its state (Hypatia RE005): + # on 2026-11-16, 5 of its tests fail outright and 2 run for more than two + # minutes each, so this step only ever burned the job's 30-minute timeout. + # Run it by hand with `cargo test --test stress_tests -- --ignored` until + # the suite is repaired and can gate honestly. # ============================================================ # MSRV (Minimum Supported Rust Version) diff --git a/.gitignore b/.gitignore index 1eccccf4..a3b59c58 100644 --- a/.gitignore +++ b/.gitignore @@ -122,8 +122,6 @@ htmlcov/ ai-cli-crash-capture/ .cache/ .vsh_state.json -.vsh_state.journal -.vsh_state.json.*.tmp # ============ # Strategic diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index d28c8625..4619fa5c 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -56,7 +56,7 @@ They close when the underlying alert closes. | `npx_in_workflow` (2) | fixed | `bunx --no-install --bun rescript build`, which never fetches an unpinned package. | `missing_timeout_minutes`, WH006 | fixed | `labels.yml`, `label-triage.yml` (echo-types versions). | RE001 (3) | fixed | `harden-runner`: `block` to `api.github.com` in `instant-sync.yml`, `block` to the SMTP endpoint in `push-email-notify.yml`, `audit` in `hypatia-scan.yml`. -| RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; after its repair it gates the Linux test jobs again. See <>. +| RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; see <>. | WH008 (3) | fixed | See the Secret Scanner section. | SD022 (2) | fixed | Both paths named another tree (`echidna/src/rust/`, the Agda tarball path `agda-2.7.0.1/src/data/lib`); now qualified. | SD009 | left for the owner | `ffi/zig/src/main.zig` has no SPDX header. Licence edits are owner-only (estate doctrine 6). @@ -95,108 +95,8 @@ Run one test at a time on 2026-11-16, 120 s limit each: 5 fail `stress_large_file_1gb` was not run. The CI step only ever reached the 30-minute job timeout. Repairing the suite is separate work. -=== Repair (2026-11-17) - -All 11 tests now pass. The step is back in `compilation_tests.yml` as -`cargo test --test stress_tests -- --ignored --test-threads=1`, Linux only, -with `timeout-minutes: 5` and no `continue-on-error`. No test was deleted or -skipped, and no assertion was loosened. - -Shell bugs fixed (`src/state.rs`, `src/commands.rs`): - -* *O(n²) persistence.* Every recorded or undone operation rewrote the whole - history to `.vsh_state.json` (cloned, then pretty-printed). 1,000 touches - took 5.9 s; 10,000 and 100,000 never finished. The hot path now appends - one line to `.vsh_state.journal`; the snapshot is rewritten only when the - journal reaches half the history length (at least 1,024 entries), which - keeps the cost amortised O(1). Snapshots are written to a temporary file - and renamed, and record the last journal sequence number they contain, so - a crash cannot tear the snapshot or replay an entry twice. A torn journal - line or a sequence gap ends replay and forces the next save to be a full - snapshot, so operations made after a crash are not stranded behind the - bad line (Codex review on #229). After the fix, 1,000 touches take - 0.04 s. Seven new unit tests in `state.rs` cover replay, compaction, trim, - a torn tail, crash-after-rename and transactions; two more cover - operations after a torn tail and `cd -` surviving a restart (`cd` now - journals `previous_dir`). -* *O(n²) single-step undo.* Each `undo 1` walked past every already-undone - operation to pick its target, then searched for that target again from the - oldest end of the history to mark it. A checked hint for the block of undone operations removes the rescan: - undoing 10,000 operations one at a time went from 1.8 s to 0.34 s. A unit - test compares it against a full scan through undo, record, trim and an - out-of-order mark. -* *Rollback not persisted.* `rollback` cleared the active transaction - without saving. That had been masked by the next operation's full rewrite, - and the journal would have exposed it. It now goes through - `ShellState::abort_transaction`, which saves. - -Test expectations corrected (`tests/stress_tests.rs`): - -* `stress_concurrent_multiple_instances`, `stress_many_operations_10000`: - the listings counted the shell's own `.vsh_state*` files. They now exclude - only those files, and the concurrent test checks the exact set of 1,000 - names. -* `stress_deep_nesting_1000_levels`: `level_NNNN` names give an - 11,000-byte path, past `PATH_MAX`, and the test then ran `mkdir` on paths - that already existed. It now builds the 1,000 levels through the shell - with one-character names (about 2,000 bytes, asserted against `PATH_MAX`) - and undoes them all. -* `stress_deep_nesting_no_stack_overflow`: it only called - `fs::create_dir_all`, which fails with ENAMETOOLONG at 5,000 levels. It - now builds the tree with `mkdirat`/`openat`, checks that shell `mkdir` and - `touch` at that depth fail cleanly without recording anything, and removes - the tree. -* `stress_large_file_undo_streaming`, `stress_large_file_1gb`: both called - `touch` on an existing file, but vsh's `touch` only creates files - (EEXIST). The 100 MB test now runs `rm` (the operation that saves file - content as undo data) plus `undo` and checks the restored bytes. The 1 GB - test times `chmod`, `mv` and their undos. -* `stress_undo_redo_efficiency`: "redo" popped the redo stack without - redoing. It now calls `commands::redo` and checks the files return. -* `stress_resource_limits_max_history`: it now asserts the history is capped - at `max_history_size` and that the persisted state stays under 32 MiB - (measured: 2.3 MB). - -Measured (debug build, 4 cores, each test run alone with the CI flags): -whole suite 29-51 s across three runs. - -[cols="3,1",options="header"] -|=== -| Test | Wall time -| `stress_concurrent_multiple_instances` | 0.6 s -| `stress_concurrent_no_corruption` | 0.2 s -| `stress_deep_nesting_1000_levels` | 0.5 s -| `stress_deep_nesting_no_stack_overflow` | 0.7 s -| `stress_history_memory_efficiency` | 0.5 s -| `stress_large_file_1gb` | 1.8 s -| `stress_large_file_undo_streaming` | 12.6 s -| `stress_many_operations_10000` | 2.3 s -| `stress_many_small_files` | 1.2 s -| `stress_resource_limits_max_history` | 10-32 s -| `stress_undo_redo_efficiency` | 0.2 s -|=== - -Still open: - -* *Undo data is not streamed.* `rm` reads the whole file into - `undo_data`, and the journal stores those bytes as a JSON number array - (about 3 bytes per byte). Removing a 100 MB file takes about 11.5 s in a - debug build and writes about 300 MB of state. The test name promises - streaming; the test comment now says it is not implemented. The fix is - out-of-line undo storage (for example, renaming the file into a store - under the root), which changes the reversibility implementation, so it is - left for the owner. -* *History trimming is O(limit) per operation.* At the cap, each new - operation drains the oldest entry from the front of a `Vec`, moving about - 1.2 MB at the default 10,000 limit. That is about 7 s of the 100,000-op - test. A `VecDeque` would remove it but changes the public - `ShellState::history` type that tests and `CLAUDE.md` document as a `Vec`. -* *macOS.* The suite is not run there: `PATH_MAX` is 1024, so the - 1,000-level test cannot pass with absolute paths, and the rest was not - measured on macOS. -* Neither the journal nor the snapshot is `fsync`ed (the old `fs::write` - was not either), and they still live in the session root. Both are now - created with mode 0600 on Unix, since history can hold deleted file - contents (Codex review on #229). Route plan items E1d and G2 - (`docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc`) still cover fsync and moving - state out of the root; the journal is a new file they must include. +Update 2026-11-17: a repair was drafted on #229 and then moved to its own +pull request (owner ruling 2026-11-17). It replaced whole-file state saves +with an append-only journal, and review found the journal's crash handling +unsound in ways point fixes did not close. The suite and the CI step are +therefore unchanged here; the repair returns with the journal redesign. diff --git a/impl/rust-cli/src/commands.rs b/impl/rust-cli/src/commands.rs index cd9f879c..4f91625d 100644 --- a/impl/rust-cli/src/commands.rs +++ b/impl/rust-cli/src/commands.rs @@ -860,11 +860,11 @@ pub fn undo(state: &mut ShellState, count: usize, verbose: bool) -> Result<()> { fs::remove_file(&path).context("Undo touch failed")?; } OperationType::CreateFile => { - let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); + let content = op.undo_data.as_ref().cloned().unwrap_or_default(); fs::write(&path, content).context("Undo rm failed")?; } OperationType::WriteFile => { - let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); + let content = op.undo_data.as_ref().cloned().unwrap_or_default(); fs::write(&path, content).context("Undo write failed")?; } OperationType::FileAppended => { @@ -1364,11 +1364,11 @@ pub fn rollback_transaction(state: &mut ShellState) -> Result<()> { fs::remove_file(&path).context("Failed to remove file") } OperationType::CreateFile => { - let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); + let content = op.undo_data.as_ref().cloned().unwrap_or_default(); fs::write(&path, content).context("Failed to restore file") } OperationType::WriteFile => { - let content: &[u8] = op.undo_data.as_deref().unwrap_or_default(); + let content = op.undo_data.as_ref().cloned().unwrap_or_default(); fs::write(&path, content).context("Failed to restore file content") } OperationType::FileAppended => { @@ -1521,8 +1521,8 @@ pub fn rollback_transaction(state: &mut ShellState) -> Result<()> { } } - // Clear the transaction (and persist that it is gone) - state.abort_transaction(); + // Clear the transaction + state.active_transaction = None; // Report results if failed_rollbacks.is_empty() { diff --git a/impl/rust-cli/src/executable.rs b/impl/rust-cli/src/executable.rs index 698df7f4..aeb72a25 100644 --- a/impl/rust-cli/src/executable.rs +++ b/impl/rust-cli/src/executable.rs @@ -402,7 +402,7 @@ impl ExecutableCommand for Command { } // Store current directory as previous before changing - state.set_previous_dir(state.root.clone()); + state.previous_dir = Some(state.root.clone()); // Change the shell's working directory std::env::set_current_dir(&target)?; diff --git a/impl/rust-cli/src/state.rs b/impl/rust-cli/src/state.rs index 0f311444..7f75389b 100644 --- a/impl/rust-cli/src/state.rs +++ b/impl/rust-cli/src/state.rs @@ -278,46 +278,9 @@ pub struct ShellState { /// Completed transactions pub transactions: Vec, - /// State file path for persistence (the snapshot) + /// State file path for persistence state_file: PathBuf, - /// Append-only journal of the history mutations made since the last - /// snapshot. - /// - /// Rewriting the whole snapshot on every operation made each operation - /// cost O(history length), so a session of n operations cost O(n²) in - /// serialisation and disk writes. Hot-path mutations (record, mark-undone, - /// trim) are appended here in O(1); the snapshot is rewritten only when - /// the journal outgrows it (amortised O(1) per operation) or at the rare - /// transaction boundaries. - journal_file: PathBuf, - - /// Sequence number of the last journal entry written or replayed. - /// Each snapshot records it, so replay skips entries already folded in. - journal_seq: u64, - - /// Journal entries written or replayed since the last snapshot. - journal_entries: usize, - - /// Indices of a contiguous block of `history` known to be all undone. - /// - /// Repeated single-step undo used to rescan every already-undone - /// operation at the end of the history (twice: to pick the next target - /// and to mark it), so undoing n operations one at a time cost O(n²). - /// Undo skips this block instead. It is a hint: it is checked before - /// use and an empty range means "no hint". - undone_run: std::ops::Range, - - /// A journal append failed (possibly leaving a torn line), so the next - /// persist must write a full snapshot rather than append. - snapshot_pending: bool, - - /// Size in bytes the journal file should have on disk. If the file is - /// removed, moved or rewritten from inside the shell (it lives in the - /// command root), appending would leave a sequence gap that discards the - /// whole history on reload, so a mismatch forces a full snapshot. - journal_len: u64, - /// Last exit code from external command (for $? support) pub last_exit_code: i32, @@ -374,7 +337,6 @@ impl ShellState { let root_path = fs::canonicalize(&root_path).context("Failed to canonicalize sandbox root")?; let state_file = root_path.join(".vsh_state.json"); - let journal_file = root_path.join(".vsh_state.journal"); let mut state = Self { root: root_path, @@ -383,12 +345,6 @@ impl ShellState { active_transaction: None, transactions: Vec::new(), state_file, - journal_file, - journal_seq: 0, - journal_entries: 0, - undone_run: 0..0, - snapshot_pending: false, - journal_len: 0, last_exit_code: 0, previous_dir: None, variables: HashMap::new(), @@ -421,13 +377,13 @@ impl ShellState { self.history.push(op); // Enforce history size limit - let trimmed = self.enforce_history_limit(); + self.enforce_history_limit(); // Clear redo stack when new operation is performed self.redo_stack.clear(); // Persist state - warn on failure but don't abort - if let Err(e) = self.persist_recorded(trimmed) { + if let Err(e) = self.save() { eprintln!("{} Failed to save state: {}", "Warning:".bright_yellow(), e); eprintln!("Operation succeeded but may not persist across restarts"); } @@ -444,10 +400,10 @@ impl ShellState { } self.history.push(op); - let trimmed = self.enforce_history_limit(); + self.enforce_history_limit(); // Persist state - warn on failure but don't abort - if let Err(e) = self.persist_recorded(trimmed) { + if let Err(e) = self.save() { eprintln!("{} Failed to save state: {}", "Warning:".bright_yellow(), e); eprintln!("Redo succeeded but may not persist across restarts"); } @@ -457,8 +413,7 @@ impl ShellState { /// /// When history exceeds max_history_size, removes the oldest operations. /// If history_archive_path is set, saves removed operations to archive. - /// Returns the number of operations removed. - fn enforce_history_limit(&mut self) -> usize { + fn enforce_history_limit(&mut self) { if let Some(limit) = self.max_history_size { if self.history.len() > limit { let excess = self.history.len() - limit; @@ -477,14 +432,11 @@ impl ShellState { // Remove oldest operations self.history.drain(0..excess); - self.shift_undone_run(excess); // Note: This means undo can only go back `limit` operations // Users should be aware via configuration - return excess; } } - 0 } /// Archive operations to disk for later reference @@ -514,103 +466,26 @@ impl ShellState { /// Get the last N undoable operations pub fn last_n_undoable(&self, n: usize) -> Vec<&Operation> { - self.undoable_indices_rev() + self.history + .iter() + .rev() + .filter(|op| !op.undone) .take(n) - .map(|i| &self.history[i]) .collect() } - /// Indices of operations not yet undone, newest first, skipping the - /// known-undone block instead of rescanning it. - fn undoable_indices_rev(&self) -> impl Iterator + '_ { - let run = self.checked_undone_run(); - let mut next = self.history.len(); - std::iter::from_fn(move || { - while next > 0 { - next -= 1; - if next + 1 == run.end { - next = run.start; - continue; - } - if !self.history[next].undone { - return Some(next); - } - } - None - }) - } - - /// The undone-block hint, or an empty range if it does not hold. - fn checked_undone_run(&self) -> std::ops::Range { - let run = self.undone_run.clone(); - let holds = !run.is_empty() - && run.end <= self.history.len() - && self.history[run.start].undone - && self.history[run.end - 1].undone; - if holds { - run - } else { - 0..0 - } - } - - /// Record that `history[index]` is now undone in the block hint. - fn extend_undone_run(&mut self, index: usize) { - let run = self.checked_undone_run(); - self.undone_run = if run.is_empty() { - index..index + 1 - } else if index + 1 == run.start { - index..run.end - } else if index == run.end { - run.start..index + 1 - } else if run.contains(&index) { - run - } else { - index..index + 1 - }; - } - - /// Keep the block hint aligned after the oldest `removed` operations - /// were dropped from the front of the history. - fn shift_undone_run(&mut self, removed: usize) { - let start = self.undone_run.start.saturating_sub(removed); - let end = self.undone_run.end.saturating_sub(removed); - self.undone_run = start..end; - } - /// Mark an operation as undone pub fn mark_undone(&mut self, op_id: Uuid, undone_by: Uuid) { - // Undo targets the newest operations that are not yet undone, so look - // there first; fall back to a full scan for any other id. - let index = self - .undoable_indices_rev() - .find(|&i| self.history[i].id == op_id) - .or_else(|| self.history.iter().rposition(|o| o.id == op_id)); - - let found = match index { - Some(i) => { - let op = &mut self.history[i]; - op.undone = true; - op.undone_by = Some(undone_by); - - // Push to redo stack - self.redo_stack.push_front(op.clone()); - self.extend_undone_run(i); - true - } - None => false, - }; + if let Some(op) = self.history.iter_mut().find(|o| o.id == op_id) { + op.undone = true; + op.undone_by = Some(undone_by); + + // Push to redo stack + self.redo_stack.push_front(op.clone()); + } // Persist state - warn on failure - let persisted = if found { - self.persist_entries(&[JournalEntryRef::Undone { - id: op_id, - undone_by, - }]) - } else { - Ok(()) - }; - if let Err(e) = persisted { + if let Err(e) = self.save() { eprintln!( "{} Failed to save undo state: {}", "Warning:".bright_yellow(), @@ -671,36 +546,6 @@ impl ShellState { Ok(()) } - /// Set the directory `cd -` returns to, and journal it so it survives a - /// restart without waiting for the next snapshot. - pub fn set_previous_dir(&mut self, dir: PathBuf) { - self.previous_dir = Some(dir); - let persisted = - self.persist_entries(&[JournalEntryRef::PreviousDir(self.previous_dir.clone())]); - if let Err(e) = persisted { - eprintln!( - "{} Failed to save previous directory: {}", - "Warning:".bright_yellow(), - e - ); - } - } - - /// Drop the active transaction without committing it (after a rollback) - /// and persist that, so a restart does not resurrect it. - pub fn abort_transaction(&mut self) { - self.active_transaction = None; - - // Persist state - warn on failure - if let Err(e) = self.save() { - eprintln!( - "{} Failed to save transaction rollback: {}", - "Warning:".bright_yellow(), - e - ); - } - } - /// Get operations in current transaction pub fn current_transaction_ops(&self) -> Vec<&Operation> { match &self.active_transaction { @@ -739,209 +584,38 @@ impl ShellState { self.redo_stack.pop_front() } - /// Persist the operation just pushed by `record_operation` or - /// `record_redo_operation`, plus the history trim it caused. - fn persist_recorded(&mut self, trimmed: usize) -> Result<()> { - if self.journal_due_for_snapshot() { - return self.save(); - } - // With `max_history_size == Some(0)` the operation is trimmed at once - // and there is nothing to journal; fall back to a snapshot. - let Some(op) = self.history.last() else { - return self.save(); + /// Save state to file + fn save(&self) -> Result<()> { + let state = SerializableState { + history: self.history.clone(), + transactions: self.transactions.clone(), + active_transaction: self.active_transaction.clone(), + previous_dir: self.previous_dir.clone(), }; - // The record and its trim are one line, so a crash cannot persist the - // new operation without the history-limit trim it caused. - let entries = [JournalEntryRef::Record { op, trim: trimmed }]; - let appended = append_journal(&self.journal_file, self.journal_seq, &entries); - self.after_append(appended, entries.len()) - } - /// Persist journal entries that do not borrow from `self`. - fn persist_entries(&mut self, entries: &[JournalEntryRef<'_>]) -> Result<()> { - if self.journal_due_for_snapshot() { - return self.save(); - } - let appended = append_journal(&self.journal_file, self.journal_seq, entries); - self.after_append(appended, entries.len()) - } - - /// Account for a journal append of `count` entries. A failed append may - /// have left a torn line, which ends replay, so the next persist writes a - /// full snapshot (and empties the journal) instead of appending after it. - fn after_append(&mut self, appended: Result<()>, count: usize) -> Result<()> { - if appended.is_err() { - self.snapshot_pending = true; - } else { - self.journal_seq += count as u64; - self.journal_entries += count; - self.journal_len = fs::metadata(&self.journal_file).map_or(0, |m| m.len()); - } - appended - } - - /// Whether the files on disk are still the ones this state wrote: the - /// journal has the expected size, and the snapshot the journal builds on - /// still exists. Either can be removed or moved by a command, since both - /// live in the command root. - fn persistence_intact(&self) -> bool { - let journal_len = fs::metadata(&self.journal_file).map_or(0, |m| m.len()); - let snapshot_seq = self.journal_seq - self.journal_entries as u64; - journal_len == self.journal_len && (snapshot_seq == 0 || self.state_file.exists()) - } - - /// The journal is folded into a fresh snapshot once it holds at least - /// half as many entries as the history has operations (and at least - /// `JOURNAL_MIN_ENTRIES`). A snapshot costs O(history length), which is - /// then at most twice the number of entries it absorbs, so persistence - /// stays amortised O(1) per operation. - fn journal_due_for_snapshot(&self) -> bool { - self.snapshot_pending - || (self.journal_entries >= JOURNAL_MIN_ENTRIES - && 2 * self.journal_entries >= self.history.len()) - || !self.persistence_intact() - } - - /// Write a full snapshot and empty the journal. - /// - /// The snapshot is written to a temporary file and renamed over the old - /// one, so a crash leaves either the old or the new snapshot. It records - /// the journal sequence number it includes, so a crash between the rename - /// and the journal truncation cannot replay entries twice. - fn save(&mut self) -> Result<()> { - let saved = self.write_snapshot(); - // Transaction boundaries are only recorded by a snapshot, so a failed - // one must be retried before anything is appended to the journal. - if saved.is_err() { - self.snapshot_pending = true; - } - saved - } - - fn write_snapshot(&mut self) -> Result<()> { - use std::io::Write; - - let state = SerializableStateRef { - history: &self.history, - transactions: &self.transactions, - active_transaction: self.active_transaction.as_ref(), - previous_dir: self.previous_dir.as_ref(), - journal_seq: self.journal_seq, - }; - - let file_name = format!(".vsh_state.json.{}.tmp", Uuid::new_v4().simple()); - let tmp = self.state_file.with_file_name(file_name); - let written = (|| -> Result<()> { - let mut out = std::io::BufWriter::new(create_private(&tmp)?); - serde_json::to_writer(&mut out, &state)?; - out.flush()?; - fs::rename(&tmp, &self.state_file)?; - Ok(()) - })(); - if written.is_err() { - let _ = fs::remove_file(&tmp); - } - written?; - - // Everything journalled so far is now in the snapshot. - if self.journal_file.exists() { - fs::OpenOptions::new() - .write(true) - .open(&self.journal_file)? - .set_len(0)?; - } - self.journal_entries = 0; - self.journal_len = 0; - self.snapshot_pending = false; + let json = serde_json::to_string_pretty(&state)?; + fs::write(&self.state_file, json)?; Ok(()) } - /// Load state from the snapshot, then replay the journal on top of it. + /// Load state from file fn load(&mut self) -> Result<()> { - if self.state_file.exists() { - let json = crate::fs_pure::read_to_string(&self.state_file)?; - let state: SerializableState = serde_json::from_str(&json)?; - - self.history = state.history; - self.transactions = state.transactions; - self.active_transaction = state.active_transaction; - self.previous_dir = state.previous_dir; - self.journal_seq = state.journal_seq; + if !self.state_file.exists() { + return Ok(()); } - if self.journal_file.exists() { - // Read bytes, not a string: a crash can tear the last line inside - // a multi-byte character, and that must count as a torn line - // rather than make the whole file unreadable. - let journal = crate::fs_pure::read_to_end(&self.journal_file)?; - self.journal_len = journal.len() as u64; - let body = journal.strip_suffix(b"\n").unwrap_or(&journal); - // A last line with no newline may parse, but the next append - // would be glued onto it (`}{`), losing both lines on the - // following reload. Treat it like a torn tail: keep what parses, - // then snapshot before appending again. - let mut replayed_all = journal.is_empty() || journal.ends_with(b"\n"); - for line in body.split(|&b| b == b'\n').filter(|_| !body.is_empty()) { - // A torn line (crash mid-append) ends the replay, and so does - // a sequence gap: replay keeps the longest consistent prefix. - let Ok(JournalLine { seq, entry }) = serde_json::from_slice::(line) - else { - replayed_all = false; - break; - }; - if seq <= self.journal_seq { - continue; // already folded into the snapshot - } - if seq != self.journal_seq + 1 { - replayed_all = false; - break; - } - self.replay(entry); - self.journal_seq = seq; - self.journal_entries += 1; - } - // Entries appended after a torn line or gap would be skipped by - // every later reload. Make the next persist write a full snapshot, - // which also truncates the journal, instead of appending. - if !replayed_all { - self.snapshot_pending = true; - } - } + let json = crate::fs_pure::read_to_string(&self.state_file)?; + let state: SerializableState = serde_json::from_str(&json)?; - // The history was replaced wholesale; drop the undone-block hint. - self.undone_run = 0..0; + self.history = state.history; + self.transactions = state.transactions; + self.active_transaction = state.active_transaction; + self.previous_dir = state.previous_dir; Ok(()) } - /// Apply one journal entry to the in-memory history. Mirrors what the - /// live mutation did, minus side effects (archiving, redo stack, I/O); - /// the redo stack is not persisted, as before. - fn replay(&mut self, entry: JournalEntry) { - match entry { - JournalEntry::Record { op, trim } => { - if let Some(txn) = self.active_transaction.as_mut() { - if op.transaction_id == Some(txn.id) { - txn.operations.push(op.id); - } - } - self.history.push(op); - let trim = trim.min(self.history.len()); - self.history.drain(0..trim); - } - JournalEntry::Undone { id, undone_by } => { - if let Some(op) = self.history.iter_mut().rev().find(|o| o.id == id) { - op.undone = true; - op.undone_by = Some(undone_by); - } - } - JournalEntry::PreviousDir(dir) => { - self.previous_dir = dir; - } - } - } - // ========================================================================= // Variable Management // ========================================================================= @@ -1235,104 +909,13 @@ impl ShellState { } } -#[derive(Deserialize)] +#[derive(Serialize, Deserialize)] struct SerializableState { history: Vec, transactions: Vec, active_transaction: Option, #[serde(default)] previous_dir: Option, - /// Last journal sequence number folded into this snapshot (0 for - /// snapshots written before the journal existed). - #[serde(default)] - journal_seq: u64, -} - -/// Borrowing twin of [`SerializableState`], so a snapshot does not clone the -/// whole history first. -#[derive(Serialize)] -struct SerializableStateRef<'a> { - history: &'a [Operation], - transactions: &'a [Transaction], - active_transaction: Option<&'a Transaction>, - previous_dir: Option<&'a PathBuf>, - journal_seq: u64, -} - -/// Minimum journal length before it is folded into a snapshot. -const JOURNAL_MIN_ENTRIES: usize = 1024; - -/// One history mutation in the journal (`.vsh_state.journal`, JSON lines). -#[derive(Deserialize)] -enum JournalEntry { - /// An operation appended to the history, then the oldest `trim` - /// operations dropped by the history size limit (0 when under it). - Record { - op: Operation, - #[serde(default)] - trim: usize, - }, - /// An operation marked undone. - Undone { id: Uuid, undone_by: Uuid }, - /// The directory `cd -` returns to, as set by `cd`. - PreviousDir(Option), -} - -/// Borrowing twin of [`JournalEntry`]; serialises to the same shape. -#[derive(Serialize)] -enum JournalEntryRef<'a> { - Record { op: &'a Operation, trim: usize }, - Undone { id: Uuid, undone_by: Uuid }, - PreviousDir(Option), -} - -/// Create (or truncate) a persistence file readable only by its owner. -/// History can hold the contents of deleted files in `undo_data`, so the -/// journal and snapshot must not inherit a permissive umask. -fn create_private(path: &Path) -> std::io::Result { - let mut options = fs::OpenOptions::new(); - options.write(true).create(true).truncate(true); - #[cfg(unix)] - { - use std::os::unix::fs::OpenOptionsExt; - options.mode(0o600); - } - options.open(path) -} - -#[derive(Deserialize)] -struct JournalLine { - seq: u64, - entry: JournalEntry, -} - -#[derive(Serialize)] -struct JournalLineRef<'a, 'b> { - seq: u64, - entry: &'b JournalEntryRef<'a>, -} - -/// Append `entries` to the journal as JSON lines numbered from -/// `last_seq + 1`. Lines are streamed to the file rather than built in memory -/// first, since a `Record` can carry a large `undo_data` payload; small -/// entries still reach the file in a single write. -fn append_journal(path: &Path, last_seq: u64, entries: &[JournalEntryRef<'_>]) -> Result<()> { - use std::io::Write; - let mut options = fs::OpenOptions::new(); - options.create(true).append(true); - #[cfg(unix)] - { - use std::os::unix::fs::OpenOptionsExt; - options.mode(0o600); // see create_private - } - let file = options.open(path)?; - let mut out = std::io::BufWriter::with_capacity(64 * 1024, file); - for (seq, entry) in (last_seq + 1..).zip(entries) { - serde_json::to_writer(&mut out, &JournalLineRef { seq, entry })?; - out.write_all(b"\n")?; - } - out.flush()?; - Ok(()) } /// Resolve `path` against the sandbox `root`, clamping any `..` traversal so @@ -1740,355 +1323,4 @@ mod tests { fn test_chown_display() { assert_eq!(format!("{}", OperationType::Chown), "chown"); } - - // ======================================================================== - // Persistence: snapshot + journal - // ======================================================================== - - fn persisted_root() -> tempfile::TempDir { - tempfile::TempDir::new().unwrap() - } - - fn reopen(root: &tempfile::TempDir) -> ShellState { - ShellState::new(root.path().to_str().unwrap()).unwrap() - } - - fn record(state: &mut ShellState, path: &str) -> Uuid { - let op = Operation::new(OperationType::CreateFile, path.to_string(), None); - let id = op.id; - state.record_operation(op); - id - } - - fn summary(state: &ShellState) -> Vec<(Uuid, bool, Option)> { - state - .history - .iter() - .map(|op| (op.id, op.undone, op.undone_by)) - .collect() - } - - #[test] - fn test_journal_replay_restores_history_and_undo_marks() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - let b = record(&mut state, "b"); - record(&mut state, "c"); - state.mark_undone(b, Uuid::new_v4()); - - // Hot-path operations only append to the journal. - assert!(state.journal_file.exists()); - assert!(!state.state_file.exists()); - - let reloaded = reopen(&root); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_journal_folds_into_snapshot_and_reloads() { - let root = persisted_root(); - let mut state = reopen(&root); - for i in 0..(JOURNAL_MIN_ENTRIES + 10) { - record(&mut state, &format!("f{i}")); - } - assert!(state.state_file.exists(), "journal should have compacted"); - assert!(state.journal_entries < JOURNAL_MIN_ENTRIES); - - let reloaded = reopen(&root); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_journal_replays_history_trim() { - let root = persisted_root(); - let mut state = reopen(&root); - state.max_history_size = Some(3); - for i in 0..5 { - record(&mut state, &format!("f{i}")); - } - assert_eq!(state.history.len(), 3); - - // The reopened state has the default (larger) limit, so the trim must - // come from the journal, not from re-applying a limit. - let reloaded = reopen(&root); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_journal_torn_tail_is_ignored() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - record(&mut state, "b"); - { - use std::io::Write; - let mut journal = fs::OpenOptions::new() - .append(true) - .open(&state.journal_file) - .unwrap(); - journal.write_all(b"{\"seq\":3,\"entry\":{\"Rec").unwrap(); - } - - let reloaded = reopen(&root); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_operations_after_torn_tail_survive_reload() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - { - use std::io::Write; - let mut journal = fs::OpenOptions::new() - .append(true) - .open(&state.journal_file) - .unwrap(); - journal.write_all(b"{\"seq\":2,\"entry\":{\"Rec").unwrap(); - } - - // The restarted shell keeps working after the crash... - let mut restarted = reopen(&root); - record(&mut restarted, "b"); - record(&mut restarted, "c"); - - // ...and those later operations must not hide behind the torn line. - let reloaded = reopen(&root); - assert_eq!(reloaded.history.len(), 3); - assert_eq!(summary(&reloaded), summary(&restarted)); - } - - #[test] - fn test_removed_journal_is_rebuilt_not_gapped() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - record(&mut state, "b"); - // e.g. `rm .vsh_state.journal` from inside the shell. - fs::remove_file(&state.journal_file).unwrap(); - record(&mut state, "c"); - - let reloaded = reopen(&root); - assert_eq!(reloaded.history.len(), 3); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_removed_snapshot_is_rebuilt_not_gapped() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - state.save().unwrap(); - record(&mut state, "b"); - fs::remove_file(&state.state_file).unwrap(); - record(&mut state, "c"); - - let reloaded = reopen(&root); - assert_eq!(reloaded.history.len(), 3); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_failed_snapshot_is_retried_before_appending() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - // A directory in the snapshot's place makes the rename fail. - fs::create_dir(&state.state_file).unwrap(); - assert!(state.save().is_err()); - assert!(state.snapshot_pending); - - fs::remove_dir(&state.state_file).unwrap(); - record(&mut state, "b"); - assert!(state.state_file.is_file(), "the next persist must snapshot"); - assert!(!state.snapshot_pending); - } - - #[test] - fn test_journal_without_final_newline_is_repaired() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - // Crash after the last record but before its newline. - let journal = fs::read(&state.journal_file).unwrap(); - fs::write(&state.journal_file, journal.strip_suffix(b"\n").unwrap()).unwrap(); - - let mut restarted = reopen(&root); - assert_eq!(restarted.history.len(), 1, "the complete record is kept"); - record(&mut restarted, "b"); - - let reloaded = reopen(&root); - assert_eq!(reloaded.history.len(), 2); - assert_eq!(summary(&reloaded), summary(&restarted)); - } - - #[test] - fn test_record_and_trim_share_one_journal_line() { - let root = persisted_root(); - let mut state = reopen(&root); - state.max_history_size = Some(3); - for i in 0..5 { - record(&mut state, &format!("f{i}")); - } - let journal = fs::read_to_string(&state.journal_file).unwrap(); - // One line per operation: no trim can be split from its record. - assert_eq!(journal.lines().count(), 5); - assert!(journal.lines().last().unwrap().contains("\"trim\":1")); - } - - #[cfg(unix)] - #[test] - fn test_persistence_files_are_private() { - use std::os::unix::fs::PermissionsExt; - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - state.save().unwrap(); - record(&mut state, "b"); - for file in [&state.journal_file, &state.state_file] { - let mode = fs::metadata(file).unwrap().permissions().mode() & 0o777; - assert_eq!(mode, 0o600, "{}", file.display()); - } - } - - #[test] - fn test_journal_torn_inside_multibyte_char_reopens() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - { - use std::io::Write; - let mut journal = fs::OpenOptions::new() - .append(true) - .open(&state.journal_file) - .unwrap(); - // "é" is 0xC3 0xA9; stop after the first byte. - journal - .write_all(b"{\"seq\":2,\"entry\":{\"Record\":{\"path\":\"caf\xC3") - .unwrap(); - } - - let mut reopened = reopen(&root); - assert_eq!(summary(&reopened), summary(&state)); - record(&mut reopened, "b"); - let reloaded = reopen(&root); - assert_eq!(reloaded.history.len(), 2); - } - - #[test] - fn test_previous_dir_survives_reload_without_snapshot() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - state.set_previous_dir(PathBuf::from("/tmp/elsewhere")); - assert!(!state.state_file.exists(), "no snapshot should be needed"); - - let reloaded = reopen(&root); - assert_eq!( - reloaded.previous_dir.as_deref(), - Some(Path::new("/tmp/elsewhere")) - ); - } - - #[test] - fn test_snapshot_skips_already_folded_journal_entries() { - let root = persisted_root(); - let mut state = reopen(&root); - record(&mut state, "a"); - record(&mut state, "b"); - let stale_journal = fs::read(&state.journal_file).unwrap(); - - // Simulate a crash after the snapshot rename but before the journal - // was truncated: the journal still holds entries the snapshot has. - state.save().unwrap(); - fs::write(&state.journal_file, stale_journal).unwrap(); - - let reloaded = reopen(&root); - assert_eq!(summary(&reloaded), summary(&state)); - } - - #[test] - fn test_rolled_back_transaction_does_not_survive_reload() { - let root = persisted_root(); - let mut state = reopen(&root); - state.begin_transaction("t").unwrap(); - record(&mut state, "a"); - state.abort_transaction(); - - let reloaded = reopen(&root); - assert!(reloaded.active_transaction.is_none()); - assert_eq!(summary(&reloaded), summary(&state)); - } - - /// `last_n_undoable` must agree with a plain newest-first scan for - /// non-undone operations, whatever the undone-block hint holds. - fn assert_undoable_matches_scan(state: &ShellState) { - let naive: Vec = state - .history - .iter() - .rev() - .filter(|op| !op.undone) - .map(|op| op.id) - .collect(); - let fast: Vec = state - .last_n_undoable(usize::MAX) - .iter() - .map(|op| op.id) - .collect(); - assert_eq!(fast, naive); - } - - fn undo_one(state: &mut ShellState) { - let id = state.last_n_undoable(1)[0].id; - state.mark_undone(id, Uuid::new_v4()); - } - - #[test] - fn test_undone_block_hint_agrees_with_full_scan() { - let root = persisted_root(); - let mut state = reopen(&root); - state.max_history_size = Some(12); - for i in 0..10 { - record(&mut state, &format!("a{i}")); - } - for _ in 0..3 { - undo_one(&mut state); - assert_undoable_matches_scan(&state); - } - // New operations after an undone block, then undo across it. - for i in 0..4 { - record(&mut state, &format!("b{i}")); - assert_undoable_matches_scan(&state); - } - for _ in 0..6 { - undo_one(&mut state); - assert_undoable_matches_scan(&state); - } - // Out-of-order mark of an older operation. - let oldest_live = state.last_n_undoable(usize::MAX).last().unwrap().id; - state.mark_undone(oldest_live, Uuid::new_v4()); - assert_undoable_matches_scan(&state); - // Trims from the front shift the block. - for i in 0..8 { - record(&mut state, &format!("c{i}")); - assert_undoable_matches_scan(&state); - } - while !state.last_n_undoable(1).is_empty() { - undo_one(&mut state); - assert_undoable_matches_scan(&state); - } - } - - #[test] - fn test_transaction_membership_survives_journal_replay() { - let root = persisted_root(); - let mut state = reopen(&root); - state.begin_transaction("t").unwrap(); - let a = record(&mut state, "a"); - - let reloaded = reopen(&root); - let txn = reloaded.active_transaction.as_ref().unwrap(); - assert_eq!(txn.operations, vec![a]); - } } diff --git a/impl/rust-cli/tests/stress_tests.rs b/impl/rust-cli/tests/stress_tests.rs index c08912c1..34628f05 100644 --- a/impl/rust-cli/tests/stress_tests.rs +++ b/impl/rust-cli/tests/stress_tests.rs @@ -10,54 +10,17 @@ //! //! These tests validate that the shell remains stable, performant, //! and correct even under stress. -//! -//! All tests are `#[ignore]`d; CI runs them on Linux with -//! `cargo test --test stress_tests -- --ignored --test-threads=1` -//! (see `.github/workflows/compilation_tests.yml`). -//! -//! The shell keeps its persisted state in `.vsh_state.json` (snapshot) and -//! `.vsh_state.journal` inside the sandbox root, so directory listings below -//! account for those files explicitly. mod fixtures; use fixtures::tempfile::TempDir; use std::fs; use std::io::Write; -use std::path::Path; use std::sync::{Arc, Mutex}; use std::thread; use std::time::Instant; use vsh::state::ShellState; -/// Prefix shared by the shell's own state files in the sandbox root. -const STATE_FILE_PREFIX: &str = ".vsh_state"; - -/// Names of the entries in `dir` that are not the shell's own state files. -fn user_entries(dir: &Path) -> Vec { - let mut names: Vec = fs::read_dir(dir) - .unwrap() - .map(|e| e.unwrap().file_name().to_string_lossy().into_owned()) - .filter(|name| !name.starts_with(STATE_FILE_PREFIX)) - .collect(); - names.sort(); - names -} - -/// Total size in bytes of the shell's own state files in `dir`. -fn state_files_size(dir: &Path) -> u64 { - fs::read_dir(dir) - .unwrap() - .map(|e| e.unwrap()) - .filter(|e| { - e.file_name() - .to_string_lossy() - .starts_with(STATE_FILE_PREFIX) - }) - .map(|e| e.metadata().unwrap().len()) - .sum() -} - // ============================================================ // Stress Test 1: Deep Directory Nesting // ============================================================ @@ -65,59 +28,46 @@ fn state_files_size(dir: &Path) -> u64 { #[test] #[ignore] // Run with: cargo test --test stress_tests -- --ignored fn stress_deep_nesting_1000_levels() { - const DEPTH: usize = 1000; - let temp = TempDir::new().unwrap(); - let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - - // The shell resolves every path to an absolute one, so the deepest path - // must fit in PATH_MAX. One-character components ("d/d/.../d") cost two - // bytes per level: about 2,000 bytes plus the root, which fits Linux's - // 4096. (Ten-character names would need ~11,000 bytes, which no - // absolute-path API accepts; macOS's PATH_MAX of 1024 cannot hold 1000 - // levels at all.) - let deepest_len = state.root.as_os_str().len() + 2 * DEPTH; - let path_max = libc::PATH_MAX as usize; - assert!( - deepest_len < path_max, - "{DEPTH}-level nesting needs a {deepest_len}-byte absolute path; \ - this platform's PATH_MAX is {path_max}" - ); - - // Create the 1000-level structure through the shell, one level per op. let start = Instant::now(); - let mut rel = String::from("d"); - for level in 0..DEPTH { - if level > 0 { - rel.push_str("/d"); - } - vsh::commands::mkdir(&mut state, &rel, false).unwrap(); + + // Create 1000-level deep directory structure + let mut current_path = temp.path().to_path_buf(); + for i in 0..1000 { + current_path.push(format!("level_{:04}", i)); } + + // Create the entire nested structure + fs::create_dir_all(¤t_path).unwrap(); + let create_time = start.elapsed(); println!( "✓ Created 1000-level nested directories in {:?}", create_time ); - // Verify it exists and every level was recorded - let deepest = state.resolve_path(&rel); - assert!(deepest.exists()); - assert!(deepest.is_dir()); - assert_eq!(state.history.len(), DEPTH, "Each mkdir should be recorded"); + // Verify it exists + assert!(current_path.exists()); + assert!(current_path.is_dir()); - // Undo all 1000 operations (innermost first) + // Test undo (remove all levels) let undo_start = Instant::now(); - for _ in 0..DEPTH { + let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); + + // Record the creation in state + for i in 0..1000 { + let path = format!("level_{:04}", i); + vsh::commands::mkdir(&mut state, &path, true).unwrap(); + } + + // Undo all 1000 operations + for _ in 0..1000 { vsh::commands::undo(&mut state, 1, false).unwrap(); } + let undo_time = undo_start.elapsed(); println!("✓ Undid 1000 operations in {:?}", undo_time); - assert!( - user_entries(temp.path()).is_empty(), - "Undo should remove every level" - ); - // Verify requirements assert!(create_time.as_secs() < 5, "Should create in <5s"); assert!(undo_time.as_secs() < 2, "Should undo in <2s"); @@ -126,69 +76,30 @@ fn stress_deep_nesting_1000_levels() { #[test] #[ignore] fn stress_deep_nesting_no_stack_overflow() { - use nix::fcntl::{openat, OFlag}; - use nix::sys::stat::{mkdirat, Mode}; - use std::os::fd::OwnedFd; - - const DEPTH: usize = 5000; - let temp = TempDir::new().unwrap(); - let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Even deeper nesting (5000 levels) to test for stack overflow. Its - // absolute path is far longer than PATH_MAX, so it cannot be created - // with path-based calls (`fs::create_dir_all` fails with ENAMETOOLONG). - // Build it one level at a time relative to the parent's descriptor. - let deep_rel = vec!["d"; DEPTH].join("/"); - assert!( - state.root.join(&deep_rel).as_os_str().len() > libc::PATH_MAX as usize, - "this test is meant to go beyond PATH_MAX" - ); - let mut dir: OwnedFd = fs::File::open(&state.root).unwrap().into(); - for _ in 0..DEPTH { - mkdirat(&dir, "d", Mode::from_bits_truncate(0o755)).unwrap(); - dir = openat( - &dir, - "d", - OFlag::O_RDONLY | OFlag::O_DIRECTORY, - Mode::empty(), - ) - .unwrap(); + // Create even deeper nesting (5000 levels) to test for stack overflow + let mut current_path = temp.path().to_path_buf(); + for i in 0..5000 { + current_path.push(format!("d{}", i)); } - drop(dir); - - // The shell must stay stable when handed a path this deep: resolving it - // is pure normalisation, and filesystem operations on it fail with an - // error instead of overflowing the stack or panicking. - assert_eq!(state.resolve_path(&deep_rel), state.root.join(&deep_rel)); - let before = state.history.len(); - let mkdir_result = vsh::commands::mkdir(&mut state, &format!("{deep_rel}/x"), false); - assert!( - mkdir_result.is_err(), - "mkdir beyond PATH_MAX should fail cleanly" - ); - let touch_result = vsh::commands::touch(&mut state, &format!("{deep_rel}/f"), false); + + // Should not cause stack overflow + let result = fs::create_dir_all(¤t_path); assert!( - touch_result.is_err(), - "touch beyond PATH_MAX should fail cleanly" - ); - assert_eq!( - state.history.len(), - before, - "Failed operations must not be recorded" + result.is_ok(), + "Should handle 5000 levels without stack overflow" ); // Cleanup should also not overflow - let cleanup_result = fs::remove_dir_all(temp.path().join("d")); + let cleanup_result = fs::remove_dir_all(temp.path().join("d0")); assert!(cleanup_result.is_ok(), "Cleanup should not overflow"); - assert!(user_entries(temp.path()).is_empty()); } // ============================================================ // Stress Test 2: Large Files // ============================================================ -/// Writes 1 GB of temporary data to disk (about 1.5 s on a local SSD). #[test] #[ignore] fn stress_large_file_1gb() { @@ -208,69 +119,44 @@ fn stress_large_file_1gb() { file.write_all(&chunk).unwrap(); } file.sync_all().unwrap(); - drop(file); let create_time = start.elapsed(); println!("✓ Created 1GB file in {:?}", create_time); // Verify size - const SIZE: u64 = 1024 * 1024 * 1024; let metadata = fs::metadata(&large_file).unwrap(); - assert_eq!(metadata.len(), SIZE, "File should be exactly 1GB"); + assert_eq!( + metadata.len(), + 1024 * 1024 * 1024, + "File should be exactly 1GB" + ); // Test operations on large file let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Metadata-only operations must not depend on the file size. (`touch` - // in vsh only creates files, so it cannot be applied to this one; the - // reversible metadata operations are `chmod` and `mv`.) Each operation - // and its undo should be <100ms even for a 1GB file. - let timed = |label: &str, op: &mut dyn FnMut()| { - let t = Instant::now(); - op(); - let elapsed = t.elapsed(); - println!("✓ {label} on 1GB file in {elapsed:?}"); - assert!( - elapsed.as_millis() < 100, - "{label} should be <100ms even for large files (was {elapsed:?})" - ); - }; - - timed("chmod", &mut || { - vsh::commands::chmod(&mut state, "600", "large.bin", false).unwrap() - }); - timed("undo chmod", &mut || { - vsh::commands::undo(&mut state, 1, false).unwrap() - }); - timed("mv", &mut || { - vsh::commands::mv(&mut state, "large.bin", "moved.bin", false).unwrap() - }); - assert_eq!( - fs::metadata(temp.path().join("moved.bin")).unwrap().len(), - SIZE - ); - timed("undo mv", &mut || { - vsh::commands::undo(&mut state, 1, false).unwrap() - }); + // Touch shouldn't fail on large file (just updates metadata) + let touch_start = Instant::now(); + vsh::commands::touch(&mut state, "large.bin", true).unwrap(); + let touch_time = touch_start.elapsed(); + println!("✓ Touch on 1GB file in {:?}", touch_time); - // Memory usage check: should not load entire file into memory. - // These operations never read file content: the file is intact. - assert_eq!(fs::metadata(&large_file).unwrap().len(), SIZE); - assert_eq!( - metadata.permissions(), - fs::metadata(&large_file).unwrap().permissions() + assert!( + touch_time.as_millis() < 100, + "Touch should be <100ms even for large files" ); + + // Memory usage check: should not load entire file into memory + // This test would fail if implementation naively reads entire file } #[test] #[ignore] fn stress_large_file_undo_streaming() { - const SIZE: usize = 100 * 1024 * 1024; - let temp = TempDir::new().unwrap(); let file_path = temp.path().join("large.txt"); // Create 100MB file + let _size = 100 * 1024 * 1024; let mut file = fs::File::create(&file_path).unwrap(); let chunk = vec![b'A'; 1024 * 1024]; // 1MB chunks @@ -279,24 +165,19 @@ fn stress_large_file_undo_streaming() { } drop(file); + // Verify we don't OOM when saving undo data for large file let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // Removing a file is the operation that saves the file's content as undo - // data. (`touch` cannot be used here: in vsh it only creates files.) - // - // NOT streaming: `rm` currently holds the whole content in memory as - // `undo_data` and persists it in the state journal as JSON. This test - // checks that a 100MB rm/undo round trip completes, restores the content - // byte for byte, and that the undo itself stays fast. Out-of-line - // (streamed) undo storage is open work, recorded in - // docs/audits/2026-11-16-hypatia-remediation.adoc. + // This should use streaming, not load all 100MB into memory let undo_save_start = Instant::now(); - vsh::commands::rm(&mut state, "large.txt", false).unwrap(); + vsh::commands::touch(&mut state, "large.txt", true).unwrap(); let undo_save_time = undo_save_start.elapsed(); - assert!(!file_path.exists(), "rm should remove the file"); println!("✓ Saved undo data for 100MB file in {:?}", undo_save_time); + // Check memory didn't spike (we can't easily test this in Rust, + // but in practice this would be monitored externally) + // Undo should also be fast let undo_start = Instant::now(); vsh::commands::undo(&mut state, 1, false).unwrap(); @@ -304,14 +185,6 @@ fn stress_large_file_undo_streaming() { println!("✓ Undid large file operation in {:?}", undo_time); assert!(undo_time.as_millis() < 500, "Undo should be <500ms"); - - // The restored file must be the original, byte for byte. - let restored = fs::read(&file_path).unwrap(); - assert_eq!(restored.len(), SIZE, "Restored file should be 100MB"); - assert!( - restored.iter().all(|&b| b == b'A'), - "Restored content should match the original" - ); } // ============================================================ @@ -352,14 +225,9 @@ fn stress_many_operations_10000() { assert!(create_time.as_secs() < 30, "Should complete in <30s"); assert!(undo_time.as_secs() < 30, "Should undo in <30s"); - // Verify all files removed (only the shell's own state files remain) - let entries = user_entries(temp.path()); - assert!( - entries.is_empty(), - "All files should be undone, found {} (first: {:?})", - entries.len(), - entries.first() - ); + // Verify all files removed + let entries: Vec<_> = fs::read_dir(temp.path()).unwrap().collect(); + assert_eq!(entries.len(), 0, "All files should be undone"); } #[test] @@ -405,22 +273,13 @@ fn stress_undo_redo_efficiency() { vsh::commands::undo(&mut state, 1, false).unwrap(); } let undo_time = start.elapsed(); - assert!( - user_entries(temp.path()).is_empty(), - "Undo should remove all files" - ); // Redo should also be O(1) per operation let redo_start = Instant::now(); for _ in 0..100 { - vsh::commands::redo(&mut state, 1, false).unwrap(); + state.pop_redo().unwrap(); } let redo_time = redo_start.elapsed(); - assert_eq!( - user_entries(temp.path()).len(), - 100, - "Redo should recreate all files" - ); println!("✓ Undo 100: {:?}, Redo 100: {:?}", undo_time, redo_time); @@ -483,16 +342,9 @@ fn stress_concurrent_multiple_instances() { handle.join().unwrap(); } - // Verify total files created (10 threads * 100 files = 1000). The - // instances share one sandbox root, so its state files are there too; - // nothing else may be. - let entries = user_entries(&temp_path); + // Verify total files created (10 threads * 100 files = 1000) + let entries: Vec<_> = fs::read_dir(&temp_path).unwrap().collect(); assert_eq!(entries.len(), 1000, "Should have 1000 total files"); - let mut expected: Vec = (0..10) - .flat_map(|t| (0..100).map(move |i| format!("thread_{}_file_{}.txt", t, i))) - .collect(); - expected.sort(); - assert_eq!(entries, expected, "Exactly the threads' files should exist"); println!("✓ Concurrent access: 10 threads, 100 ops each = 1000 files"); } @@ -550,11 +402,8 @@ fn stress_resource_limits_max_history() { let temp = TempDir::new().unwrap(); let mut state = ShellState::new(temp.path().to_str().unwrap()).unwrap(); - // ShellState bounds its history (`max_history_size`, 10,000 by default); - // a user-facing setting for it remains tracked by #190. - let limit = state - .max_history_size - .expect("ShellState should bound its history by default"); + // Create operations until we hit a reasonable limit + // In practice, there should be a configurable max history size for i in 0..100_000 { let path = format!("file_{}.txt", i); @@ -563,30 +412,17 @@ fn stress_resource_limits_max_history() { // Every 10k operations, check if we have a limit if i % 10_000 == 0 { println!(" {} operations...", i); - assert!(state.history.len() <= limit); } } - // Even with 100k operations, should not OOM: the in-memory history is - // capped at the limit... + // Even with 100k operations, should not OOM + // (This test would be better with actual memory monitoring) + let history_size = state.history.len(); println!("✓ Completed {} operations without OOM", history_size); - assert_eq!( - history_size, limit, - "History should be capped at max_history_size" - ); - // ...and so is the persisted state, which must not grow with the total - // number of operations. A touch op serialises to ~200 bytes, so a - // snapshot plus journal of a capped history stays within a few MB; - // 32 MiB leaves ample headroom while catching unbounded growth (100k - // uncapped ops alone would exceed it). - let persisted = state_files_size(temp.path()); - println!("✓ Persisted state: {} bytes", persisted); - assert!( - persisted < 32 * 1024 * 1024, - "Persisted state should be bounded by the history limit (was {persisted} bytes)" - ); + // A configurable production history bound remains tracked by #190. + // assert!(history_size <= MAX_HISTORY_SIZE); } #[test] diff --git a/proofs/coq/README.adoc b/proofs/coq/README.adoc index 96f81216..941599b1 100644 --- a/proofs/coq/README.adoc +++ b/proofs/coq/README.adoc @@ -16,16 +16,18 @@ extraction. | `filesystem_model.v` | Core `Filesystem = Path -> option FSNode` model + structural lemmas. - Note: this finite-domain model is the source of the - `is_empty_dir_dec` axiom (justified per `[coq-proof-status] + Note: this finite-domain model is why `is_empty_dir_dec` + (`posix_errors.v`) is a theorem proved with classical logic + (`Classical.classic`), not a custom axiom; see `[coq-proof-status] axiom-detail` in the archived - `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`). + `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`. | `filesystem_composition.v` -| Composition theorems. Carries one declared `admit.` at line ~199 - (`single_op_reversible` OpRmdir branch — pre-existing model gap; - see `[coq-proof-status] admitted-detail` in the archived - `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`). +| Composition theorems. Contains no `admit.` or `Admitted.` markers: + the former `single_op_reversible` OpRmdir admit is closed with `Qed` + (see `[coq-proof-status] admitted-detail` in the archived + `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`, re-verified 2026-07-16 + under Coq 8.18.0). | `filesystem_equivalence.v` | State-equivalence relations. @@ -68,10 +70,10 @@ make all # via auto-emitted Makefile == Proof-debt status -* `admitted = 1` — `single_op_reversible` OpRmdir branch - (`filesystem_composition.v:199`). -* `axioms-justified = 1` — `is_empty_dir_dec` (infinite-domain - decidability; migration path: switch to `FMaps.t FSNode`). +* `admitted = 0` — no `admit.` or `Admitted.` marker in any `.v` file. +* One justified classical dependency: `is_empty_dir_dec`, a theorem + proved with `Classical.classic` (infinite-domain decidability; + migration path: switch to `FMaps.t FSNode`). No custom `Axiom`. * All other proofs constructively closed. Authoritative status in `../../docs/PROOF_HOLES_AUDIT.adoc` and the From 057be2c79d5d9bd59c103297cceb5ad32fcc9def Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:23:00 +0000 Subject: [PATCH 12/14] fix: one SPDX identifier in main.zig; Mustfile checks the archived files Two findings from the Codex review of ee5380e: - ffi/zig/src/main.zig already carried its SPDX identifier on line 6, so 86f32cf left the file with two. The older line is removed; the single identifier (MPL-2.0, unchanged) is on line 1 as the owner asked. The audit record said the file had no header, which was wrong, and is corrected. - repo-deed-present checked the deed, the ledger and the absence of 6a2/, but not the nine archived files that hold the retired fields verbatim. It now fails if any is missing (checked by removing one). Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- .machine_readable/contractiles/Mustfile.a2ml | 2 +- docs/audits/2026-11-16-hypatia-remediation.adoc | 2 +- ffi/zig/src/main.zig | 1 - 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.machine_readable/contractiles/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml index 6a62791d..3473b8ca 100644 --- a/.machine_readable/contractiles/Mustfile.a2ml +++ b/.machine_readable/contractiles/Mustfile.a2ml @@ -63,7 +63,7 @@ hooks fail if any check fails. ### repo-deed-present - description: The repo deed holds the descriptiles; the retired 6a2 A2ML files are archived (D312, D313) -- run: test -f valence-shell_chora.deed && test -f archive/a2ml-v1/MIGRATION-LEDGER.adoc && test ! -e .machine_readable/6a2 +- run: test -f valence-shell_chora.deed && test -f archive/a2ml-v1/MIGRATION-LEDGER.adoc && test ! -e .machine_readable/6a2 && for f in STATE.a2ml META.a2ml ECOSYSTEM.a2ml AGENTIC.a2ml NEUROSYM.a2ml PLAYBOOK.a2ml 0-AI-MANIFEST.a2ml anchor-ANCHOR.a2ml README.adoc; do test -f "archive/a2ml-v1/6a2-$f.txt" || exit 1; done - severity: critical ### self-validating-structure diff --git a/docs/audits/2026-11-16-hypatia-remediation.adoc b/docs/audits/2026-11-16-hypatia-remediation.adoc index 4619fa5c..2aace5c5 100644 --- a/docs/audits/2026-11-16-hypatia-remediation.adoc +++ b/docs/audits/2026-11-16-hypatia-remediation.adoc @@ -59,7 +59,7 @@ They close when the underlying alert closes. | RE005 | fixed | The ignored stress suite no longer runs under `continue-on-error` in `compilation_tests.yml`; see <>. | WH008 (3) | fixed | See the Secret Scanner section. | SD022 (2) | fixed | Both paths named another tree (`echidna/src/rust/`, the Agda tarball path `agda-2.7.0.1/src/data/lib`); now qualified. -| SD009 | left for the owner | `ffi/zig/src/main.zig` has no SPDX header. Licence edits are owner-only (estate doctrine 6). +| SD009 | fixed (owner-authorised, 2026-11-17) | `ffi/zig/src/main.zig` did have an SPDX identifier, on line 6 of its leading comment; the rule looks at line 1. The identifier (unchanged, `MPL-2.0`) now sits on line 1, and the file carries exactly one. An earlier entry here said the file had no header; that was wrong. | SD004 (6), SD007 | left for the owner | Moving `.machine_readable/6a2/` into deed clauses needs the estate converter (kyX, standards D312/D313); writing the clauses by hand would guess at metadata. | `known_fake_action_sha` (3), `download_then_run_shell` (1) in `alkahest-shell-transmuter/` | left for upstream | Owner ruling: fix the canonical alkahest repository, then re-sync this copy. These workflows never run here. |=== diff --git a/ffi/zig/src/main.zig b/ffi/zig/src/main.zig index 5de795e8..dac99a51 100644 --- a/ffi/zig/src/main.zig +++ b/ffi/zig/src/main.zig @@ -4,7 +4,6 @@ // This module implements the C-compatible FFI declared in src/abi/Foreign.idr // All types and layouts must match the Idris2 ABI definitions. // -// SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell const std = @import("std"); From 477d78b7178e56ec9d71ea724b96747ee70236d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:30:16 +0000 Subject: [PATCH 13/14] docs(roadmap): stop sending two tasks to retired A2ML files ROADMAP.adoc told contributors to add dogfooding data to STATE.a2ml and ADRs to META.a2ml. Both files are archived by the deed migration, and the Mustfile check requires .machine_readable/6a2 to stay absent, so neither task could be done as written (Codex review). The tasks stay, without the file names, marked 'target pending': the new home is an owner decision (ledger U-6, T-1), which this change does not make. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- ROADMAP.adoc | 13 +++++++++---- archive/a2ml-v1/MIGRATION-LEDGER.adoc | 2 +- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/ROADMAP.adoc b/ROADMAP.adoc index c42d486d..8946a61f 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -39,11 +39,16 @@ CI on `rust-cli.yml`, dogfood evidence, structural compliance. in the same PR. * [ ] Per-directory README coverage 23% → ~90% (17 subtrees missing, enumerated in the audit). -* [ ] Add `[dogfooding-status]` to STATE.a2ml with concrete daily-use - entries. -* [ ] Add 3+ ADRs to META.a2ml (proof stack: Agda source, Lean/Rocq rechecks, Rust as primary +* [ ] Record dogfooding status with concrete daily-use entries. + _Target pending:_ this item named `STATE.a2ml`, which is retired and + archived (2026-11-17). Do not edit the archive; the new home is an + owner decision (`archive/a2ml-v1/MIGRATION-LEDGER.adoc`, row U-6). +* [ ] Write 3+ ADRs (proof stack: Agda source, Lean/Rocq rechecks, Rust as primary implementation, property-testing as correspondence-gap mitigation) and - populate `[development-practices]`. + record the development practices. + _Target pending:_ this item named `META.a2ml`, which is retired and + archived. The canon's successor is `(adr …)` entries in the deed + (ledger rows U-6 and T-1); do not edit the archive. * [x] Resolved 2026-04-19: `impl/rust-ffi/` deleted; `ffi/rust/` is canonical (superset, includes `verification.rs`, matches CLAUDE.md ABI/FFI standard `ffi//`). 7 sibling files were byte-identical; diff --git a/archive/a2ml-v1/MIGRATION-LEDGER.adoc b/archive/a2ml-v1/MIGRATION-LEDGER.adoc index 190ea3b2..b71b3322 100644 --- a/archive/a2ml-v1/MIGRATION-LEDGER.adoc +++ b/archive/a2ml-v1/MIGRATION-LEDGER.adoc @@ -201,7 +201,7 @@ archive is verbatim and an SPDX edit is the owner's (owner input, row X-1). | U-3 | `docs/README.adoc` (two references) | Updated to the deed, `PROOF_HOLES_AUDIT.adoc` and the archived STATE. | U-4 | `proofs/coq/README.adoc` (three references) | Updated to the archived STATE and the live authorities. The file's own counts (`admitted = 1`) disagree with `docs/PROOF_HOLES_AUDIT.adoc` (0 admits); recorded, not corrected. | U-5 | `ROADMAP.adoc` "Current Status" | The path updated to the archived STATE. The "~74%" figure is left as written (S-4). -| U-6 | `ROADMAP.adoc` open items "Add `[dogfooding-status]` to STATE.a2ml" and "Add 3+ ADRs to META.a2ml" | Left as written (owner's roadmap). Both name retired files, which may no longer be written; the ADR target is now `(adr …)` entries (T-1). Owner input. +| U-6 | `ROADMAP.adoc` open items "Add `[dogfooding-status]` to STATE.a2ml" and "Add 3+ ADRs to META.a2ml" | Both named retired files. The tasks are kept, reworded to drop the file names and marked "target pending", so nobody is sent to edit an archive (Codex review on #229). Where dogfooding status lives, and when ADRs become `(adr …)` entries (T-1), is still owner input. | U-7 | `.machine_readable/bot_directives/README.adoc` | The `AGENTIC.a2ml` line now names the deed's `(agentic …)` clause. | U-8 | Dated records: `CHANGELOG.adoc` history, `docs/audits/*`, `docs/governance/CRG-AUDIT-2026-04-18.adoc`, `docs/reports/*` | Left as written. |=== From 1ed04b61bd2dc4e2fa39610637370ace072a218a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:38:52 +0000 Subject: [PATCH 14/14] docs(coq): name the three standard axioms the Coq proofs depend on The proof-debt summary said is_empty_dir_dec was the only classical dependency, proved with Classical.classic, and that all other proofs were constructive. Print Assumptions under Coq 8.18.0 shows: - is_empty_dir_dec: Classical_Prop.classic and ClassicalEpsilon.constructive_indefinite_description (it uses excluded_middle_informative); - mkdir_rmdir_reversible and single_op_reversible: FunctionalExtensionality.functional_extensionality_dep. The summary now lists all three and no longer calls the rest constructive. There is still no custom Axiom and no admit. Codex review on #229. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01J4QvDjNR1ZoYKEPxSKE2nq --- proofs/coq/README.adoc | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/proofs/coq/README.adoc b/proofs/coq/README.adoc index 941599b1..e521972c 100644 --- a/proofs/coq/README.adoc +++ b/proofs/coq/README.adoc @@ -16,11 +16,11 @@ extraction. | `filesystem_model.v` | Core `Filesystem = Path -> option FSNode` model + structural lemmas. - Note: this finite-domain model is why `is_empty_dir_dec` - (`posix_errors.v`) is a theorem proved with classical logic - (`Classical.classic`), not a custom axiom; see `[coq-proof-status] + Note: this function-based model is why `is_empty_dir_dec` + (`posix_errors.v`) is a theorem proved with classical logic, not a + custom axiom (see "Proof-debt status" below, and `[coq-proof-status] axiom-detail` in the archived - `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`. + `../../archive/a2ml-v1/6a2-STATE.a2ml.txt`). | `filesystem_composition.v` | Composition theorems. Contains no `admit.` or `Admitted.` markers: @@ -71,10 +71,19 @@ make all # via auto-emitted Makefile == Proof-debt status * `admitted = 0` — no `admit.` or `Admitted.` marker in any `.v` file. -* One justified classical dependency: `is_empty_dir_dec`, a theorem - proved with `Classical.classic` (infinite-domain decidability; - migration path: switch to `FMaps.t FSNode`). No custom `Axiom`. -* All other proofs constructively closed. +* No custom `Axiom`. The proofs do depend on three standard-library + axioms (`Print Assumptions`, Coq 8.18.0, re-run 2026-11-17): +** *Classical logic:* `is_empty_dir_dec` uses + `excluded_middle_informative`, so it depends on + `Classical_Prop.classic` and + `ClassicalEpsilon.constructive_indefinite_description` + (decidability over an infinite domain; migration path: switch to + `FMaps.t FSNode`). +** *Functional extensionality:* the reversibility theorems, for example + `mkdir_rmdir_reversible` and `single_op_reversible`, depend on + `FunctionalExtensionality.functional_extensionality_dep`, because a + filesystem is a function and they state equality of filesystems. +* So these proofs are not constructive, and are not axiom-free. Authoritative status in `../../docs/PROOF_HOLES_AUDIT.adoc` and the Proof Ledger of `../../EXPLAINME.adoc`. The former `[coq-proof-status]`