diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index c750a87..830aa0d 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -4,204 +4,40 @@ # This workflow is managed by gh actions-lock. # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# RSR Standard E2E + Aspect + Benchmark Workflow Template +# Conformance workflow (owner decision 2026-11-17, ADR-0003). # -# Covers ALL merge requirement test categories: -# - E2E (end-to-end pipeline tests) -# - Aspect (cross-cutting concern validation) -# - Benchmarks (performance regression detection) -# - Readiness (Component Readiness Grade: D/C/B) +# The required check is named after the highest conformance level the engine +# actually passes: `Conformance L0` today, later L1, L2, L3 as those levels +# exist (verification/conformance/README.adoc). There is no "E2E" job: it is +# retired until Scaffoldia can mint something end to end. The inherited +# Idris2/Zig harness tests/e2e.sh is no longer run here (docs/status/ROADMAP.adoc). # -# INSTRUCTIONS: Uncomment and customise the section matching your stack. -# Delete sections that don't apply. See examples in each job. +# The commands live in verification/conformance/check-l0.sh, which +# `just conformance` also calls. Needs cargo, rustc, jq and coreutils, all on a +# stock ubuntu-latest image. -name: E2E + Aspect + Bench +name: Conformance on: push: branches: [main, master, develop] - paths: - - 'src/**' - - 'ffi/**' - - 'tests/**' - - '.github/workflows/e2e.yml' + # No `paths:` filter on pull_request: a required check that is skipped by a + # path filter never reports, and the pull request would wait forever. pull_request: branches: [main, master] - paths: - - 'src/**' - - 'ffi/**' - - 'tests/**' workflow_dispatch: permissions: read-all concurrency: - group: e2e-${{ github.ref }} + group: conformance-${{ github.ref }} cancel-in-progress: true jobs: - # ─── Default: repo smoke (always runs — not a silent no-op) ───────── - # Runs the repo's own E2E harness (tests/e2e.sh). Downstream work either - # extends tests/e2e.sh or uncomments a stack block below. - e2e: - name: E2E — smoke + conformance-l0: + name: Conformance L0 runs-on: ubuntu-latest timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@v7.0.1 - - name: Run E2E harness + - name: Build kernel, check fixtures, run L0, run negative controls run: | - if [ -f tests/e2e.sh ]; then - bash tests/e2e.sh - else - echo "::notice::no tests/e2e.sh present — nothing to run" - fi - -# ─── End-to-End Tests (downstream stack-specific examples) ───────── -# Uncomment ONE of the following e2e job blocks matching your stack. - -## === RUST E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo build --release -# - run: bash tests/e2e.sh -# # OR: cargo test --test end_to_end -- --nocapture - -## === ZIG FFI E2E === -# e2e: -# name: E2E — FFI Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406 # v2.2.1 -# with: -# version: 0.15.1 -# - run: cd ffi/zig && zig build test -# - run: bash tests/e2e.sh - -## === ELIXIR E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.24.0 -# with: -# otp-version: '27.0' -# elixir-version: '1.17' -# - run: mix deps.get && mix compile --warnings-as-errors -# - run: mix test test/integration/e2e_test.exs --trace - -## === DENO/RESCRIPT E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4 -# with: -# deno-version: v2.x -# - run: deno install --node-modules-dir=auto -# - run: deno task res:build # ReScript compile -# - run: deno test tests/e2e/ - -## === PLAYWRIGHT (Browser E2E) === -# e2e-playwright: -# name: Playwright — ${{ matrix.project }} -# runs-on: ubuntu-latest -# timeout-minutes: 20 -# strategy: -# fail-fast: false -# matrix: -# project: [chromium-1080p, firefox-1080p, webkit-1080p] -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4 -# with: -# deno-version: v2.x -# - run: deno install --node-modules-dir=auto -# - run: npx playwright install --with-deps -# - run: npx playwright test --project=${{ matrix.project }} -# - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 -# if: failure() -# with: -# name: playwright-traces-${{ matrix.project }} -# path: test-results/**/trace.zip -# retention-days: 7 - -## === HASKELL E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: haskell-actions/setup@cd0d9bdd65b20557f41bea4dbe43d0b5fbbfe553 # v2.11.0 -# with: -# ghc-version: '9.6' -# cabal-version: '3.10' -# - run: cabal build all -# - run: bash tests/integration-test.sh - -# ─── Aspect Tests ────────────────────────────────────────────────── -# Cross-cutting concerns: thread safety, ABI contracts, SPDX, dangerous patterns -# Uncomment and customise: - -# aspect-tests: -# name: Aspect — Architectural Invariants -# runs-on: ubuntu-latest -# timeout-minutes: 10 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - run: bash tests/aspect_tests.sh - -# ─── Benchmarks ──────────────────────────────────────────────────── -# Performance regression detection. Uncomment matching stack: - -## === RUST BENCH === -# benchmarks: -# name: Bench — Performance Regression -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo bench 2>&1 | tee /tmp/bench-results.txt -# - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 -# if: always() -# with: -# name: benchmark-results -# path: /tmp/bench-results.txt -# retention-days: 30 - -## === ZIG BENCH === -# benchmarks: -# name: Bench — Performance Regression -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406 # v2.2.1 -# with: -# version: 0.15.1 -# - run: cd ffi/zig && zig build bench - -# ─── Readiness (CRG) ────────────────────────────────────────────── -# Component Readiness Grade: D (runs) → C (correct) → B (edge cases) - -# readiness: -# name: Readiness — Grade D/C/B -# runs-on: ubuntu-latest -# timeout-minutes: 10 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo test --test readiness -- --nocapture + set -euo pipefail + bash verification/conformance/check-l0.sh diff --git a/.gitignore b/.gitignore index 87e91e8..1d9d3e2 100644 --- a/.gitignore +++ b/.gitignore @@ -123,3 +123,7 @@ dist/ # ...but never track Idris2 typecheck output. `idris2 --typecheck src/interface/abi.ipkg` # writes compiled .ttc/.ttm under build/ttc/; these are generated artifacts. /build/ttc/ + +# Agda interface files (written when agda is run by hand; the plan-law gate +# checks a fresh copy and writes none here) +*.agdai diff --git a/Justfile b/Justfile index e9cd529..08cb85f 100644 --- a/Justfile +++ b/Justfile @@ -120,12 +120,10 @@ clean-all: clean # TEST & QUALITY # ═══════════════════════════════════════════════════════════════════════════════ -# Run all tests -test *args: - @echo "Running tests..." - idris2 --typecheck src/interface/abi.ipkg - cd src/interface/ffi && zig build test {{args}} - @echo "Tests passed!" +# Run the tests that gate this repository: the conformance suite at L0 +# (the CI check `Conformance L0`). The inherited Idris2/Zig seam is not +# covered; see test-verbose, test-smoke and docs/status/ROADMAP.adoc (P0). +test: conformance # Run tests with verbose output test-verbose: @@ -139,7 +137,8 @@ test-smoke: idris2 --typecheck src/interface/abi.ipkg cd src/interface/ffi && zig build -# Run end-to-end tests (full pipeline: build → run → verify) +# Inherited Idris2/Zig harness. NOT run by CI and not a gate (retired as a CI +# check 2026-11-17; docs/status/ROADMAP.adoc P0). Needs idris2 and zig. e2e: bash tests/e2e.sh @@ -173,10 +172,10 @@ crg-badge: esac; \ echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" -# Run the full merge-requirement test suite (ALL categories) -# Per STANDING rule: P2P + E2E + aspect + execution + lifecycle + bench -test-all: test e2e aspect bench - @echo "All test categories passed — safe to merge!" +# Run the local test categories that exist: conformance, aspect, bench. +# This is not the merge gate; the required CI check is `Conformance L0`. +test-all: test aspect bench + @echo "Local test categories passed." # Run all quality checks quality: fmt-check lint test @@ -665,6 +664,12 @@ help-me: import? "build/just/proofs.just" +# ═══════════════════════════════════════════════════════════════════════════════ +# PLAN KERNEL & CONFORMANCE SUITE — see build/just/conformance.just +# ═══════════════════════════════════════════════════════════════════════════════ + +import? "build/just/conformance.just" + # ═══════════════════════════════════════════════════════════════════════════════ # SESSION MANAGEMENT (THIN BINDINGS TO CENTRAL STANDARDS) # ═══════════════════════════════════════════════════════════════════════════════ diff --git a/build/just/conformance.just b/build/just/conformance.just new file mode 100644 index 0000000..0153d23 --- /dev/null +++ b/build/just/conformance.just @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# PLAN KERNEL & CONFORMANCE SUITE (ADR-0003) +# +# Imported by ../../Justfile via `import? "build/just/conformance.just"`. +# The suite is engine-neutral (verification/conformance/README.adoc); the +# Rust spike under src/kernel/ is one engine it is run against. Needs: cargo, +# bash, jq, coreutils. Run via `just conformance`. + +kernel_manifest := "src/kernel/Cargo.toml" + +# Build the plan kernel (release, locked dependencies) +kernel-build: + cargo build --release --locked --manifest-path {{kernel_manifest}} + +# Test, lint and format-check the plan kernel workspace +kernel-check: + cargo test --locked --manifest-path {{kernel_manifest}} + cargo clippy --locked --all-targets --manifest-path {{kernel_manifest}} -- -D warnings + cargo fmt --manifest-path {{kernel_manifest}} --all -- --check + +# Fixtures match their generator; kernel passes L0; every negative control fails +conformance: + verification/conformance/check-l0.sh diff --git a/build/just/proofs.just b/build/just/proofs.just index b124d7a..1cff563 100644 --- a/build/just/proofs.just +++ b/build/just/proofs.just @@ -9,7 +9,7 @@ # `just proof-check-all` for the full sweep. # Check all formal proofs (Idris2 + Lean4 + Agda + Coq) -proof-check-all: proof-check-idris2 proof-check-lean4 proof-check-agda proof-check-coq proof-scan-dangerous +proof-check-all: proof-check-plan-laws proof-check-plan-laws-controls proof-check-idris2 proof-check-lean4 proof-check-agda proof-check-coq proof-scan-dangerous @echo "=== All proof checks complete ===" # Check Idris2 proofs (ABI, types, dependent type proofs) @@ -87,6 +87,20 @@ proof-check-agda: fi echo "PASS: All Agda proofs verified" +# Runs agda --safe --without-K --cubical-compatible (standards PROOF-POLICY +# §2.1) on verification/proofs/agda/PlanLaws. Fatal if agda is absent or not +# the pinned version; also fails on a pragma, hole, postulate, warning or +# unchecked file. See the header of scripts/check-plan-laws.sh. +# Check the ADR-0003 plan laws (Agda; fatal if agda is absent) +proof-check-plan-laws: + @bash scripts/check-plan-laws.sh + +# Each file in tests/reject/PlanLaws/Controls must be refused, for the reason +# its EXPECT-REFUSED line names. +# Run the negative controls of the plan-law gate +proof-check-plan-laws-controls: + @bash scripts/check-plan-laws.sh --controls + # Check Coq proofs proof-check-coq: #!/usr/bin/env bash diff --git a/docs/architecture/TOPOLOGY.adoc b/docs/architecture/TOPOLOGY.adoc index b6fd919..74dc6e0 100644 --- a/docs/architecture/TOPOLOGY.adoc +++ b/docs/architecture/TOPOLOGY.adoc @@ -40,7 +40,7 @@ Scaffoldia consumes these schemas; it does not fork their definitions. | `src/interface/Abi/` | Generic Idris2 foreign declarations and type/layout model | Not matched to Zig exports | `src/interface/ffi/` | Zig exported scaffold functions and unit/integration tests | No composer operations; Zig-side tests only | `verification/proofs/` | Example/skeleton proof artifacts | No linked composer assurance -| `tests/` | Shell E2E, aspect, workflow tests | No actual mint/retrofit acceptance test +| `tests/` | Conformance and workflow tests; inherited E2E harness (not run by CI), aspect tests | No actual mint/retrofit acceptance test | `.github/workflows/` | 25 YAML workflows, actions.lock | Multiple pre-existing CI failures | `.machine_readable/`, `build/`, `Justfile` | RSR substrate and task recipes | Some checks refer to removed/moved paths |=== @@ -100,7 +100,7 @@ ADR-0002 leaves retention/retirement of this optional seam open. permissions, allowlist and pinned reusable workflows separately. * Some reusables still refer to `hyperpolymath/standards` while the live canon is `metadatastician/standards`. -* The `e2e.yml` job invokes a script requiring Idris2 and Zig without +* (Resolved 2026-11-17: `e2e.yml` now runs the conformance suite as `Conformance L0`; `tests/e2e.sh` is no longer run by CI.) It used to invoke a script requiring Idris2 and Zig without explicit toolchain provisioning. Do not suppress failures to create a green summary. Fix at the owning layer diff --git a/docs/decisions/0003-plan-kernel-tiers-and-conformance.adoc b/docs/decisions/0003-plan-kernel-tiers-and-conformance.adoc new file mode 100644 index 0000000..16d7137 --- /dev/null +++ b/docs/decisions/0003-plan-kernel-tiers-and-conformance.adoc @@ -0,0 +1,224 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += ADR-0003: Plan Kernel, Tiers and an Engine-Neutral Conformance Suite (proposed) +:toc: +:sectnums: + +*Status:* Proposed — refines ADR-0002; does not select an engine. +*Date:* 2026-11-17 +*Scope:* Where safety lives, how a small user and a large estate share one +system, and how the ADR-0002 engine candidates are compared. + +== Context + +ADR-0002 leaves the engine open and asks for equal-scope spikes. Three facts +recorded since then change the shape of that question. + +. *The owner wants one system at two sizes* (2026-11-17). A full composer for + an estate; and, for someone with a few repositories and less ambition, a + minimal engine. The composer must be usable "sitting atop the minimal + engine", not beside it. +. *The estate already has a meta-model for this.* + `hyperpolymath/hybrid-automation-router` (HAR) ADR-0002 defines a two-level + representation: a declarative _resource graph_ (resources, dependencies, + provenance, realisation status, ownership handoff) and an imperative _plan_ + of idempotent primitive operations; _lowering_ takes graph to plan and + _lifting_ takes observed state back to a graph. HAR ADR-0003 takes software + installation as its first resource domain. At commit `0176b7d` the Rust + workspace builds and its 115 tests pass (run 2026-11-17); the graph level + (`har-meta`) exists, the plan level (`har-il`) does not yet. + Minting is lowering. Retrofit is lifting, comparing, and lowering the + difference. Provisioning is HAR's install domain. Scaffoldia's + `CompositionPlan`, `ReconciliationPlan` and `ExecutionReceipt` (ADR-0002) + are the plan level of that same model, for the resource domain "files and + settings of a repository". +. *Every engine candidate in ADR-0002 would have to re-earn the same safety + invariants* (no path escape, no silent overwrite, idempotent apply, + provenance on every write). That is the expensive, proof-worthy part, and it + does not depend on which language composes the plan. + +== Decision (proposed) + +=== Separate the planner from the kernel + +[cols="1,3",options="header"] +|=== +| Part | Role + +| *Plan* | Data. A versioned, deterministic list of file operations with +preconditions and provenance, content held by hash. Internal engine output +(ADR-0002: not a new RSR document format). I-JSON serialised by JCS. +| *Kernel* | Small and trusted. Checks a plan is well formed and safe, then +applies it to a staging target and emits a receipt. Refuses anything it cannot +show safe. It never composes, never reads canon, never contacts a forge. +| *Planner* | Large and untrusted. Reads canon, spine, packs, answers and the +target's deed, and produces a plan. Any language. A wrong planner can produce +a wrong repository; it cannot produce an unsafe write, because the kernel +checks the plan it is given. +|=== + +This is the proof-checker arrangement (a small kernel checks what a large +untrusted tactic produced), applied to file plans. It moves the ADR-0002 +safety invariants out of the engine-selection question: they are properties of +the kernel, stated once and verified once. + +=== Two tiers, one plan format + +* *Tier 0, the minimal engine* is the kernel plus _published plans_. Canon (or + any publisher) ships a plan for "a conformant repository of profile P at + canon version V" with a small set of named holes (owner, repository name, + identifiers). The user fills the holes and applies. No planner is installed. + Where the forge can inherit by reference (reusable workflows, shared + community files), the published plan writes only the thin caller, so the + drift surface stays small. +* *Tier 1, the composer* is a planner that _computes_ the plan from + spine@pin × pack × features × profile, and for retrofit from a three-way + comparison. It hands the plan to the same kernel. + +A Tier 0 user who outgrows published plans installs a planner and changes +nothing else. That is what "atop" means here. + +=== Composition is a join, not an overwrite + +A plan maps each path to at most one operation. Composing two plans is a +partial join: paths in only one side carry over; a path in both sides with the +same operation merges; a path in both sides with different operations is a +*conflict*, and the result is an error, never a last-writer-wins. The only +exception is a replacement that an input contract authorises by name +(issue #70, "contract-authorised overlay path replacement"); it is recorded in +the plan's provenance. + +Laws to state and prove (theory; Agda under +`--safe --without-K --cubical-compatible`, rechecked per PROOF-POLICY §2): + +. join is commutative, associative and idempotent wherever it is defined, so + pack order cannot change the result; +. every path of a join of safe plans is safe, but the join is a safe plan + only when no path of one plan clashes with a path of the other (case-fold + collision or directory prefix), so the kernel checks plan-level safety + again on the composed plan; +. applying a plan twice equals applying it once; +. for compatible plans, applying the join equals applying one then the other. + +Law 1 is why "pack A then pack B" and "pack B then pack A" need no ordering +rule, and why an undeclared conflict cannot be hidden by ordering. These are +candidates for registration in `hyperpolymath/mathesis` once proved; nothing is +claimed until receipts exist. + +Rust kernel code is verified with *Creusot* (contracts in *Pearlite*) and +*Verus* by default (PROOF-POLICY §1.2). Planned scope for both: path +normalisation and containment; uniqueness of paths in a checked plan; +idempotence of apply on a modelled file system. Status today: *not run* for +either verifier; no kernel code exists. + +=== Compare engines with a suite, not an argument + +`verification/conformance/` holds an engine-neutral suite in two halves. + +* *Kernel cases* give a plan and a starting tree and assert the resulting tree + or the refusal. A minimal engine is conformant when it passes these. +* *Planner cases* give pinned inputs and assert properties of the produced + plan (and of the tree after the reference kernel applies it). + +Levels: `L0` reference mint and kernel safety; `L1` composition; `L2` retrofit; +`L3` sustain (checks that must hold in a child as well as in a template). An +engine states the highest level it passes; a level passes only when every case +at and below it passes on the pull-request head, and a skipped case is reported +as skipped. + +The suite is the selection gate of ADR-0002. Its first cases come from defects +found when real repositories were minted from `rsr-template-repo` and from the +negative tests ADR-0002 already lists. Those defects are recorded here as +cases, not patched in the template's scripts, so the knowledge moves with the +suite and not with the engine being replaced. + +Planner candidates to spike against the suite, equal scope (`L0` then `L1`): + +[cols="2,3",options="header"] +|=== +| Candidate | What the spike must show + +| Rust planner | Deed input to deterministic plan with no second grammar. +| Dormant Haskell CLI + Nickel builder | That `init`/`build` can be connected +to emit a plan; today they invoke no renderer. +| Nickel only | That composition can be Nickel record merge with contracts and +no host-language planner: Nickel's merge already refuses conflicting values, +which is the join above. The harvested registry is already Nickel. +|=== + +== Owner decisions recorded (2026-11-17) + +Given through the question selector on that date. + +* *Where the kernel lives.* Scaffoldia consumes the hybrid automation router + as its own module: the plan level is developed at source in HAR (its planned + `har-il`) and Scaffoldia takes it as a pinned dependency, upgraded whenever + Scaffoldia releases. Until HAR has a plan level, the spike in + `src/kernel/plan-kernel` stands in for it. That crate has no dependency and + nothing Scaffoldia-specific in it, so moving it is a change of path and + workspace only. Not done yet: the move, the pin, and a check that the pin is + current. +* *Carrier.* A deed attests facts about a repository; a plan or graph is a + computed message between tools. They are different kinds of thing with one + carrier each: deed clauses for declarations, I-JSON/JCS for plans. HAR + ADR-0002 still names A2ML, which is retired; changing that is a HAR change. +* *First retrofit.* Scaffoldia's first real retrofit is Scaffoldia itself. It + tracks 118 `.a2ml` files and has no `scaffoldia_chora.deed`. Hand conversion + is forbidden, so the translation belongs to kyX (D313). The retrofit case + is: given this repository as it is, produce the plan that leaves it with a + deed and no `.a2ml`, and refuse where kyX has no mapping. It is an `L2` case + and is not written yet. The `.a2ml` files stay until then. +* *Control plane.* No separate lifecycle repository (standards#636): + Scaffoldia owns birth and enrolment (retrofit), chora-registry the census + and de-registration, HAR lifecycle events and plans, gitbot-fleet the acting. +* *Toolchains by derivation.* A repository's toolchain and hooks are generated + from the languages its deed declares (standards#698, #706, #917). This is a + planner requirement at `L1`; nothing implements it yet. +* *CI gate.* The "E2E" job is retired until Scaffoldia can mint something end + to end. The required check is `Conformance L0`, and later `L1`, `L2`, `L3` as + they exist, so the required context always names the highest level the + engine passes. This changes a required context name: the owner updates the + branch ruleset (`E2E — smoke` to `Conformance L0`). + +== Open questions the proofs and the spike raised + +. *Provenance of a merged operation.* Two packs writing identical content + merge, but each operation has one `source`. Unless the merged provenance is + defined (a set, or a canonical choice), the plan bytes depend on pack order + although its effect does not. +. *Which conflicting path is reported* depends on argument order. Cases should + assert the code and that the named path conflicts, not a particular path, + unless the format fixes one (for example the bytewise least). +. *Residue and other template syntaxes.* The hole token collides with `just` + and, read literally, with GitHub Actions expressions. The spike counts only + hole-style names; a published plan still cannot carry a Justfile verbatim. +. *Answer validation.* v0.1 cannot refuse a bad answer value, and has no holes + in paths, so a published plan cannot name `_chora.deed`. + +The spike's reading of each ambiguous point in the specification is asserted +by a case. `verification/conformance/backlog/cases-from-mint-defects.jsonl` +holds 72 cases (39 `L0`, 13 `L1`, 9 `L2`, 11 `L3`) derived from defects found +when repositories were minted from `rsr-template-repo`. Most need a planner or +a real spine and are not yet runnable; two were taken into the `L0` suite. + +== What this does not decide + +* The engine (ADR-0002 selection gate stands). +* Any forge mutation, fan-out, licence or SPDX edit (ADR-0002 limits stand). + +== Consequences + +* Engine choice becomes low-stakes: a planner can be replaced without touching + the safety argument. +* `rsr-template-repo` becomes an input (a spine and packs, as data). Nothing in + Scaffoldia depends on its mint scripts. +* One more internal format to version (the plan), and a kernel that must stay + small enough to verify. Both are costs. +* Lifting an arbitrary existing repository to a graph is lossy (HAR ADR-0002 + says the same); `L2` cases must include a repository the engine cannot fully + classify and assert that it says so. + +== Acceptance evidence before this ADR is accepted + +A kernel spike passing every `L0` kernel case, including the refusals, with a +negative control showing the suite fails a deliberately unsafe kernel; and the +join laws either proved or listed as open with their statements checked. diff --git a/docs/status/PROOF-STATUS.adoc b/docs/status/PROOF-STATUS.adoc index 0b355ff..ea0a730 100644 --- a/docs/status/PROOF-STATUS.adoc +++ b/docs/status/PROOF-STATUS.adoc @@ -20,7 +20,97 @@ | *Total* | *7* | *0* | *0* | *0* | *7* |=== -*Overall*: 0% proven +*Census* (a count with its denominator, never a percentage: standards +PROOF-POLICY §8.4): engineering obligations in the table above, 0 discharged and +7 open (of 7). Theory claims (the ADR-0003 plan laws, next section): Agda leg +`proven` 19 (of 19); `PWG-3` or better 0, `ungraded` 19 (of 19). + +== Theory claims: ADR-0003 plan laws + +The algebra of plan composition and application that ADR-0003 ("Composition is +a join, not an overwrite") lists. Theory obligations (PROOF-POLICY §1): Agda is +the source, rechecked in Rocq and Lean (§2). + +* *Sources*: `verification/proofs/agda/PlanLaws/` (graded root `All.agda`; + one module-level comment per file says what it proves). +* *Invocation*: `cd verification/proofs/agda && agda --safe --without-K + --cubical-compatible PlanLaws/All.agda` (§2.1), run by `just + proof-check-plan-laws` (`scripts/check-plan-laws.sh`). The gate also refuses + any other pragma, a hole, a warning, a postulate in the cone, a prover + postulate outside the trusted base, and a file outside the cone. Negative + controls: `just proof-check-plan-laws-controls` (`tests/reject/PlanLaws/Controls/`, + §8.5.4), each refused for its stated reason. +* *Checker*: Agda 2.7.0.1, the upstream release binary (see the deviation + below). Ran 2026-11-17 in an agent session, not in CI. +* *Library cone*: none. No agda-stdlib and no `.agda-lib`; the import cone of + `PlanLaws/All.agda` (`--dependency-graph`) is the nine `PlanLaws` modules and + `Agda.Primitive`. Postulates in the first-party cone: 0. Trusted base (§8.4): + the four prover postulates of `Agda.Primitive`, `Level` (`BUILTIN LEVEL`), + `lzero` (`LEVELZERO`), `lsuc` (`LEVELSUC`), `_⊔_` (`LEVELMAX`). +* *Equality*: plans by `≈` (lookup agrees at every path); outcomes by `~` (any + two conflicts are related, `ok r ~ ok s` iff `r ≈ s`); file systems by `≗` + (pointwise). No function extensionality is used or assumed. +* *Model*: paths and contents abstract with decidable equality; a desired state + is a file with content or absent; a plan is read through `lookup`; `p ⊔ q` + returns `conflict x` or `ok (p ∪ q)`; `apply` overrides a total file system. + Preconditions (`expect`) are outside the algebra and return in + `PlanLaws/Kernel.agda`. An authorised replacement (issue #70) is out of scope. +* *PWG*: `ungraded` for every row. §8.2 grants `PWG-3` only with a receipt that + records the Agda version, library pin, flags and import cone, and §8.4 derives + a grade from receipts, never asserts it. No receipt exists yet: the run above + was on a commit that is not on `main`. What is missing is a proof receipt + (§8.5.1, `verification/receipts/*_praxis.deed`) for the commit as it lands on + `main`; with it the reader would derive `PWG-3`. `PWG-3` would still owe both + recheck legs (§8.4, rule 1). +* *Recheck legs*: Rocq and Lean both `open`, not attempted (route: Dedukti + transport first, hand re-proof as fallback, no Mathlib; §2). + +[cols="1,5,1,1,1,1,2",options="header"] +|=== +| ID | Claim (statement as proved; file:line) | Token | PWG | Rocq leg | Lean leg | Receipt + +| PL-1 | `conflict-sound`: if `p ⊔ q ≡ conflict x`, then `p` and `q` give `x` two different desired states. `Join.agda:183` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-2 | `conflict-complete`: if some path has `lookup p x ≡ just a`, `lookup q x ≡ just b` and `a ≢ b`, then `p ⊔ q ≡ conflict y` for some `y`. `Join.agda:190` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-3 | `join-lub`: if `p ⊔ q ≡ ok r`, then `r` extends `p` and `q` and is extended by every common extension of both. `Join.agda:263` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-4 | `join-defined-sym`: if `p ⊔ q` is defined, so is `q ⊔ p`. `Join.agda:418` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-5 | `join-comm`: `p ⊔ q ~ q ⊔ p` (both conflicts, or both `ok` with `≈` results). `Join.agda:422` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-6 | `join-assoc-defined`: `(p ⊔ q) ⊔ᴼ ok r` is defined iff `p`, `q`, `r` are pairwise compatible iff `ok p ⊔ᴼ (q ⊔ r)` is defined. `Join.agda:454` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-7 | `join-assoc`: `(p ⊔ q) ⊔ᴼ ok r ~ ok p ⊔ᴼ (q ⊔ r)`. `Join.agda:480` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-8 | `join-idem`: `p ⊔ p ~ ok p`. `Join.agda:495` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-9 | `join-cong`: `p ≈ p′ → q ≈ q′ → p ⊔ q ~ p′ ⊔ q′`. `Join.agda:504` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-10 | `apply-idem`: `apply p (apply p fs) ≗ apply p fs`. `Apply.agda:97` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-11 | `apply-join`: if `p ⊔ q ≡ ok r`, then `apply r fs ≗ apply q (apply p fs)`. `Apply.agda:121` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-12 | `apply-comm`: for compatible `p`, `q`, `apply q (apply p fs) ≗ apply p (apply q fs)`. `Apply.agda:127` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-13 | `commute-compatible`: if the two orders agree (`≗`) on one file system, `p` and `q` are compatible (with PL-12: `apply-comm-iff`, `Apply.agda:147`). `Apply.agda:137` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-14 | `apply-faithful`: given one content value, if `apply p fs ≗ apply q fs` for every `fs`, then `p ≈ q`. `Apply.agda:165` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-15 | `safe-join-ok`: for any predicate `Safe` on paths, if `p ⊔ q ≡ ok r` and every path of `p` and of `q` is safe, every path of `r` is safe. `Safety.agda:79` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-16 | `plan-safe-join`: for a symmetric, irreflexive `Clash`, if `p ⊔ q ≡ ok r` and `p`, `q` are plan-safe, then `r` is plan-safe iff no path of `p` clashes with a path of `q`. `Safety.agda:126` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-17 | `plan-safety-not-preserved`: if `Safe x`, `Safe y` and `Clash x y`, the one-entry plans at `x` and at `y` are plan-safe and join, and the join is not plan-safe. `Safety.agda:150` (instance: `case-fold-counterexample`, `Example.agda:84`) | `proven` | `ungraded` | `open` | `open` | none yet +| PL-18 | The total join `⊔ᴼ` on outcomes is a semilattice up to `~` with unit `ok []` and conflict as top: `⊔ᴼ-cong`, `⊔ᴼ-comm`, `⊔ᴼ-assoc`, `⊔ᴼ-idem`, `⊔ᴼ-unit`. `Semilattice.agda:40,49,55,61,67` | `proven` | `ungraded` | `open` | `open` | none yet +| PL-19 | `kapply-idem`: for a kernel plan in which lookup finds each operation's state (`unique-functional`: true when no two operations share a path), a second kernel apply is accepted, finds every path already in its desired state, and changes nothing; `kapply-refines`: an accepted kernel apply is `apply`. `Kernel.agda:175,159,115` | `proven` | `ungraded` | `open` | `open` | none yet +|=== + +ADR-0003 law 2 ("a join of safe plans is safe") holds for per-path safety +(PL-15) and is false for the plan-level conditions of plan format v0.1 (no +case-fold collision, no directory-prefix clash): PL-16 gives the exact +condition and PL-17 the counterexample. A kernel must re-check those +conditions on the composed plan. + +*Deviation* (PROOF-POLICY §6), state `open`: the leg above is the Agda leg; the +tool is Agda 2.7.0.1, installed from the upstream release archive +`Agda-v2.7.0.1-linux.tar.xz` (SHA-256 +`975b515a14877ab6bce5bfc641e16c4a3ee52ca5d7f846577dee80aa2145db8a`; binary +`bin/agda` SHA-256 +`6de41437c14c05c9fe576d724cc67386444c0fa9fee662a08250fefb91bee8b6`), not through +Guix or the container, because the session had no Guix and `build/guix.scm` +does not provide Agda. `scripts/check-plan-laws.sh` asserts the version and +fails on a mismatch. It closes when Agda comes from the repository's Guix +manifest or container and a CI lane runs `just proof-check-plan-laws`; no CI +lane runs it today. + +*Rust kernel*: the refinement from `PlanLaws/Kernel.agda` to kernel code is an +engineering obligation for Creusot (contracts in Pearlite) and Verus +(PROOF-POLICY §1.2). Status `open` for both: no kernel code exists. == Proofs Done @@ -66,6 +156,9 @@ | ABI-5 | C ABI compliance | ABI | Idris2 | P1 | 4h | TP-1 | Core data type well-formedness | TP | Idris2 | P1 | 4h | TP-2 | Public API type safety | TP | Lean4 | P2 | 4h +| PL-1..19 (Rocq) | Recheck leg for the plan laws: Dedukti transport first, hand re-proof as fallback | Theory | Rocq | P2 | not estimated +| PL-1..19 (Lean) | Recheck leg for the plan laws: core library only, no Mathlib | Theory | Lean | P2 | not estimated +| PL-receipt | Proof receipt for PL-1..19 on a commit on main (PROOF-POLICY §8.5.1), so a grade can be derived | Theory | Agda | P1 | not estimated |=== == Verification Commands @@ -81,6 +174,11 @@ just proof-check-lean4 # Check all Agda proofs just proof-check-agda +# Check the ADR-0003 plan laws (canonical flags; fatal if agda is absent), +# and show that the gate refuses each negative control +just proof-check-plan-laws +just proof-check-plan-laws-controls + # Check all Coq proofs just proof-check-coq @@ -98,4 +196,5 @@ panic-attack assail --proofs-only | Date | Change | By | 2026-04-04 | Initial proof status tracking | Template +| 2026-11-17 | ADR-0003 plan laws PL-1 to PL-19: Agda leg `proven`, `ungraded` (no receipt yet), recheck legs `open`; census replaces the percentage | Agent (Claude) |=== diff --git a/docs/status/ROADMAP.adoc b/docs/status/ROADMAP.adoc index 9b6c73f..5fd4ada 100644 --- a/docs/status/ROADMAP.adoc +++ b/docs/status/ROADMAP.adoc @@ -24,6 +24,21 @@ Zig tests or passing isolated workflows. * [ ] Do not claim CI green until all required latest-commit checks execute successfully and review threads are resolved. +== Owner decision: the CI gate is conformance levels (2026-11-17) + +The `E2E — smoke` job is retired as a concept until Scaffoldia can mint +something end to end. The required check is `Conformance L0`, and later `L1`, +`L2`, `L3` as those levels exist, so the required context always names the +highest level the engine passes. `.github/workflows/e2e.yml` (file name kept, +it is an `actions.lock` key) runs `verification/conformance/check-l0.sh`. +The inherited `tests/e2e.sh` (Idris2/Zig) is kept but not run by CI; whether +the seam stays is the P0 item above. + +* [ ] *Owner step, required:* in the repository branch ruleset, replace the + required status check `E2E — smoke` with `Conformance L0`. Until that is done + a pull request waits forever on a context that no longer reports. +* [ ] First real run of `Conformance L0` on GitHub (none yet). + == M0 — Complete scaffold with live interfaces * [ ] Parse pinned canon/spine and archetype praxis deeds, overlay/prune and @@ -42,6 +57,11 @@ Zig tests or passing isolated workflows. receipts; skips remain reported as skips. * [ ] Prove idempotence, deterministic replay, negative-case enforcement and same-input repeatability in CI. +* [x] Plan kernel spike (ADR-0003, Rust, `src/kernel/`) passes all 47 `L0` + kernel conformance cases and the suite fails each of its 3 negative controls + (`just conformance`, local run 2026-11-17; see + `verification/conformance/README.adoc`, Evidence). Wired to CI as `Conformance L0` + (not yet run on GitHub); no planner; Creusot/Pearlite and Verus contracts not run. == M1 — Sustain loop (after M0) diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc index 627a105..bb75ec3 100644 --- a/docs/status/TEST-NEEDS.adoc +++ b/docs/status/TEST-NEEDS.adoc @@ -18,7 +18,7 @@ section instead describes the test infrastructure scaffoldia actually has. | *Source modules* | 6 | 3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI (build.zig, main.zig), 1 Zig integration test module | *Unit tests* | 3 | Inline `test` blocks in `src/interface/ffi/src/main.zig` (lifecycle, error handling, version) | *Integration tests* | 10 | `src/interface/ffi/test/integration_test.zig` — real tests against the exported FFI (lifecycle, operations, strings, version, build_info, error handling) -| *E2E tests* | 1 | `tests/e2e.sh` — real preflight + `idris2 --build src/interface/abi.ipkg` + `zig build`/`zig build test` +| *E2E tests* | 1 | `tests/e2e.sh` (inherited Idris2/Zig harness; not run by CI and not a gate since 2026-11-17, the required check is `Conformance L0`) — real preflight + `idris2 --build src/interface/abi.ipkg` + `zig build`/`zig build test` | *Aspect tests* | 1 | `tests/aspect_tests.sh` — SPDX header coverage + dangerous-pattern grep (real, pre-existing, unchanged by the cure) | *Workflow tests* | 1 | `tests/workflows/validate_workflows_test.sh` (unchanged by the cure) | *Benchmarks* | 3 | `benches/template_bench.sh` — Zig build, Zig tests, workflow validation diff --git a/scripts/check-plan-laws.sh b/scripts/check-plan-laws.sh new file mode 100755 index 0000000..6ebf723 --- /dev/null +++ b/scripts/check-plan-laws.sh @@ -0,0 +1,297 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-plan-laws.sh [--controls] +# +# The gate for the plan-law development, verification/proofs/agda/PlanLaws/ +# (ADR-0003, "Composition is a join, not an overwrite"). It checks the graded +# root PlanLaws/All.agda with the canonical theory invocation of standards +# PROOF-POLICY §2.1, +# +# agda --safe --without-K --cubical-compatible PlanLaws/All.agda +# +# from the source root verification/proofs/agda, and refuses the development +# unless ALL of these hold: +# +# 1. Agda is on PATH (absent is a failure, never a skip) and is the pinned +# version below (PROOF-POLICY §6: assert the version, fail on a mismatch). +# 2. Every .agda file begins with exactly the canonical OPTIONS line and has +# no other pragma ({-# ... #-}): no TERMINATING, NON_TERMINATING, +# NO_POSITIVITY_CHECK, REWRITE, BUILTIN, and no second OPTIONS that could +# weaken the flags. +# 3. No hole ({! !}) and no trust primitive (primTrustMe, primEraseEquality). +# 4. Agda exits 0 with no warning. +# 5. The comment-aware postulate scan (scripts/scan-postulates.sh, adopted +# from the PROOF-POLICY §8.4 reference gate) finds no postulate in the +# first-party modules of the import cone that Agda reports +# (--dependency-graph). +# 6. The prover-supplied modules of the cone postulate exactly the trusted +# base below, by name and BUILTIN binding (§8.4); anything else fails. +# 7. Every .agda file under PlanLaws/ is in the import cone of the root, so +# no file escapes the check. +# +# Agda runs on a fresh copy of the .agda files in a temporary directory, so a +# stale interface file (.agdai) can never stand in for a check and nothing is +# written into the repository. +# +# With --controls it runs the negative controls instead: each file in +# tests/reject/PlanLaws/Controls/ is added to a copy of +# the development and checked as the root by the same gate. Each MUST be +# refused, and for the reason its `-- EXPECT-REFUSED: ` line names. A +# further generated control adds an orphan module with a postulate that the +# root does not import; check 7 must refuse it. A control that is accepted, or +# refused for another reason, fails the run: a gate that accepts everything +# proves nothing. +# +# On success the gate prints the fields a proof receipt records (PROOF-POLICY +# §8.5.1): checker and version, invocation, import cone, trusted base, axioms +# (none), and the inputs manifest with its SHA-256 for the working tree. +# +# Exit: 0 pass; 1 fail; 2 misuse. + +# shellcheck disable=SC2001 # sed reads more plainly here for indenting multi-line output +set -euo pipefail + +PINNED_AGDA="2.7.0.1" +CANON='{-# OPTIONS --safe --without-K --cubical-compatible #-}' +FLAGS=(--safe --without-K --cubical-compatible) +SRC="verification/proofs/agda" +DEV="PlanLaws" +ROOT_MODULE="PlanLaws/All.agda" +CONTROLS="tests/reject/PlanLaws/Controls" + +# The prover-supplied postulates the cone may reach, for the pinned Agda: +# " BUILTIN ", one per line. +EXPECTED_TRUSTED_BASE="$(LC_ALL=C sort <<'EOF' +Agda.Primitive Level BUILTIN LEVEL +Agda.Primitive lzero BUILTIN LEVELZERO +Agda.Primitive lsuc BUILTIN LEVELSUC +Agda.Primitive _⊔_ BUILTIN LEVELMAX +EOF +)" + +MODE=gated +case "${1:-}" in + "") ;; + --controls) MODE=controls ;; + *) echo "usage: $(basename "$0") [--controls]" >&2; exit 2 ;; +esac + +cd "$(dirname "${BASH_SOURCE[0]}")/.." +ROOT="$PWD" +WORK="$(mktemp -d)" +trap 'rm -rf "$WORK"' EXIT + +# --- toolchain ---------------------------------------------------------------- +if ! command -v agda >/dev/null 2>&1; then + echo "FAIL: agda not found on PATH. A missing prover is a failure, never a skip." >&2 + exit 1 +fi +version_line="$(agda --version 2>/dev/null | head -1)" +echo "checker: $version_line ($(command -v agda))" +if [ "${version_line#Agda version }" != "$PINNED_AGDA" ]; then + echo "FAIL: expected Agda $PINNED_AGDA (the pin this gate's trusted base was read from)." >&2 + echo " A new Agda changes the trusted base: re-read it and re-earn the receipt." >&2 + exit 1 +fi + +# Agda keeps the interfaces of its own modules under /lib/prim. If +# that directory is read-only and has none (a packaged Agda), give Agda a +# writable copy through Agda_datadir, the variable it reads for it. +DATADIR="${Agda_datadir:-$(agda --print-agda-data-dir 2>/dev/null)}" +if [ ! -d "$DATADIR/lib/prim/_build" ] && [ ! -w "$DATADIR/lib/prim" ]; then + cp -r "$DATADIR/." "$WORK/datadir/" + chmod -R u+w "$WORK/datadir" + DATADIR="$WORK/datadir" +fi +export Agda_datadir="$DATADIR" + +# --- the trusted base a prover-supplied module declares ---------------------- +# Prints " BUILTIN " for each name the module +# postulates (UNBOUND if no BUILTIN pragma binds it). Prints +# "UNREADABLE " if the number of postulate blocks it parsed differs +# from the number of postulate keywords the comment-aware scan finds. +prover_postulates() { + local module="$1" file="$2" blocks keywords + awk -v mod="$module" ' + /^[ \t]*--/ { next } + /^[ \t]*postulate[ \t]*$/ { inblock = 1; blocks++; next } + /^[ \t]*postulate[ \t]+[^ \t]+[ \t]+:/ { + s = $0; sub(/^[ \t]*postulate[ \t]+/, "", s); sub(/[ \t].*/, "", s) + names[++n] = s; blocks++; inblock = 0; next } + inblock && /^[ \t]+[^ \t]+[ \t]+:/ { + s = $0; sub(/^[ \t]+/, "", s); sub(/[ \t].*/, "", s); names[++n] = s; next } + inblock && /^[ \t]*$/ { inblock = 0; next } + inblock && /^[^ \t]/ { inblock = 0 } + /\{-#[ \t]*BUILTIN[ \t]/ { + s = $0; sub(/.*\{-#[ \t]*BUILTIN[ \t]+/, "", s); split(s, w, /[ \t]+/) + bound[w[2]] = w[1] } + END { + for (i = 1; i <= n; i++) + printf "%s %s %s\n", mod, names[i], (names[i] in bound) ? "BUILTIN " bound[names[i]] : "UNBOUND" + printf "#blocks %d\n", blocks } + ' "$file" >"$WORK/pp" + blocks="$(sed -n 's/^#blocks //p' "$WORK/pp")" + set +e + keywords="$(bash "$ROOT/scripts/scan-postulates.sh" "$file" 2>/dev/null | sed -n 's/^postulate scan: [0-9]* files, \([0-9]*\) postulate.*/\1/p')" + set -e + if [ "$blocks" != "$keywords" ]; then echo "UNREADABLE $module"; fi + grep -v '^#blocks ' "$WORK/pp" || true +} + +# --- the gate --------------------------------------------------------------------- +# gate DIR ROOTREL COVER : checks DIR (a source root) with ROOTREL as the root +# module. COVER=1 also requires every .agda file under DIR/PlanLaws to be in +# the cone. Prints its findings; returns 0 iff every check passes. +gate() { + local dir="$1" rootrel="$2" cover="$3" fails=0 f out rc m + local -a files own prover + mapfile -t files < <(cd "$dir" && find . -name '*.agda' | sed 's|^\./||' | LC_ALL=C sort) + + # Checks 2 and 3: header, pragmas, holes, trust primitives. + for f in "${files[@]}"; do + if [ "$(head -n 1 "$dir/$f")" != "$CANON" ]; then + echo " gate: first line is not the canonical OPTIONS pragma: $f"; fails=1 + fi + if [ "$(grep -c '{-#' "$dir/$f")" -ne 1 ]; then + echo " gate: pragma other than the canonical OPTIONS line: $f" + grep -n '{-#' "$dir/$f" | sed 's/^/ /'; fails=1 + fi + if grep -qE '\{!|!\}|primTrustMe|primEraseEquality' "$dir/$f"; then + echo " gate: hole or trust primitive: $f" + grep -nE '\{!|!\}|primTrustMe|primEraseEquality' "$dir/$f" | sed 's/^/ /'; fails=1 + fi + done + + # Check 4: Agda, canonical flags, clean. + rm -f "$WORK/cone.dot" + set +e + out="$(cd "$dir" && agda "${FLAGS[@]}" --dependency-graph="$WORK/cone.dot" "$rootrel" 2>&1)"; rc=$? + set -e + if [ "$rc" -ne 0 ]; then + echo " agda: exit $rc" + grep -v '^ /' <<<"$out" | grep -v '^ *Checking ' | sed 's/^/ agda: /' | head -30 + return 1 + fi + if grep -q 'warning' <<<"$out"; then + echo " agda: warnings (a clean check is required)" + sed 's/^/ agda: /' <<<"$out" | head -30 + fails=1 + fi + if [ ! -s "$WORK/cone.dot" ]; then echo " gate: agda reported no import cone"; return 1; fi + + # Split the cone into first-party files and prover-supplied modules. + own=(); prover=() + while IFS= read -r m; do + if [ -f "$dir/${m//.//}.agda" ]; then own+=("${m//.//}.agda"); else prover+=("$m"); fi + done < <(sed -n 's/.*label="\([^"]*\)".*/\1/p' "$WORK/cone.dot" | LC_ALL=C sort -u) + + # Check 5: no postulate in the first-party cone. + set +e + out="$(cd "$dir" && bash "$ROOT/scripts/scan-postulates.sh" "${own[@]}" 2>&1)"; rc=$? + set -e + if [ "$rc" -ne 0 ]; then echo " gate: postulate in the import cone"; sed 's/^/ /' <<<"$out"; fails=1; fi + + # Check 6: the prover-supplied postulates are exactly the trusted base. + local found="" + for m in "${prover[@]}"; do + f="$DATADIR/lib/prim/${m//.//}.agda" + if [ ! -f "$f" ]; then echo " gate: cannot find prover module $m at $f"; fails=1; continue; fi + found+="$(prover_postulates "$m" "$f")"$'\n' + done + found="$(grep -v '^$' <<<"$found" | LC_ALL=C sort || true)" + if [ "$found" != "$EXPECTED_TRUSTED_BASE" ]; then + echo " gate: the prover-supplied postulates of the cone are not the recorded trusted base" + diff <(echo "$EXPECTED_TRUSTED_BASE") <(echo "$found") | sed 's/^/ /' || true + fails=1 + fi + + # Check 7: coverage. + if [ "$cover" = 1 ]; then + local unreached + unreached="$(comm -23 <(cd "$dir" && find "$DEV" -name '*.agda' | LC_ALL=C sort) \ + <(printf '%s\n' "${own[@]}" | LC_ALL=C sort) || true)" + if [ -n "$unreached" ]; then + echo " gate: files under $DEV/ that the root does not import (unchecked):" + sed 's/^/ /' <<<"$unreached"; fails=1 + fi + fi + + GATE_OWN=("${own[@]}"); GATE_PROVER=("${prover[@]}"); GATE_TB="$found" + return "$fails" +} + +# A fresh copy of the development's .agda files at DIR/PlanLaws. +copy_dev() { + local dir="$1" f + mkdir -p "$dir" + while IFS= read -r f; do + mkdir -p "$dir/$(dirname "$f")"; cp "$SRC/$f" "$dir/$f" + done < <(cd "$SRC" && find "$DEV" -name '*.agda' | LC_ALL=C sort) +} + +if [ "$MODE" = gated ]; then + echo "=== plan laws: gate (verification/proofs/agda/$DEV) ===" + copy_dev "$WORK/src" + if ! gate "$WORK/src" "$ROOT_MODULE" 1; then + echo; echo "RESULT: FAIL"; exit 1 + fi + echo " invocation: cd $SRC && agda ${FLAGS[*]} $ROOT_MODULE" + echo " import cone (first party): ${#GATE_OWN[@]} module(s)" + printf ' %s\n' "${GATE_OWN[@]}" + echo " import cone (prover-supplied): ${GATE_PROVER[*]}" + echo " trusted base (prover postulates, by name and binding):" + sed 's/^/ /' <<<"$GATE_TB" + echo " axioms: none (no postulate in the first-party cone; --safe in force)" + echo " library: none (no agda-stdlib, no .agda-lib)" + manifest="$(for f in "${GATE_OWN[@]}"; do printf '%s\n' "$SRC/$f"; done | LC_ALL=C sort | + while IFS= read -r p; do printf '%s %s\n' "$(sha256sum "$p" | cut -d' ' -f1)" "$p"; done)" + echo " inputs manifest (working tree; PROOF-POLICY §8.5.1):" + sed 's/^/ /' <<<"$manifest" + echo " inputs-sha256 (working tree): $(printf '%s\n' "$manifest" | sha256sum | cut -d' ' -f1)" + echo; echo "RESULT: PASS" + exit 0 +fi + +# --- negative controls ------------------------------------------------------------ +echo "=== plan laws: negative controls ($CONTROLS) ===" +bad=0; n=0 +mapfile -t controls < <(find "$CONTROLS" -name '*.agda' 2>/dev/null | LC_ALL=C sort) +if [ "${#controls[@]}" -eq 0 ]; then echo "FAIL: no negative controls found"; exit 1; fi + +run_control() { + # $1 name, $2 expected ERE, $3 directory holding the prepared source root, + # $4 root module, $5 cover flag + local name="$1" expect="$2" dir="$3" rootrel="$4" cover="$5" out rc + n=$((n + 1)) + set +e; out="$(gate "$dir" "$rootrel" "$cover" 2>&1)"; rc=$?; set -e + if [ "$rc" -eq 0 ]; then + echo "FAIL $name: ACCEPTED by the gate (a control must be refused)"; bad=$((bad + 1)) + elif ! grep -qE "$expect" <<<"$out"; then + echo "FAIL $name: refused, but not for the expected reason /$expect/:" + sed 's/^/ /' <<<"$out"; bad=$((bad + 1)) + else + echo "ok $name: refused, as expected (/$expect/)" + grep -E "$expect" <<<"$out" | head -3 | sed 's/^/ /' + fi +} + +for c in "${controls[@]}"; do + expect="$(sed -n 's/^-- EXPECT-REFUSED: //p' "$c" | head -1)" + if [ -z "$expect" ]; then echo "FAIL $c: no EXPECT-REFUSED line"; bad=$((bad + 1)); continue; fi + d="$WORK/ctl-$(basename "$c" .agda)" + copy_dev "$d" + mkdir -p "$d/$DEV/Controls"; cp "$c" "$d/$DEV/Controls/" + run_control "$(basename "$c")" "$expect" "$d" "$DEV/Controls/$(basename "$c")" 0 +done + +# Generated control: an orphan module with a postulate, not imported by the +# root. Agda never sees it; only the coverage check (7) can refuse it. +d="$WORK/ctl-orphan"; copy_dev "$d" +{ echo "$CANON"; echo "module PlanLaws.Orphan where"; echo "postulate"; echo " anything : (A : Set) → A"; } >"$d/$DEV/Orphan.agda" +run_control "Orphan.agda (generated)" "the root does not import" "$d" "$ROOT_MODULE" 1 + +echo +if [ "$bad" -gt 0 ]; then echo "RESULT: FAIL ($bad of $n control(s) not refused as expected)"; exit 1; fi +echo "RESULT: PASS ($n of $n control(s) refused, each for its expected reason)" diff --git a/scripts/scan-postulates.sh b/scripts/scan-postulates.sh new file mode 100755 index 0000000..4d6fd6c --- /dev/null +++ b/scripts/scan-postulates.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell +# Comment-aware postulate scan of Agda source files (PROOF-POLICY §8.4, +# "Axioms travel with the grade"): --safe already refuses `postulate`, and this +# scan is the second of the three parts that make the absence of axioms visible +# on a receipt. check-proofs.sh passes it the first-party modules of the import +# cone that Agda itself reports, so the files scanned are the files checked. +# +# Adopted unchanged in its lexer from hyperpolymath/januskey (989a747, +# scripts/scan-postulates.sh), the reference gate PROOF-POLICY §8.4 names. +# +# Lexing follows Agda closely enough for one keyword: text inside nested +# {- -} comments, after a `--` that starts a token (with or without a space +# after it), and inside string or character literals is ignored. A `--` inside +# a name such as `x--y` is part of the name. A comment separates tokens, as it +# does for Agda, so `postulate{- c -}X` is a postulate. +# A pragma ({-# … #-}) is skipped to the first `#-}`: its contents are pragma +# tokens or, for FOREIGN and COMPILE, another language's text, never an Agda +# declaration, and Agda does not nest comments inside it (Lexer.x). Agda closes +# a pragma at a `#-}` token, never before the first `#-}` in the text, so this +# rule can end a pragma early (an extra report) but never late (a missed one). +# Whitespace is Agda's: its lexer reads every character Haskell's isSpace accepts, +# other than tab and newline, as a space (Agda.Syntax.Parser.Alex, toASCII), so +# CR, FF, VT, NO-BREAK SPACE and the Unicode space separators (category Zs) are +# turned into spaces before the line is lexed. +# +# Usage: scan-postulates.sh FILE... Prints each hit as path:line: text and the +# count; exits 1 if there is any hit, 2 on a usage error or an unreadable file. +set -euo pipefail +[ "$#" -gt 0 ] || { echo "usage: $0 FILE..." >&2; exit 2; } +for f in "$@"; do + [[ -f $f && -r $f ]] || { echo "ERROR: not a readable file: $f" >&2; exit 2; } +done +# The non-ASCII spaces as UTF-8 byte sequences: U+00A0, U+1680, U+2000-U+200A, +# U+202F, U+205F, U+3000. awk runs in the C locale, so it matches bytes the same +# way whichever awk is installed. +ws="$(printf '\302\240|\341\232\200|\342\200[\200-\212]|\342\200\257|\342\201\237|\343\200\200')" +hits="$(LC_ALL=C awk -v ws="$ws" ' + # Agda name characters are everything except whitespace and .;{}()@" + function namechar(c) { return c != "" && c !~ /[ \t.;{}()@"]/ } + FNR == 1 { depth = 0; pragma = 0 } + { + line = $0; gsub(/[\r\f\v]/, " ", line); gsub(ws, " ", line) + code = ""; i = 1; n = length(line) + while (i <= n) { + c = substr(line, i, 1); two = substr(line, i, 2) + # The last character emitted as code, not the raw one before i: a skipped + # literal, comment or pragma leaves a space, so a token may start after it. + prev = (code == "") ? "" : substr(code, length(code), 1) + if (pragma) { # inside {-# … #-}: skip to the first #-} + if (substr(line, i, 3) == "#-}") { pragma = 0; i += 3; code = code " " } else i++ + continue + } + if (depth == 0 && two == "{-" && substr(line, i + 2, 1) == "#") { + pragma = 1; i += 3; code = code " "; continue + } + if (two == "{-") { if (depth == 0) code = code " "; depth++; i += 2; continue } + if (depth > 0 && two == "-}") { depth--; i += 2; continue } + if (depth > 0) { i++; continue } + if (c == "\"") { # string literal: skip to the closing quote + i++ + while (i <= n && substr(line, i, 1) != "\"") i += (substr(line, i, 1) == "\\") ? 2 : 1 + i++; code = code " "; continue + } + if (c == "'\''" && !namechar(prev)) { # character literal at a token start + i++ + while (i <= n && substr(line, i, 1) != "'\''") i += (substr(line, i, 1) == "\\") ? 2 : 1 + i++; code = code " "; continue + } + if (two == "--" && !namechar(prev)) break + code = code c; i++ + } + if (code ~ /(^|[ \t.;{}()@])postulate([ \t.;{}()@]|$)/) + printf "%s:%d: %s\n", FILENAME, FNR, $0 + } +' "$@")" +count=0 +[ -n "$hits" ] && count="$(printf '%s\n' "$hits" | wc -l | tr -d ' ')" +[ -n "$hits" ] && printf '%s\n' "$hits" +echo "postulate scan: $# files, $count postulate(s)" +[ "$count" -eq 0 ] || exit 1 diff --git a/src/kernel/Cargo.lock b/src/kernel/Cargo.lock new file mode 100644 index 0000000..324e790 --- /dev/null +++ b/src/kernel/Cargo.lock @@ -0,0 +1,210 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "plan-kernel" +version = "0.1.0" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "scaffoldia-kernel" +version = "0.1.0" +dependencies = [ + "plan-kernel", + "serde_json", + "sha2", + "unicode-normalization", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "tinyvec" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "unicode-normalization" +version = "0.1.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75cd3fb03d5288b3ba9a1ee103ac7e9cbb59f0b03d64f8ddfcc04dd42758a85d" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/src/kernel/Cargo.toml b/src/kernel/Cargo.toml new file mode 100644 index 0000000..d7e9f59 --- /dev/null +++ b/src/kernel/Cargo.toml @@ -0,0 +1,16 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Scaffoldia plan kernel spike (ADR-0003). `plan-kernel` is the pure, std-only +# decision layer meant for Creusot/Pearlite and Verus contracts; `scaffoldia-kernel` is the +# I/O edge (JSON parsing, hashing, NFC, filesystem). +[workspace] +members = ["plan-kernel", "scaffoldia-kernel"] +resolver = "2" + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "MPL-2.0" +publish = false +repository = "https://github.com/hyperpolymath/scaffoldia" diff --git a/src/kernel/plan-kernel/Cargo.toml b/src/kernel/plan-kernel/Cargo.toml new file mode 100644 index 0000000..98d32fe --- /dev/null +++ b/src/kernel/plan-kernel/Cargo.toml @@ -0,0 +1,16 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Pure decision core of the plan kernel. It must keep ZERO dependencies: +# everything it cannot do with `std` (SHA-256, Unicode NFC) is injected +# through the `Prims` trait by the edge crate. +[package] +name = "plan-kernel" +description = "Pure decision core of a file-plan kernel: check, instantiate and decide apply for plan format v0.1" +version.workspace = true +edition.workspace = true +license.workspace = true +publish.workspace = true +repository.workspace = true + +[dependencies] diff --git a/src/kernel/plan-kernel/PROOF-PLAN.adoc b/src/kernel/plan-kernel/PROOF-PLAN.adoc new file mode 100644 index 0000000..5ebabc3 --- /dev/null +++ b/src/kernel/plan-kernel/PROOF-PLAN.adoc @@ -0,0 +1,144 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += plan-kernel: Proof Plan +:toc: + +What is to be verified in this crate, by which verifier, and what has been +run. Normative policy: `metadatastician/standards` `3-practice/PROOF-POLICY.adoc` +(§1.2: Rust code is verified with *Creusot*, contracts written in *Pearlite*, +and with *Verus*, by default; §1.1: third-party code is not re-proved but +stated as an `ASSUMED` boundary). + +*Status: nothing in this file has been verified.* Every row below is +`not run`. Unit and property tests exist (`cargo test`); they are tests, not +proofs, and are reported as such. + +== Why this crate is the verification target + +The crate is the pure decision layer of the kernel. It performs no I/O and +depends on nothing beyond `std`. Everything that needs tables or cryptography +is injected through the `Prims` trait (NFC check, SHA-256), and the +filesystem is reached only through observations (`apply::OpObs`) that the +edge builds and effects (`apply::Step`) that the edge performs. That keeps +the obligations below about total functions over plain data, which is what +both Creusot and Verus handle best. + +Pearlite is Creusot's specification language, not a third verifier. Running +both verifiers does not produce two independent witnesses: they share solver +trust (policy §1.2). + +== Obligations + +[cols="1,2,3,1,1",options="header"] +|=== +| Id | Function | Property (informal statement of the contract) | Creusot (Pearlite) | Verus + +| P1 path containment +| `path::path_fault` +| `path_fault(p) == None` implies: `p` is non-empty; does not start with `/`; +contains no `\` and no control character; every `/`-separated segment is +non-empty and is neither `.` nor `..` nor `.git` in any ASCII case. Hence, +for any directory `t`, the lexical resolution of `t/p` is a proper +descendant of `t` (stated over a modelled path resolution). +| not run | not run + +| P2 uniqueness and prefix-freeness +| `check::check_paths` +| `Ok(())` implies: op paths strictly increase bytewise (so at most one op +per path); `fold` is injective on the op paths; no folded op path is a proper +`/`-prefix of another. +| not run | not run + +| P3 pinned provenance +| `plan::parse_plan` +| `Ok(plan)` implies: every input `rev` is 40 lowercase hex digits; every +op's `source.input` (and `replaces.input`) names a declared input; a delete's +`expect` is a digest, never "absent"; hole names match `[A-Z][A-Z0-9_]*` +and are distinct. +| not run | not run + +| P4 all-or-nothing +| `apply::decide` +| The result is `Err(_)`, or `Ok(steps)` with `steps.len() == plan.ops.len()` +and `steps[i].op == i`. Together with the edge's structure (the edge calls +`perform` only on `Ok`), a refusal performs no effect. The edge part is +`ASSUMED` (see below). +| not run | not run + +| P5 precondition soundness +| `apply::decide_op` +| `Write` only when (leaf absent and expect absent) or (leaf a regular file +whose digest equals expect); `Delete` only when the leaf is a regular file +whose digest equals expect; never `Write`/`Delete` when the leaf or an +ancestor is a symbolic link or an ancestor is not a directory. +| not run | not run + +| P6 idempotence +| `model::ModelFs::apply` +| If `apply(fs) == Ok(_)` then `apply` on the result returns `Ok(steps')` +with every effect `Unchanged` or `AlreadyAbsent`, and leaves the state +unchanged (`apply ∘ apply = apply`). Depends on P2: prefix-freeness makes +the operations independent (see the module comment of `apply`). +| not run | not run + +| P7 no residue +| `instantiate::instantiate` +| `Ok(out)` implies `out.plan.holes` is empty and `find_residue(b) == None` +for every output blob `b`; every hole has an answer and every answer names a +hole. +| not run | not run + +| P8 canonical form +| `json::canonical`, `json::is_j1` +| `canonical` sorts members by UTF-16 code units and escapes strings per +RFC 8785 §3.2.2.2; `is_j1(bytes, v)` holds for exactly one byte string per +value. (Injectivity of parsing is not claimed.) +| not run | not run +|=== + +Planned scope per verifier: both verifiers take P1 to P7. P8 is a +specification-conformance obligation (against RFC 8785) and is listed for +completeness; if one verifier cannot express the UTF-16 ordering cheaply, it +is recorded as unsupported for that verifier, not silently dropped. + +== `ASSUMED` boundaries + +[cols="1,3",options="header"] +|=== +| Boundary | Assumption +| `Prims::is_nfc` | Implemented at the edge by `unicode-normalization` 0.1.26: returns `true` exactly for strings in Unicode NFC. +| `Prims::sha256_hex` | Implemented at the edge by `sha2` 0.10.9: SHA-256, lowercase hex; collision resistance is assumed. +| `path::fold` | `lower(upper(lower(s)))` over `std`'s Unicode case mappings is assumed to merge at least what full case folding merges. Not checked against `CaseFolding.txt`. +| JSON parsing | `serde_json` 1.0.154 parses I-JSON faithfully; duplicate member names are caught by the J-1 byte comparison, not by the parser. +| Edge observation | `lstat`-based observation in the edge reports the target faithfully and never follows a link. +| Edge effects | `ensure_dirs` and `write_atomic` re-check with `lstat` and write via `O_CREAT|O_EXCL` + `rename`; a concurrent writer between check and write is detected only on the paths the edge re-checks (a TOCTOU window remains, and an I/O failure mid-apply can leave a partial state that a re-run converges by P6). +|=== + +Kani (policy §4.1, `unsafe`/FFI seams): not applicable. The workspace has +`#![forbid(unsafe_code)]` in both crates and no FFI. + +== What was attempted (2026-11-17) + +* Verus: `curl -sSL https://api.github.com/repos/verus-lang/verus/releases/latest` + returned `"GitHub access to this repository is not enabled for this session"`, + and `https://github.com/verus-lang/verus/releases/latest` answered + `HTTP/1.1 403 Forbidden` through the session proxy. Verus is distributed as + release binaries pinned to a Rust toolchain; none could be fetched. +* Creusot: `cargo info cargo-creusot` gives `could not find cargo-creusot in + registry`. The Creusot driver is installed from its Git repository together + with a pinned nightly toolchain, Why3 and SMT solvers; none were reachable + in this session. `creusot-std` (the contract library) is on crates.io, but + contracts without the driver would be unchecked text, so none were added. + +Next step: in an environment with the Creusot driver and the Verus release +installed, add the contracts above to `path`, `check`, `plan`, `apply`, +`model` and `instantiate` (behind a feature flag or `cfg` so the plain build +stays dependency-free), run both, and record each row's command, version and +result here. + +== Testing evidence (not verification) + +`cargo test -p plan-kernel` runs unit tests for every module and three +property-style tests with a fixed-seed generator: idempotence and +all-or-nothing on `model::ModelFs` (P4, P6), safety stable under +permutation-then-sort (P2), and a last-operation precondition refusal (P4). +These are `TESTED`, not proved. diff --git a/src/kernel/plan-kernel/README.adoc b/src/kernel/plan-kernel/README.adoc new file mode 100644 index 0000000..4afbb25 --- /dev/null +++ b/src/kernel/plan-kernel/README.adoc @@ -0,0 +1,45 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += plan-kernel + +The pure decision core of a file-plan kernel. A *plan* is data: a sorted list +of file writes and deletes with preconditions and provenance, content held by +SHA-256. This crate decides, without I/O, whether a plan is well formed and +safe, how an open plan is instantiated, and — given observations of a target +directory — either a refusal or the exact list of effects. A thin binary +performs the reads and writes around it. + +* No dependency beyond `std`; `#![forbid(unsafe_code)]`. +* SHA-256 and Unicode NFC are injected through the `Prims` trait. +* Plan format: v0.1. Refusal codes: the kernel half of the closed list. +* Verification plan: `PROOF-PLAN.adoc` (Creusot with Pearlite, and Verus; + status *not run*). + +== Modules + +[cols="1,3",options="header"] +|=== +| Module | Role +| `json` | Number-free JSON value; canonical (RFC 8785) serialisation; J-1 byte check. +| `plan` | Typed plan, closed-world well-formedness, pins. +| `path` | Safe-path predicate, collision key, ancestors. +| `check` | Closed, safe, unique, collision-free; blob integrity. +| `apply` | Observations, the refuse-or-effects decision, the receipt. +| `instantiate` | Answers against holes, single-pass substitution, residue. +| `model` | In-memory target model for idempotence and all-or-nothing. +| `refusal` | Refusal codes and their wire form. +|=== + +== Location and intended home + +This crate is the candidate for the plan level of +`hyperpolymath/hybrid-automation-router` (HAR), named `har-il` in HAR +ADR-0002 and not yet built there. It is being developed first as a spike in +the Scaffoldia repository (`src/kernel/plan-kernel/`), which will later +consume it as a pinned module. + +Moving it needs nothing but its path and workspace membership: it has no +dependencies, no identifiers or error text tied to its current host, and no +build script. It deliberately does *not* depend on any HAR crate today +(`har-meta` still carries a retired A2ML module). What moves with it: this +README, `PROOF-PLAN.adoc`, and the plan format v0.1 text, which currently +lives in the host repository's conformance suite. diff --git a/src/kernel/plan-kernel/src/apply.rs b/src/kernel/plan-kernel/src/apply.rs new file mode 100644 index 0000000..d612bf5 --- /dev/null +++ b/src/kernel/plan-kernel/src/apply.rs @@ -0,0 +1,244 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! The apply decision: refuse, or the exact list of effects. +//! +//! The edge observes the target without following symbolic links and hands +//! the observations here. [`decide`] either refuses, or returns one [`Step`] +//! per operation. The edge performs the steps only after `decide` has +//! returned `Ok` for *every* operation, which is what makes a refusal write +//! nothing. +//! +//! Independence: in a checked plan no path is a directory prefix of another +//! (`check::check_paths`), and a step never removes a directory. So +//! performing one step cannot change the observation of another operation +//! except by creating an absent ancestor directory, which `decide` accepts in +//! both states. Deciding every operation against the initial observation is +//! therefore the same as deciding them in sequence. + +use crate::json::{j1, Json}; +use crate::path::ancestors; +use crate::plan::{Action, Expect, Plan}; +use crate::refusal::{Code, Refusal}; + +/// What is at a path, observed with `lstat` (links not followed). +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Node { + /// Nothing. + Absent, + /// A directory. + Dir, + /// A regular file. + File { + /// SHA-256 of its content (64 lowercase hex). + sha256: String, + /// Owner-execute bit set. + exec: bool, + }, + /// A symbolic link (not followed). + Symlink, + /// Anything else (device, FIFO, socket). + Other, +} + +/// What the target directory itself is. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum TargetRoot { + /// An existing directory (not a link). + Dir, + /// Nothing there. + Absent, + /// A symbolic link. + Symlink, + /// Something that is not a directory. + NotDir, +} + +/// Observation for one operation. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct OpObs { + /// One node per proper ancestor of the path, shortest first + /// ([`crate::path::ancestors`]). The edge may stop after the first + /// non-directory; missing trailing entries are read as `Absent`. + pub ancestors: Vec, + /// The path itself. + pub leaf: Node, +} + +/// The effect of one operation. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Effect { + /// Write the blob with this mode (via temp file and rename). + Write, + /// Remove the regular file. + Delete, + /// The target already has the desired state. + Unchanged, + /// Delete of a path that is not there. + AlreadyAbsent, +} + +impl Effect { + /// The receipt spelling. + pub fn as_str(&self) -> &'static str { + match self { + Effect::Write => "written", + Effect::Delete => "deleted", + Effect::Unchanged => "unchanged", + Effect::AlreadyAbsent => "already-absent", + } + } +} + +/// One decided step: operation index and effect. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Step { + /// Index into `plan.ops`. + pub op: usize, + /// What to do. + pub effect: Effect, +} + +/// Decide the effect of one operation, or refuse. +pub fn decide_op(plan: &Plan, i: usize, obs: &OpObs) -> Result { + let op = &plan.ops[i]; + let names = ancestors(&op.path); + for (j, node) in obs.ancestors.iter().enumerate() { + match node { + Node::Absent => break, + Node::Dir => {} + Node::Symlink => { + return Err(Refusal::new( + Code::TargetSymlink, + format!( + "ops[{i}]: ancestor {} is a symbolic link", + names.get(j).copied().unwrap_or("?") + ), + )) + } + Node::File { .. } | Node::Other => { + return Err(Refusal::new( + Code::Precondition, + format!( + "ops[{i}]: ancestor {} is not a directory", + names.get(j).copied().unwrap_or("?") + ), + )) + } + } + } + let fail = |why: &str| Err(Refusal::new(Code::Precondition, format!("ops[{i}]: {why}"))); + match (&op.action, &obs.leaf) { + (_, Node::Symlink) => Err(Refusal::new( + Code::TargetSymlink, + format!("ops[{i}]: the path is a symbolic link"), + )), + (Action::Write { blob, mode, .. }, Node::File { sha256, exec }) + if sha256 == blob && *exec == mode.is_exec() => + { + Ok(Effect::Unchanged) + } + ( + Action::Write { + expect: Expect::Absent, + .. + }, + Node::Absent, + ) => Ok(Effect::Write), + ( + Action::Write { + expect: Expect::Sha256(_), + .. + }, + Node::Absent, + ) => fail("expected existing content, but the path is absent"), + ( + Action::Write { + expect: Expect::Absent, + .. + }, + Node::File { .. }, + ) => fail("expected absent, but a file with other content is there"), + ( + Action::Write { + expect: Expect::Sha256(e), + .. + }, + Node::File { sha256, .. }, + ) => { + if e == sha256 { + Ok(Effect::Write) + } else { + fail("the file's content differs from the expected sha256") + } + } + (Action::Delete { .. }, Node::Absent) => Ok(Effect::AlreadyAbsent), + (Action::Delete { expect }, Node::File { sha256, .. }) => { + if expect == sha256 { + Ok(Effect::Delete) + } else { + fail("the file's content differs from the expected sha256") + } + } + (_, Node::Dir) => fail("a directory is at the path"), + (_, Node::Other) => fail("a special file is at the path"), + } +} + +/// Refuse, or return one step per operation, in plan order. `obs` must have +/// one entry per operation (a mismatch is refused as `TARGET_INVALID`). +pub fn decide(plan: &Plan, root: TargetRoot, obs: &[OpObs]) -> Result, Refusal> { + match root { + TargetRoot::Dir => {} + TargetRoot::Absent => { + return Err(Refusal::new( + Code::TargetInvalid, + "the target does not exist", + )) + } + TargetRoot::NotDir => { + return Err(Refusal::new( + Code::TargetInvalid, + "the target is not a directory", + )) + } + TargetRoot::Symlink => { + return Err(Refusal::new( + Code::TargetSymlink, + "the target is a symbolic link", + )) + } + } + if obs.len() != plan.ops.len() { + return Err(Refusal::new( + Code::TargetInvalid, + "internal: one observation per operation is required", + )); + } + let mut steps = Vec::with_capacity(obs.len()); + for (i, o) in obs.iter().enumerate() { + steps.push(Step { + op: i, + effect: decide_op(plan, i, o)?, + }); + } + Ok(steps) +} + +/// The receipt document: `{"ops":[{"path":...,"result":...}],"plan":"sha256:"}` +/// in J-1 form. `plan_sha256` is the SHA-256 of the plan file's bytes. +pub fn receipt(plan: &Plan, steps: &[Step], plan_sha256: &str) -> String { + let ops = steps + .iter() + .map(|s| { + Json::Obj(vec![ + ("path".into(), Json::Str(plan.ops[s.op].path.clone())), + ("result".into(), Json::Str(s.effect.as_str().into())), + ]) + }) + .collect(); + j1(&Json::Obj(vec![ + ("ops".into(), Json::Arr(ops)), + ("plan".into(), Json::Str(format!("sha256:{plan_sha256}"))), + ])) +} diff --git a/src/kernel/plan-kernel/src/check.rs b/src/kernel/plan-kernel/src/check.rs new file mode 100644 index 0000000..9178bbc --- /dev/null +++ b/src/kernel/plan-kernel/src/check.rs @@ -0,0 +1,174 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! Plan-level checks: closed, safe, blobs. +//! +//! [`check_plan`] is the whole "Check the plan" step of Apply (plan format v0.1 +//! specification): well formed, closed (when required), safe, in that order. +//! [`check_blobs`] then needs the edge to have looked at the blob directory. + +use std::collections::{BTreeMap, BTreeSet}; + +use crate::json::Json; +use crate::path::{ancestors, fold, path_fault}; +use crate::plan::{parse_plan, Action, Plan}; +use crate::refusal::{Code, Refusal}; +use crate::Prims; + +/// Path safety of a plan: every path safe; ops strictly sorted bytewise (so +/// at most one per path); no two paths equal after case folding; no path a +/// proper directory prefix of another (also after folding). +pub fn check_paths(plan: &Plan, prims: &P) -> Result<(), Refusal> { + for (i, op) in plan.ops.iter().enumerate() { + if let Some(f) = path_fault(&op.path, prims) { + return Err(Refusal::new( + Code::PathUnsafe, + format!("ops[{i}].path {}", f.describe()), + )); + } + } + for i in 1..plan.ops.len() { + let (a, b) = (&plan.ops[i - 1].path, &plan.ops[i].path); + match a.as_bytes().cmp(b.as_bytes()) { + std::cmp::Ordering::Less => {} + std::cmp::Ordering::Equal => { + return Err(Refusal::new( + Code::PathDuplicate, + format!("ops[{}] and ops[{i}] name the same path", i - 1), + )) + } + std::cmp::Ordering::Greater => { + return Err(Refusal::new( + Code::PathDuplicate, + format!("ops[{i}] is not sorted after ops[{}]", i - 1), + )) + } + } + } + let mut keys: BTreeMap = BTreeMap::new(); + for (i, op) in plan.ops.iter().enumerate() { + if let Some(j) = keys.insert(fold(&op.path), i) { + return Err(Refusal::new( + Code::PathCollision, + format!("ops[{j}] and ops[{i}] are equal after case folding"), + )); + } + } + let set: BTreeSet<&String> = keys.keys().collect(); + for (i, op) in plan.ops.iter().enumerate() { + let k = fold(&op.path); + for a in ancestors(&k) { + if set.contains(&a.to_string()) { + return Err(Refusal::new( + Code::PathCollision, + format!("ops[{i}].path lies under another planned path (file/directory clash)"), + )); + } + } + } + Ok(()) +} + +/// Well formed, then closed (when `require_closed`), then safe. +pub fn check_plan( + doc: &Json, + prims: &P, + require_closed: bool, +) -> Result { + let plan = parse_plan(doc)?; + if require_closed && !plan.holes.is_empty() { + return Err(Refusal::new( + Code::OpenPlan, + format!( + "plan has {} open hole(s); instantiate it first", + plan.holes.len() + ), + )); + } + check_paths(&plan, prims)?; + Ok(plan) +} + +/// What the edge found at `blobs/sha256/`. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum BlobObs { + /// No regular file there. + Missing, + /// A file whose content has this SHA-256 (64 lowercase hex). + Present(String), +} + +/// Distinct blob digests the plan writes, in first-use order. +pub fn blobs_needed(plan: &Plan) -> Vec { + let mut out: Vec = Vec::new(); + for op in &plan.ops { + if let Action::Write { blob, .. } = &op.action { + if !out.contains(blob) { + out.push(blob.clone()); + } + } + } + out +} + +/// Every written blob is present with the right hash. +pub fn check_blobs(plan: &Plan, found: &BTreeMap) -> Result<(), Refusal> { + for (i, op) in plan.ops.iter().enumerate() { + if let Action::Write { blob, .. } = &op.action { + match found.get(blob) { + None | Some(BlobObs::Missing) => { + return Err(Refusal::new( + Code::BlobMissing, + format!("ops[{i}] blob sha256:{blob} is absent"), + )) + } + Some(BlobObs::Present(h)) if h == blob => {} + Some(BlobObs::Present(_)) => { + return Err(Refusal::new( + Code::BlobMismatch, + format!("ops[{i}] blob sha256:{blob} has different content"), + )) + } + } + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::path::tests::TestPrims; + use crate::plan::tests::{plan_doc, write_op}; + + fn code(paths: &[&str]) -> Option { + let doc = plan_doc(paths.iter().map(|p| write_op(p)).collect()); + check_plan(&doc, &TestPrims, true).err().map(|r| r.code) + } + + #[test] + fn path_rules() { + assert_eq!(code(&["a", "b/c", "d"]), None); + assert_eq!(code(&["../a"]), Some(Code::PathUnsafe)); + assert_eq!(code(&["a", "a"]), Some(Code::PathDuplicate)); + assert_eq!(code(&["b", "a"]), Some(Code::PathDuplicate)); + assert_eq!(code(&["README", "readme"]), Some(Code::PathCollision)); + assert_eq!(code(&["docs", "docs/a"]), Some(Code::PathCollision)); + assert_eq!(code(&["DOCS", "docs/a"]), Some(Code::PathCollision)); + // `docs-x` sorts between `docs` and `docs/`, but is not a prefix clash. + assert_eq!(code(&["docs-x", "docs/a"]), None); + } + + #[test] + fn blob_rules() { + let doc = plan_doc(vec![write_op("a")]); + let p = check_plan(&doc, &TestPrims, true).unwrap(); + let h = blobs_needed(&p)[0].clone(); + let mut m = BTreeMap::new(); + assert_eq!(check_blobs(&p, &m).unwrap_err().code, Code::BlobMissing); + m.insert(h.clone(), BlobObs::Present("0".repeat(64))); + assert_eq!(check_blobs(&p, &m).unwrap_err().code, Code::BlobMismatch); + m.insert(h.clone(), BlobObs::Present(h)); + assert!(check_blobs(&p, &m).is_ok()); + } +} diff --git a/src/kernel/plan-kernel/src/instantiate.rs b/src/kernel/plan-kernel/src/instantiate.rs new file mode 100644 index 0000000..7d9696b --- /dev/null +++ b/src/kernel/plan-kernel/src/instantiate.rs @@ -0,0 +1,192 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! Instantiate: open plan to closed plan (plan format v0.1 specification, "Instantiate"). +//! +//! A *token* is `{{` NAME `}}` with NAME matching `[A-Z][A-Z0-9_]*` — the hole +//! name syntax, nothing looser. So `${{ github.sha }}` (GitHub Actions) and +//! `{{project}}` (lowercase) are not tokens and are left alone; `{{OWNER}}` +//! is a token wherever it appears, including in a Justfile (see +//! the specification's open question on delimiter collisions). +//! +//! Substitution is one left-to-right pass over the original blob: a value is +//! never rescanned, so an answer cannot expand another answer. Residue is then +//! looked for in the *result*, so a token that an answer introduces, or that +//! substitution assembles from adjacent text, is still refused. + +use std::collections::BTreeMap; + +use crate::plan::{is_hole_name, Action, Plan}; +use crate::refusal::{Code, Refusal}; +use crate::Prims; + +/// Every hole has an answer (`HOLE_UNFILLED`), and every answer names a hole +/// (`HOLE_UNKNOWN`), checked in that order. +pub fn check_answers(holes: &[String], answers: &BTreeMap) -> Result<(), Refusal> { + for h in holes { + if !answers.contains_key(h) { + return Err(Refusal::new( + Code::HoleUnfilled, + format!("hole {h} has no answer"), + )); + } + } + for k in answers.keys() { + if !holes.contains(k) { + return Err(Refusal::new( + Code::HoleUnknown, + "an answer names no hole of this plan".to_string(), + )); + } + } + Ok(()) +} + +/// If a token starts at `b[i]`, its name and the index just past `}}`. +fn token_at(b: &[u8], i: usize) -> Option<(&str, usize)> { + if !b[i..].starts_with(b"{{") { + return None; + } + let start = i + 2; + let mut end = start; + while end < b.len() + && (b[end].is_ascii_uppercase() || b[end].is_ascii_digit() || b[end] == b'_') + { + end += 1; + } + if !b[end..].starts_with(b"}}") { + return None; + } + let name = std::str::from_utf8(&b[start..end]).ok()?; + if is_hole_name(name) { + Some((name, end + 2)) + } else { + None + } +} + +/// Replace `{{NAME}}` by `answers[NAME]` for the given names only. +pub fn substitute(blob: &[u8], answers: &BTreeMap) -> Vec { + let mut out = Vec::with_capacity(blob.len()); + let mut i = 0; + while i < blob.len() { + if let Some((name, next)) = token_at(blob, i) { + if let Some(v) = answers.get(name) { + out.extend_from_slice(v.as_bytes()); + i = next; + continue; + } + } + out.push(blob[i]); + i += 1; + } + out +} + +/// The first token left in `blob`, if any. +pub fn find_residue(blob: &[u8]) -> Option { + (0..blob.len()).find_map(|i| token_at(blob, i).map(|(n, _)| n.to_string())) +} + +/// A closed plan and the blobs it needs, keyed by digest (64 lowercase hex). +pub struct Instantiated { + /// The closed plan (holes empty, blob digests recomputed). + pub plan: Plan, + /// Content of every blob the closed plan writes. + pub blobs: BTreeMap>, +} + +/// Instantiate a checked plan. `blobs` must hold every blob the plan writes +/// (the caller has run `check::check_blobs`); a missing one is `BLOB_MISSING`. +pub fn instantiate( + plan: &Plan, + answers: &BTreeMap, + blobs: &BTreeMap>, + prims: &P, +) -> Result { + check_answers(&plan.holes, answers)?; + let mut out = plan.clone(); + out.holes.clear(); + let mut out_blobs = BTreeMap::new(); + for (i, op) in out.ops.iter_mut().enumerate() { + if let Action::Write { blob, .. } = &mut op.action { + let Some(content) = blobs.get(blob.as_str()) else { + return Err(Refusal::new( + Code::BlobMissing, + format!("ops[{i}] blob sha256:{blob} is absent"), + )); + }; + let filled = substitute(content, answers); + if let Some(name) = find_residue(&filled) { + return Err(Refusal::new( + Code::Residue, + format!("ops[{i}]: token {{{{{name}}}}} remains after instantiation"), + )); + } + let h = prims.sha256_hex(&filled); + *blob = h.clone(); + out_blobs.insert(h, filled); + } + } + Ok(Instantiated { + plan: out, + blobs: out_blobs, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn answers(kv: &[(&str, &str)]) -> BTreeMap { + kv.iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + #[test] + fn substitution_is_single_pass() { + let a = answers(&[("OWNER", "{{REPO}}"), ("REPO", "r")]); + assert_eq!( + substitute(b"{{OWNER}}/{{REPO}}", &a), + b"{{REPO}}/r".to_vec() + ); + assert_eq!( + find_residue(&substitute(b"{{OWNER}}", &a)), + Some("REPO".to_string()) + ); + } + + #[test] + fn foreign_template_syntax_is_not_a_token() { + let a = answers(&[("OWNER", "o")]); + let text = b"${{ github.sha }} {{project}} {{ OWNER }} {{{OWNER}}"; + assert_eq!( + substitute(text, &a), + b"${{ github.sha }} {{project}} {{ OWNER }} {o".to_vec() + ); + assert_eq!(find_residue(b"${{ github.sha }} {{project}}"), None); + assert_eq!(find_residue(b"x {{OTHER}} y"), Some("OTHER".to_string())); + } + + #[test] + fn answers_match_holes() { + let holes = vec!["OWNER".to_string(), "REPO".to_string()]; + assert_eq!( + check_answers(&holes, &answers(&[("OWNER", "o")])) + .unwrap_err() + .code, + Code::HoleUnfilled + ); + assert_eq!( + check_answers( + &holes, + &answers(&[("OWNER", "o"), ("REPO", "r"), ("X", "x")]) + ) + .unwrap_err() + .code, + Code::HoleUnknown + ); + assert!(check_answers(&holes, &answers(&[("OWNER", "o"), ("REPO", "r")])).is_ok()); + } +} diff --git a/src/kernel/plan-kernel/src/json.rs b/src/kernel/plan-kernel/src/json.rs new file mode 100644 index 0000000..d8808a1 --- /dev/null +++ b/src/kernel/plan-kernel/src/json.rs @@ -0,0 +1,181 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! A number-free JSON value and its canonical (RFC 8785, JCS) serialisation. +//! +//! Plan format v0.1 contains no numbers, so the value type has no number +//! variant: the edge refuses any document that contains one (`MALFORMED`) +//! before it reaches the core. This removes the only hard part of JCS +//! (ECMAScript number serialisation). What remains, and what this module +//! implements, is: objects with members sorted by UTF-16 code units, no +//! insignificant whitespace, and the RFC 8785 string escaping (`"` and `\` +//! escaped; U+0008, U+0009, U+000A, U+000C, U+000D as `\b \t \n \f \r`; every +//! other C0 control as `\u00xx` with lowercase hex; everything else literal). + +use std::cmp::Ordering; + +/// A JSON value without numbers. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Json { + /// `null` + Null, + /// `true` / `false` + Bool(bool), + /// A string. + Str(String), + /// An array. + Arr(Vec), + /// An object, members in any order (the serialiser sorts them). + Obj(Vec<(String, Json)>), +} + +impl Json { + /// Member `key` of an object, if this is an object that has it. + pub fn get(&self, key: &str) -> Option<&Json> { + match self { + Json::Obj(members) => members.iter().find(|(k, _)| k == key).map(|(_, v)| v), + _ => None, + } + } + + /// The string, if this is a string. + pub fn as_str(&self) -> Option<&str> { + match self { + Json::Str(s) => Some(s), + _ => None, + } + } +} + +/// Order two member names by UTF-16 code units, as RFC 8785 §3.2.3 requires. +pub fn utf16_cmp(a: &str, b: &str) -> Ordering { + a.encode_utf16().cmp(b.encode_utf16()) +} + +/// Append the RFC 8785 serialisation of the string `s` (with quotes). +pub fn write_string(out: &mut String, s: &str) { + out.push('"'); + for c in s.chars() { + match c { + '"' => out.push_str("\\\""), + '\\' => out.push_str("\\\\"), + '\u{8}' => out.push_str("\\b"), + '\t' => out.push_str("\\t"), + '\n' => out.push_str("\\n"), + '\u{c}' => out.push_str("\\f"), + '\r' => out.push_str("\\r"), + c if (c as u32) < 0x20 => { + const HEX: &[u8; 16] = b"0123456789abcdef"; + let v = c as u32; + out.push_str("\\u00"); + out.push(HEX[(v >> 4) as usize] as char); + out.push(HEX[(v & 0xf) as usize] as char); + } + c => out.push(c), + } + } + out.push('"'); +} + +fn write_value(out: &mut String, v: &Json) { + match v { + Json::Null => out.push_str("null"), + Json::Bool(true) => out.push_str("true"), + Json::Bool(false) => out.push_str("false"), + Json::Str(s) => write_string(out, s), + Json::Arr(items) => { + out.push('['); + for (i, item) in items.iter().enumerate() { + if i > 0 { + out.push(','); + } + write_value(out, item); + } + out.push(']'); + } + Json::Obj(members) => { + let mut order: Vec<&(String, Json)> = members.iter().collect(); + order.sort_by(|a, b| utf16_cmp(&a.0, &b.0)); + out.push('{'); + for (i, (k, val)) in order.into_iter().enumerate() { + if i > 0 { + out.push(','); + } + write_string(out, k); + out.push(':'); + write_value(out, val); + } + out.push('}'); + } + } +} + +/// The canonical serialisation of `v` (no trailing line feed). +pub fn canonical(v: &Json) -> String { + let mut out = String::new(); + write_value(&mut out, v); + out +} + +/// The on-disk form the estate requires of a `.json` file (JSON-POLICY J-1): +/// the canonical serialisation followed by exactly one line feed. +pub fn j1(v: &Json) -> String { + let mut s = canonical(v); + s.push('\n'); + s +} + +/// `true` when `bytes` are exactly the J-1 form of `v`. +/// +/// Because the edge's parser keeps one member per name, a document with a +/// duplicate member name never equals the J-1 form of what was parsed, so +/// this check also enforces the I-JSON "no duplicate names" rule. +pub fn is_j1(bytes: &[u8], v: &Json) -> bool { + bytes == j1(v).as_bytes() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn s(x: &str) -> Json { + Json::Str(x.to_string()) + } + + #[test] + fn sorts_members_by_utf16() { + // U+FF61 sorts after U+1F600 in UTF-8/code point order, but before it + // in UTF-16 (0xFF61 < 0xD83D is false; 0xD83D < 0xFF61 is true). + let v = Json::Obj(vec![ + ("\u{ff61}".to_string(), s("a")), + ("\u{1f600}".to_string(), s("b")), + ("a".to_string(), s("c")), + ]); + assert_eq!( + canonical(&v), + "{\"a\":\"c\",\"\u{1f600}\":\"b\",\"\u{ff61}\":\"a\"}" + ); + } + + #[test] + fn escapes_per_rfc8785() { + let mut out = String::new(); + write_string(&mut out, "q\"b\\\u{8}\t\n\u{c}\r\u{1}\u{1f}\u{7f}é/"); + assert_eq!(out, "\"q\\\"b\\\\\\b\\t\\n\\f\\r\\u0001\\u001f\u{7f}é/\""); + } + + #[test] + fn nested_and_literals() { + let v = Json::Obj(vec![ + ( + "b".to_string(), + Json::Arr(vec![Json::Null, Json::Bool(true), Json::Bool(false)]), + ), + ("a".to_string(), Json::Obj(vec![])), + ]); + assert_eq!(canonical(&v), "{\"a\":{},\"b\":[null,true,false]}"); + assert!(is_j1(b"{\"a\":{},\"b\":[null,true,false]}\n", &v)); + assert!(!is_j1(b"{\"a\":{},\"b\":[null,true,false]}", &v)); + assert!(!is_j1(b"{\"a\": {},\"b\":[null,true,false]}\n", &v)); + } +} diff --git a/src/kernel/plan-kernel/src/lib.rs b/src/kernel/plan-kernel/src/lib.rs new file mode 100644 index 0000000..56aa05b --- /dev/null +++ b/src/kernel/plan-kernel/src/lib.rs @@ -0,0 +1,44 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! Pure decision core of a file-plan kernel (plan format v0.1). +//! +//! A *plan* is data: a sorted list of file operations with preconditions and +//! provenance, content held by SHA-256. A *kernel* checks that a plan is well +//! formed and safe, then decides, against an observed target directory, +//! either a refusal or the exact list of effects. See this crate's README for +//! where the plan format v0.1 text lives. +//! +//! Everything here is a total function over already-parsed data: no I/O, no +//! clock, no randomness, no dependency beyond `std`. The two primitives that +//! need large tables or a cryptographic implementation (Unicode NFC and +//! SHA-256) are injected through [`Prims`]; for verification they are +//! `ASSUMED` boundary specifications (see `PROOF-PLAN.adoc`). +//! +//! The pipeline the edge drives is: +//! +//! 1. [`json::is_j1`] — the bytes are the canonical (JCS) form plus one LF; +//! 2. [`plan::parse_plan`] — well-formedness, version, pins; +//! 3. [`check::check_paths`] — path safety, order, uniqueness, collisions; +//! 4. [`check::check_blobs`] — every blob present with the right hash; +//! 5. [`apply::decide`] — refuse, or the exact list of effects; +//! or [`instantiate::instantiate`] — open plan to closed plan. + +#![forbid(unsafe_code)] + +pub mod apply; +pub mod check; +pub mod instantiate; +pub mod json; +pub mod model; +pub mod path; +pub mod plan; +pub mod refusal; + +/// Primitives the core needs but does not implement. The edge provides them. +pub trait Prims { + /// `true` when `s` is in Unicode Normalization Form C. + fn is_nfc(&self, s: &str) -> bool; + /// Lowercase hexadecimal SHA-256 of `bytes` (64 characters). + fn sha256_hex(&self, bytes: &[u8]) -> String; +} diff --git a/src/kernel/plan-kernel/src/model.rs b/src/kernel/plan-kernel/src/model.rs new file mode 100644 index 0000000..d8b77a9 --- /dev/null +++ b/src/kernel/plan-kernel/src/model.rs @@ -0,0 +1,310 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! An in-memory model of a target directory, used to state and test +//! idempotence (`apply ∘ apply = apply`) and all-or-nothing, and intended as +//! the abstract state for the Creusot/Verus contracts (see `PROOF-PLAN.adoc`). +//! +//! The model is a map from safe path to node. A file is its content digest +//! and execute bit. Directories are explicit entries; links are opaque. + +use std::collections::BTreeMap; + +use crate::apply::{decide, Effect, Node, OpObs, Step, TargetRoot}; +use crate::path::ancestors; +use crate::plan::{Action, Plan}; +use crate::refusal::Refusal; + +/// A modelled target directory. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct ModelFs { + /// Entries by path. A missing key is `Absent`. + pub entries: BTreeMap, +} + +impl ModelFs { + fn node(&self, p: &str) -> Node { + self.entries.get(p).cloned().unwrap_or(Node::Absent) + } + + /// Observe the target for a plan, as the edge does with `lstat`: stop at + /// the first ancestor that is not a directory. + pub fn observe(&self, plan: &Plan) -> Vec { + plan.ops + .iter() + .map(|op| { + let mut anc = Vec::new(); + let mut blocked = false; + for a in ancestors(&op.path) { + let n = self.node(a); + blocked = n != Node::Dir; + anc.push(n); + if blocked { + break; + } + } + let leaf = if blocked { + Node::Absent + } else { + self.node(&op.path) + }; + OpObs { + ancestors: anc, + leaf, + } + }) + .collect() + } + + /// Perform decided steps (creating absent ancestors as directories). + pub fn perform(&mut self, plan: &Plan, steps: &[Step]) { + for s in steps { + let op = &plan.ops[s.op]; + match (&s.effect, &op.action) { + (Effect::Write, Action::Write { blob, mode, .. }) => { + for a in ancestors(&op.path) { + self.entries.entry(a.to_string()).or_insert(Node::Dir); + } + self.entries.insert( + op.path.clone(), + Node::File { + sha256: blob.clone(), + exec: mode.is_exec(), + }, + ); + } + (Effect::Delete, _) => { + self.entries.remove(&op.path); + } + _ => {} + } + } + } + + /// Decide and, only when every operation is accepted, perform. + pub fn apply(&mut self, plan: &Plan) -> Result, Refusal> { + let steps = decide(plan, TargetRoot::Dir, &self.observe(plan))?; + self.perform(plan, &steps); + Ok(steps) + } +} + +#[cfg(test)] +mod tests { + //! Property-style tests with a fixed-seed generator (no property-testing + //! crate: a 20-line xorshift keeps the core dependency-free and the runs + //! reproducible). + + use super::*; + use crate::check::check_plan; + use crate::path::tests::TestPrims; + use crate::plan::{plan_to_json, Expect, Input, Mode, Op, Source}; + use crate::refusal::Code; + + struct Rng(u64); + impl Rng { + fn next(&mut self) -> u64 { + let mut x = self.0; + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + self.0 = x; + x + } + fn below(&mut self, n: usize) -> usize { + (self.next() % n as u64) as usize + } + } + + const NAMES: &[&str] = &["a", "b", "B", "c.txt", "d", "e-f", "x", "z"]; + const DIGESTS: &[&str] = &[ + "0000000000000000000000000000000000000000000000000000000000000000", + "1111111111111111111111111111111111111111111111111111111111111111", + "2222222222222222222222222222222222222222222222222222222222222222", + ]; + + fn rand_path(r: &mut Rng) -> String { + let depth = 1 + r.below(3); + (0..depth) + .map(|_| NAMES[r.below(NAMES.len())]) + .collect::>() + .join("/") + } + + fn rand_digest(r: &mut Rng) -> String { + DIGESTS[r.below(DIGESTS.len())].to_string() + } + + fn rand_plan(r: &mut Rng) -> Plan { + let n = r.below(7); + let ops = (0..n) + .map(|_| { + let path = rand_path(r); + let action = if r.below(4) == 0 { + Action::Delete { + expect: rand_digest(r), + } + } else { + Action::Write { + blob: rand_digest(r), + mode: if r.below(3) == 0 { + Mode::Executable + } else { + Mode::Regular + }, + expect: if r.below(2) == 0 { + Expect::Absent + } else { + Expect::Sha256(rand_digest(r)) + }, + } + }; + Op { + source: Source { + input: "spine".into(), + path: path.clone(), + }, + path, + action, + replaces: None, + } + }) + .collect(); + Plan { + holes: vec![], + inputs: vec![Input { + name: "spine".into(), + repo: "o/r".into(), + rev: "0123456789abcdef0123456789abcdef01234567".into(), + }], + ops, + } + } + + fn rand_fs(r: &mut Rng) -> ModelFs { + let mut fs = ModelFs::default(); + for _ in 0..r.below(6) { + let p = rand_path(r); + let anc: Vec = ancestors(&p).iter().map(|s| s.to_string()).collect(); + if anc + .iter() + .any(|a| matches!(fs.entries.get(a), Some(n) if *n != Node::Dir)) + || fs.entries.contains_key(&p) + { + continue; + } + for a in anc { + fs.entries.insert(a, Node::Dir); + } + let leaf = match r.below(5) { + 0 => Node::Symlink, + 1 => Node::Dir, + _ => Node::File { + sha256: rand_digest(r), + exec: r.below(2) == 0, + }, + }; + fs.entries.insert(p, leaf); + } + fs + } + + fn sorted_dedup(mut p: Plan) -> Plan { + p.ops + .sort_by(|a, b| a.path.as_bytes().cmp(b.path.as_bytes())); + p.ops.dedup_by(|a, b| a.path == b.path); + p + } + + /// apply ∘ apply = apply, and a refusal leaves the model unchanged. + #[test] + fn idempotence_and_all_or_nothing() { + let mut r = Rng(0x9e3779b97f4a7c15); + let (mut accepted, mut refused) = (0, 0); + for _ in 0..20_000 { + let plan = sorted_dedup(rand_plan(&mut r)); + if check_plan(&plan_to_json(&plan), &TestPrims, true).is_err() { + continue; + } + let fs0 = rand_fs(&mut r); + let mut fs1 = fs0.clone(); + match fs1.apply(&plan) { + Err(_) => { + refused += 1; + assert_eq!(fs1, fs0, "a refusal changed the target"); + } + Ok(_) => { + accepted += 1; + let mut fs2 = fs1.clone(); + let steps2 = fs2.apply(&plan).expect("second application refused"); + assert_eq!(fs2, fs1, "second application changed the target"); + assert!(steps2 + .iter() + .all(|s| matches!(s.effect, Effect::Unchanged | Effect::AlreadyAbsent))); + } + } + } + // The generator must exercise both branches, or the test proves nothing. + assert!( + accepted > 1000 && refused > 1000, + "accepted {accepted}, refused {refused}" + ); + } + + /// A safe plan stays safe under permutation-then-sort, and sorting gives + /// back the same plan. + #[test] + fn safety_is_stable_under_permutation_then_sort() { + let mut r = Rng(0x2545f4914f6cdd1d); + let mut safe = 0; + for _ in 0..20_000 { + let plan = sorted_dedup(rand_plan(&mut r)); + if check_plan(&plan_to_json(&plan), &TestPrims, true).is_err() { + continue; + } + safe += 1; + let mut shuffled = plan.clone(); + for i in (1..shuffled.ops.len()).rev() { + let j = r.below(i + 1); + shuffled.ops.swap(i, j); + } + let resorted = sorted_dedup(shuffled); + assert_eq!(resorted, plan); + assert!(check_plan(&plan_to_json(&resorted), &TestPrims, true).is_ok()); + } + assert!(safe > 1000, "only {safe} safe plans generated"); + } + + /// A refusal on the last operation means nothing is performed. + #[test] + fn last_op_precondition_refuses_whole_plan() { + let mut plan = rand_plan(&mut Rng(1)); + plan.ops = ["a", "b", "c.txt"] + .iter() + .map(|p| Op { + path: p.to_string(), + action: Action::Write { + blob: DIGESTS[1].into(), + mode: Mode::Regular, + expect: Expect::Absent, + }, + source: Source { + input: "spine".into(), + path: p.to_string(), + }, + replaces: None, + }) + .collect(); + let mut fs = ModelFs::default(); + fs.entries.insert( + "c.txt".into(), + Node::File { + sha256: DIGESTS[2].into(), + exec: false, + }, + ); + let before = fs.clone(); + assert_eq!(fs.apply(&plan).unwrap_err().code, Code::Precondition); + assert_eq!(fs, before); + } +} diff --git a/src/kernel/plan-kernel/src/path.rs b/src/kernel/plan-kernel/src/path.rs new file mode 100644 index 0000000..9986087 --- /dev/null +++ b/src/kernel/plan-kernel/src/path.rs @@ -0,0 +1,192 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! Safe paths (plan format v0.1 specification, "Safe paths"). +//! +//! A path is safe when: it is non-empty and relative; its segments are +//! separated by `/`; no segment is empty, `.` or `..`; it contains no +//! backslash and no control character (NUL, C0, DEL, C1); it is in Unicode +//! NFC; and no segment is `.git` in any ASCII case (the README says "first +//! segment is not `.git`"; this kernel refuses `.git` at any depth and in any +//! case; a stricter reading than the specification text). +//! +//! A safe path, joined to a target directory, names an entry strictly inside +//! that directory: it cannot be absolute, cannot climb (`..`), and cannot be +//! re-interpreted by a separator other than `/`. + +use crate::Prims; + +/// Why a path is not safe. The first applicable fault in this order is +/// reported: empty, absolute, backslash, control, then per segment (empty, +/// `.`, `..`, `.git`), then NFC. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum PathFault { + /// The empty string. + Empty, + /// Starts with `/`. + Absolute, + /// Contains `\`. + Backslash, + /// Contains a control character. + Control(char), + /// Has an empty segment (`a//b`, trailing `/`). + EmptySegment, + /// Has a `.` segment. + DotSegment, + /// Has a `..` segment. + DotDotSegment, + /// Has a segment equal to `.git` ignoring ASCII case. + GitDir, + /// Not in Unicode NFC. + NotNfc, +} + +impl PathFault { + /// A short English description. + pub fn describe(&self) -> String { + match self { + PathFault::Empty => "empty path".to_string(), + PathFault::Absolute => "absolute path".to_string(), + PathFault::Backslash => "contains a backslash".to_string(), + PathFault::Control(c) => format!("contains control character U+{:04X}", *c as u32), + PathFault::EmptySegment => "has an empty segment".to_string(), + PathFault::DotSegment => "has a '.' segment".to_string(), + PathFault::DotDotSegment => "has a '..' segment".to_string(), + PathFault::GitDir => "has a '.git' segment".to_string(), + PathFault::NotNfc => "is not in Unicode NFC".to_string(), + } + } +} + +/// `true` for NUL, C0 controls, DEL and C1 controls (Unicode category Cc). +pub fn is_control(c: char) -> bool { + let v = c as u32; + v < 0x20 || (0x7f..=0x9f).contains(&v) +} + +/// The first fault of `p`, or `None` when `p` is safe. +pub fn path_fault(p: &str, prims: &P) -> Option { + if p.is_empty() { + return Some(PathFault::Empty); + } + if p.starts_with('/') { + return Some(PathFault::Absolute); + } + if p.contains('\\') { + return Some(PathFault::Backslash); + } + if let Some(c) = p.chars().find(|c| is_control(*c)) { + return Some(PathFault::Control(c)); + } + for seg in p.split('/') { + if seg.is_empty() { + return Some(PathFault::EmptySegment); + } + if seg == "." { + return Some(PathFault::DotSegment); + } + if seg == ".." { + return Some(PathFault::DotDotSegment); + } + if seg.eq_ignore_ascii_case(".git") { + return Some(PathFault::GitDir); + } + } + if !prims.is_nfc(p) { + return Some(PathFault::NotNfc); + } + None +} + +/// The collision key of a path: an approximation of Unicode full case folding +/// built from `std` only (`lower(upper(lower(s)))`). It maps `ß`, `ẞ` and +/// `SS` to `ss` and `K` (Kelvin) to `k`. It is not proved equal to +/// `CaseFolding.txt`; where it differs it should only merge more strings +/// (refuse more), which is the safe direction. Listed as ASSUMED in the proof +/// plan. +pub fn fold(p: &str) -> String { + p.to_lowercase().to_uppercase().to_lowercase() +} + +/// The proper directory prefixes of `p`, shortest first: +/// `a/b/c` gives `a`, `a/b`. +pub fn ancestors(p: &str) -> Vec<&str> { + p.match_indices('/').map(|(i, _)| &p[..i]).collect() +} + +#[cfg(test)] +pub(crate) mod tests { + use super::*; + + /// Test primitives: NFC is approximated as "no combining acute accent", + /// enough for the unit tests; the real oracle lives in the edge crate. + pub struct TestPrims; + impl Prims for TestPrims { + fn is_nfc(&self, s: &str) -> bool { + !s.contains('\u{301}') + } + fn sha256_hex(&self, bytes: &[u8]) -> String { + // Not SHA-256: a stable, injective-enough stand-in for tests. + let mut h: u64 = 0xcbf29ce484222325; + for b in bytes { + h ^= u64::from(*b); + h = h.wrapping_mul(0x100000001b3); + } + format!("{:064x}", h) + } + } + + #[test] + fn safe_paths() { + for p in [ + "README.adoc", + "docs/a.adoc", + ".github/workflows/x.yml", + "café.txt", + ".gitignore", + "a/.github", + ] { + assert_eq!(path_fault(p, &TestPrims), None, "{p}"); + } + } + + #[test] + fn unsafe_paths() { + let cases: &[(&str, PathFault)] = &[ + ("", PathFault::Empty), + ("/etc/passwd", PathFault::Absolute), + ("a\\b", PathFault::Backslash), + ("a\u{0}b", PathFault::Control('\u{0}')), + ("a\u{1}b", PathFault::Control('\u{1}')), + ("a\u{7f}", PathFault::Control('\u{7f}')), + ("a\u{85}", PathFault::Control('\u{85}')), + ("a//b", PathFault::EmptySegment), + ("a/", PathFault::EmptySegment), + ("./a", PathFault::DotSegment), + ("../a", PathFault::DotDotSegment), + ("a/../../b", PathFault::DotDotSegment), + (".git/config", PathFault::GitDir), + (".GIT/config", PathFault::GitDir), + ("sub/.git/hooks/pre-commit", PathFault::GitDir), + ("cafe\u{301}.txt", PathFault::NotNfc), + ]; + for (p, f) in cases { + assert_eq!(path_fault(p, &TestPrims).as_ref(), Some(f), "{p:?}"); + } + } + + #[test] + fn folding() { + assert_eq!(fold("README.adoc"), fold("readme.ADOC")); + assert_eq!(fold("stra\u{df}e"), fold("STRASSE")); + assert_eq!(fold("\u{1e9e}"), fold("ss")); + assert_eq!(fold("\u{212a}"), fold("k")); + assert_ne!(fold("a"), fold("b")); + } + + #[test] + fn ancestor_list() { + assert_eq!(ancestors("a/b/c"), vec!["a", "a/b"]); + assert!(ancestors("a").is_empty()); + } +} diff --git a/src/kernel/plan-kernel/src/plan.rs b/src/kernel/plan-kernel/src/plan.rs new file mode 100644 index 0000000..916c2a1 --- /dev/null +++ b/src/kernel/plan-kernel/src/plan.rs @@ -0,0 +1,540 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! Plan format v0.1: typed form and well-formedness. +//! +//! [`parse_plan`] is closed-world: an unknown member anywhere is `MALFORMED`, +//! because a kernel must not silently ignore a field it does not understand. +//! Order of refusals: structure (`MALFORMED`, with `PLAN_VERSION` as soon as +//! the version is read), then pins (`SOURCE_UNPINNED`). + +use crate::json::{canonical, Json}; +use crate::refusal::{Code, Refusal}; + +/// The only plan version this kernel implements. +pub const PLAN_VERSION: &str = "0.1"; + +/// A pinned source. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Input { + /// Name operations refer to. + pub name: String, + /// `owner/name` on the forge. + pub repo: String, + /// Full commit id (40 lowercase hex). + pub rev: String, +} + +/// Provenance of an operation. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Source { + /// Name of an input. + pub input: String, + /// Path inside that input. + pub path: String, +} + +/// File mode of a write. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Mode { + /// `644` + Regular, + /// `755` + Executable, +} + +impl Mode { + /// The wire spelling. + pub fn as_str(self) -> &'static str { + match self { + Mode::Regular => "644", + Mode::Executable => "755", + } + } + /// `true` for `755`. + pub fn is_exec(self) -> bool { + self == Mode::Executable + } +} + +/// Precondition of a write. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Expect { + /// Nothing is at the path. + Absent, + /// A regular file with this SHA-256 (64 lowercase hex) is at the path. + Sha256(String), +} + +/// What an operation does. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Action { + /// Write blob `blob` (64 lowercase hex, without the `sha256:` prefix). + Write { + /// Blob digest. + blob: String, + /// File mode. + mode: Mode, + /// Precondition. + expect: Expect, + }, + /// Delete a regular file whose content has this SHA-256. + Delete { + /// Precondition (never "absent"). + expect: String, + }, +} + +/// One operation. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Op { + /// Target-relative path. + pub path: String, + /// What to do. + pub action: Action, + /// Provenance. + pub source: Source, + /// Authorised replacement, when an input contract names one. + pub replaces: Option, +} + +/// A parsed plan. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Plan { + /// Open holes (empty: closed plan). + pub holes: Vec, + /// Pinned inputs. + pub inputs: Vec, + /// Operations, in file order. + pub ops: Vec, +} + +/// `true` when `s` is exactly `n` lowercase hexadecimal digits. +pub fn is_lower_hex(s: &str, n: usize) -> bool { + s.len() == n + && s.bytes() + .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) +} + +/// `true` when `s` matches `[A-Z][A-Z0-9_]*`. +pub fn is_hole_name(s: &str) -> bool { + let mut it = s.bytes(); + match it.next() { + Some(b) if b.is_ascii_uppercase() => {} + _ => return false, + } + it.all(|b| b.is_ascii_uppercase() || b.is_ascii_digit() || b == b'_') +} + +fn malformed(detail: impl Into) -> Refusal { + Refusal::new(Code::Malformed, detail) +} + +/// Members of an object, checking that every required key is present and no +/// key outside `required ∪ optional` occurs. +fn members<'a>( + v: &'a Json, + what: &str, + required: &[&str], + optional: &[&str], +) -> Result<&'a [(String, Json)], Refusal> { + let Json::Obj(ms) = v else { + return Err(malformed(format!("{what} is not an object"))); + }; + for (k, _) in ms { + if !required.contains(&k.as_str()) && !optional.contains(&k.as_str()) { + return Err(malformed(format!( + "{what} has unknown member {}", + canonical(&Json::Str(k.clone())) + ))); + } + } + for r in required { + if !ms.iter().any(|(k, _)| k == r) { + return Err(malformed(format!("{what} is missing member \"{r}\""))); + } + } + Ok(ms) +} + +fn string(v: &Json, what: &str) -> Result { + match v { + Json::Str(s) => Ok(s.clone()), + _ => Err(malformed(format!("{what} is not a string"))), + } +} + +fn field<'a>(ms: &'a [(String, Json)], key: &str) -> &'a Json { + // Callers only ask for keys `members` proved present. + ms.iter() + .find(|(k, _)| k == key) + .map(|(_, v)| v) + .unwrap_or(&Json::Null) +} + +fn source(v: &Json, what: &str) -> Result { + let ms = members(v, what, &["input", "path"], &[])?; + Ok(Source { + input: string(field(ms, "input"), &format!("{what}.input"))?, + path: string(field(ms, "path"), &format!("{what}.path"))?, + }) +} + +fn digest_field(v: &Json, what: &str) -> Result { + let ms = members(v, what, &["sha256"], &[])?; + let h = string(field(ms, "sha256"), &format!("{what}.sha256"))?; + if !is_lower_hex(&h, 64) { + return Err(malformed(format!( + "{what}.sha256 is not 64 lowercase hex digits" + ))); + } + Ok(h) +} + +fn parse_op(v: &Json, i: usize) -> Result { + let what = format!("ops[{i}]"); + let Json::Obj(_) = v else { + return Err(malformed(format!("{what} is not an object"))); + }; + let kind = match v.get("op") { + Some(Json::Str(k)) => k.clone(), + Some(_) => return Err(malformed(format!("{what}.op is not a string"))), + None => return Err(malformed(format!("{what} is missing member \"op\""))), + }; + let (ms, action) = match kind.as_str() { + "write" => { + let ms = members( + v, + &what, + &["blob", "expect", "mode", "op", "path", "source"], + &["replaces"], + )?; + let blob = string(field(ms, "blob"), &format!("{what}.blob"))?; + let blob = match blob.strip_prefix("sha256:") { + Some(h) if is_lower_hex(h, 64) => h.to_string(), + _ => { + return Err(malformed(format!( + "{what}.blob is not sha256:<64 lowercase hex>" + ))) + } + }; + let mode = match string(field(ms, "mode"), &format!("{what}.mode"))?.as_str() { + "644" => Mode::Regular, + "755" => Mode::Executable, + _ => return Err(malformed(format!("{what}.mode is not \"644\" or \"755\""))), + }; + let expect = match field(ms, "expect") { + Json::Str(s) if s == "absent" => Expect::Absent, + e @ Json::Obj(_) => Expect::Sha256(digest_field(e, &format!("{what}.expect"))?), + _ => { + return Err(malformed(format!( + "{what}.expect is neither \"absent\" nor {{\"sha256\":...}}" + ))) + } + }; + (ms, Action::Write { blob, mode, expect }) + } + "delete" => { + let ms = members(v, &what, &["expect", "op", "path", "source"], &["replaces"])?; + let expect = match field(ms, "expect") { + e @ Json::Obj(_) => digest_field(e, &format!("{what}.expect"))?, + _ => { + return Err(malformed(format!( + "{what}.expect of a delete must be {{\"sha256\":...}}" + ))) + } + }; + (ms, Action::Delete { expect }) + } + other => { + return Err(malformed(format!( + "{what}.op {} is not \"write\" or \"delete\"", + canonical(&Json::Str(other.to_string())) + ))) + } + }; + let path = string(field(ms, "path"), &format!("{what}.path"))?; + let src = source(field(ms, "source"), &format!("{what}.source"))?; + let replaces = match ms.iter().find(|(k, _)| k == "replaces") { + Some((_, r)) => Some(source(r, &format!("{what}.replaces"))?), + None => None, + }; + Ok(Op { + path, + action, + source: src, + replaces, + }) +} + +/// Parse and check a plan document. Does not check paths or blobs. +pub fn parse_plan(doc: &Json) -> Result { + let Json::Obj(_) = doc else { + return Err(malformed("plan is not an object")); + }; + match doc.get("plan_version") { + None => return Err(malformed("plan is missing member \"plan_version\"")), + Some(Json::Str(v)) if v == PLAN_VERSION => {} + Some(Json::Str(v)) => { + return Err(Refusal::new( + Code::PlanVersion, + format!( + "plan_version {} is not {PLAN_VERSION}", + canonical(&Json::Str(v.clone())) + ), + )) + } + Some(_) => return Err(malformed("plan_version is not a string")), + } + let ms = members( + doc, + "plan", + &["holes", "inputs", "ops", "plan_version"], + &[], + )?; + + let Json::Arr(hs) = field(ms, "holes") else { + return Err(malformed("holes is not an array")); + }; + let mut holes = Vec::new(); + for (i, h) in hs.iter().enumerate() { + let h = string(h, &format!("holes[{i}]"))?; + if !is_hole_name(&h) { + return Err(malformed(format!( + "holes[{i}] does not match [A-Z][A-Z0-9_]*" + ))); + } + if holes.contains(&h) { + return Err(malformed(format!("hole {h} is declared twice"))); + } + holes.push(h); + } + + let Json::Arr(is) = field(ms, "inputs") else { + return Err(malformed("inputs is not an array")); + }; + let mut inputs: Vec = Vec::new(); + for (i, v) in is.iter().enumerate() { + let what = format!("inputs[{i}]"); + let ims = members(v, &what, &["name", "repo", "rev"], &[])?; + let input = Input { + name: string(field(ims, "name"), &format!("{what}.name"))?, + repo: string(field(ims, "repo"), &format!("{what}.repo"))?, + rev: string(field(ims, "rev"), &format!("{what}.rev"))?, + }; + if input.name.is_empty() || input.repo.is_empty() { + return Err(malformed(format!("{what} has an empty name or repo"))); + } + if inputs.iter().any(|x| x.name == input.name) { + return Err(malformed(format!("{what}.name is declared twice"))); + } + inputs.push(input); + } + + let Json::Arr(os) = field(ms, "ops") else { + return Err(malformed("ops is not an array")); + }; + let ops = os + .iter() + .enumerate() + .map(|(i, v)| parse_op(v, i)) + .collect::, _>>()?; + + // Pins: every input carries a full commit id; every op names an input. + for (i, input) in inputs.iter().enumerate() { + if !is_lower_hex(&input.rev, 40) { + return Err(Refusal::new( + Code::SourceUnpinned, + format!("inputs[{i}].rev is not a full commit id (40 lowercase hex)"), + )); + } + } + for (i, op) in ops.iter().enumerate() { + for (role, s) in [ + ("source", Some(&op.source)), + ("replaces", op.replaces.as_ref()), + ] { + if let Some(s) = s { + if !inputs.iter().any(|x| x.name == s.input) { + return Err(Refusal::new( + Code::SourceUnpinned, + format!("ops[{i}].{role}.input names no declared input"), + )); + } + } + } + } + Ok(Plan { holes, inputs, ops }) +} + +/// The JSON document of a plan (for writing an instantiated plan). +pub fn plan_to_json(p: &Plan) -> Json { + fn src(s: &Source) -> Json { + Json::Obj(vec![ + ("input".into(), Json::Str(s.input.clone())), + ("path".into(), Json::Str(s.path.clone())), + ]) + } + let ops = p + .ops + .iter() + .map(|op| { + let mut ms = vec![ + ("path".to_string(), Json::Str(op.path.clone())), + ("source".to_string(), src(&op.source)), + ]; + if let Some(r) = &op.replaces { + ms.push(("replaces".into(), src(r))); + } + match &op.action { + Action::Write { blob, mode, expect } => { + ms.push(("op".into(), Json::Str("write".into()))); + ms.push(("blob".into(), Json::Str(format!("sha256:{blob}")))); + ms.push(("mode".into(), Json::Str(mode.as_str().into()))); + ms.push(( + "expect".into(), + match expect { + Expect::Absent => Json::Str("absent".into()), + Expect::Sha256(h) => { + Json::Obj(vec![("sha256".into(), Json::Str(h.clone()))]) + } + }, + )); + } + Action::Delete { expect } => { + ms.push(("op".into(), Json::Str("delete".into()))); + ms.push(( + "expect".into(), + Json::Obj(vec![("sha256".into(), Json::Str(expect.clone()))]), + )); + } + } + Json::Obj(ms) + }) + .collect(); + Json::Obj(vec![ + ( + "holes".into(), + Json::Arr(p.holes.iter().map(|h| Json::Str(h.clone())).collect()), + ), + ( + "inputs".into(), + Json::Arr( + p.inputs + .iter() + .map(|i| { + Json::Obj(vec![ + ("name".into(), Json::Str(i.name.clone())), + ("repo".into(), Json::Str(i.repo.clone())), + ("rev".into(), Json::Str(i.rev.clone())), + ]) + }) + .collect(), + ), + ), + ("ops".into(), Json::Arr(ops)), + ("plan_version".into(), Json::Str(PLAN_VERSION.into())), + ]) +} + +#[cfg(test)] +pub(crate) mod tests { + use super::*; + + pub const REV: &str = "0123456789abcdef0123456789abcdef01234567"; + pub const H1: &str = "1111111111111111111111111111111111111111111111111111111111111111"; + + pub fn s(x: &str) -> Json { + Json::Str(x.to_string()) + } + pub fn obj(ms: &[(&str, Json)]) -> Json { + Json::Obj(ms.iter().map(|(k, v)| (k.to_string(), v.clone())).collect()) + } + pub fn write_op(path: &str) -> Json { + obj(&[ + ("op", s("write")), + ("path", s(path)), + ("blob", s(&format!("sha256:{H1}"))), + ("mode", s("644")), + ("expect", s("absent")), + ("source", obj(&[("input", s("spine")), ("path", s(path))])), + ]) + } + pub fn plan_doc(ops: Vec) -> Json { + obj(&[ + ("plan_version", s("0.1")), + ("holes", Json::Arr(vec![])), + ( + "inputs", + Json::Arr(vec![obj(&[ + ("name", s("spine")), + ("repo", s("o/r")), + ("rev", s(REV)), + ])]), + ), + ("ops", Json::Arr(ops)), + ]) + } + + fn code(doc: &Json) -> Option { + parse_plan(doc).err().map(|r| r.code) + } + + #[test] + fn minimal_plan_parses_and_round_trips() { + let doc = plan_doc(vec![write_op("README.adoc")]); + let p = parse_plan(&doc).unwrap(); + assert_eq!(p.ops.len(), 1); + assert_eq!(canonical(&plan_to_json(&p)), canonical(&doc)); + } + + #[test] + fn refusals() { + assert_eq!(code(&s("x")), Some(Code::Malformed)); + let mut d = plan_doc(vec![]); + if let Json::Obj(ms) = &mut d { + ms.retain(|(k, _)| k != "ops"); + } + assert_eq!(code(&d), Some(Code::Malformed)); + let mut d = plan_doc(vec![]); + if let Json::Obj(ms) = &mut d { + ms[0].1 = s("0.2"); + } + assert_eq!(code(&d), Some(Code::PlanVersion)); + let mut d = plan_doc(vec![write_op("a")]); + if let Json::Obj(ms) = &mut d { + ms[2].1 = Json::Arr(vec![obj(&[ + ("name", s("spine")), + ("repo", s("o/r")), + ("rev", s("abc1234")), + ])]); + } + assert_eq!(code(&d), Some(Code::SourceUnpinned)); + let mut op = write_op("a"); + if let Json::Obj(ms) = &mut op { + ms[5].1 = obj(&[("input", s("other")), ("path", s("a"))]); + } + assert_eq!(code(&plan_doc(vec![op])), Some(Code::SourceUnpinned)); + let mut op = write_op("a"); + if let Json::Obj(ms) = &mut op { + ms.push(("colour".into(), s("red"))); + } + assert_eq!(code(&plan_doc(vec![op])), Some(Code::Malformed)); + let del = obj(&[ + ("op", s("delete")), + ("path", s("a")), + ("expect", s("absent")), + ("source", obj(&[("input", s("spine")), ("path", s("a"))])), + ]); + assert_eq!(code(&plan_doc(vec![del])), Some(Code::Malformed)); + } + + #[test] + fn hole_names() { + assert!(is_hole_name("OWNER")); + assert!(is_hole_name("A_1")); + assert!(!is_hole_name("owner")); + assert!(!is_hole_name("1A")); + assert!(!is_hole_name("")); + } +} diff --git a/src/kernel/plan-kernel/src/refusal.rs b/src/kernel/plan-kernel/src/refusal.rs new file mode 100644 index 0000000..efd631d --- /dev/null +++ b/src/kernel/plan-kernel/src/refusal.rs @@ -0,0 +1,110 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! The closed list of kernel refusal codes (plan format v0.1 specification, "Refusal +//! codes"). Planner-only codes are deliberately absent: a kernel never raises +//! them. + +use crate::json::{canonical, Json}; + +/// A refusal code a kernel can raise. +#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub enum Code { + /// Not a v0.1 plan, or not JCS. + Malformed, + /// A plan version this kernel does not implement. + PlanVersion, + /// An input without a full commit id, or an op naming no input. + SourceUnpinned, + /// A path that is not safe. + PathUnsafe, + /// Two operations on one path, or ops not sorted. + PathDuplicate, + /// Case-fold collision, or a file/directory prefix clash. + PathCollision, + /// Blob absent. + BlobMissing, + /// Blob present with the wrong hash. + BlobMismatch, + /// Apply was asked for a plan with holes. + OpenPlan, + /// A hole has no answer. + HoleUnfilled, + /// An answer names no hole. + HoleUnknown, + /// A `{{...}}` token survived instantiation. + Residue, + /// An `expect` does not hold on the target. + Precondition, + /// A symbolic link on the way to (or at) a planned path. + TargetSymlink, + /// The target is missing or not a directory. + TargetInvalid, +} + +impl Code { + /// The wire spelling of the code. + pub fn as_str(self) -> &'static str { + match self { + Code::Malformed => "MALFORMED", + Code::PlanVersion => "PLAN_VERSION", + Code::SourceUnpinned => "SOURCE_UNPINNED", + Code::PathUnsafe => "PATH_UNSAFE", + Code::PathDuplicate => "PATH_DUPLICATE", + Code::PathCollision => "PATH_COLLISION", + Code::BlobMissing => "BLOB_MISSING", + Code::BlobMismatch => "BLOB_MISMATCH", + Code::OpenPlan => "OPEN_PLAN", + Code::HoleUnfilled => "HOLE_UNFILLED", + Code::HoleUnknown => "HOLE_UNKNOWN", + Code::Residue => "RESIDUE", + Code::Precondition => "PRECONDITION", + Code::TargetSymlink => "TARGET_SYMLINK", + Code::TargetInvalid => "TARGET_INVALID", + } + } +} + +/// A refusal: a correct, expected outcome, not an error. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Refusal { + /// The code. + pub code: Code, + /// Human-readable detail (not part of the wire contract). + pub detail: String, +} + +impl Refusal { + /// Build a refusal. + pub fn new(code: Code, detail: impl Into) -> Self { + Refusal { + code, + detail: detail.into(), + } + } + + /// The wire form: `{"detail":"...","refused":""}` in JCS, no LF. + pub fn to_jcs(&self) -> String { + canonical(&Json::Obj(vec![ + ( + "refused".to_string(), + Json::Str(self.code.as_str().to_string()), + ), + ("detail".to_string(), Json::Str(self.detail.clone())), + ])) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn wire_form_is_sorted_and_escaped() { + let r = Refusal::new(Code::PathUnsafe, "bad \"a\u{1}b\""); + assert_eq!( + r.to_jcs(), + "{\"detail\":\"bad \\\"a\\u0001b\\\"\",\"refused\":\"PATH_UNSAFE\"}" + ); + } +} diff --git a/src/kernel/scaffoldia-kernel/Cargo.toml b/src/kernel/scaffoldia-kernel/Cargo.toml new file mode 100644 index 0000000..84274c9 --- /dev/null +++ b/src/kernel/scaffoldia-kernel/Cargo.toml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# I/O edge of the plan kernel: argument parsing, JSON parsing, hashing, NFC +# and filesystem effects. All safety decisions are delegated to the core. +[package] +name = "scaffoldia-kernel" +description = "Scaffoldia plan kernel: check, instantiate and apply plan format v0.1" +version.workspace = true +edition.workspace = true +license.workspace = true +publish.workspace = true +repository.workspace = true + +[[bin]] +name = "scaffoldia-kernel" +path = "src/main.rs" + +[dependencies] +plan-kernel = { path = "../plan-kernel" } +serde_json = "1.0" +sha2 = "0.10" +unicode-normalization = "0.1" diff --git a/src/kernel/scaffoldia-kernel/src/main.rs b/src/kernel/scaffoldia-kernel/src/main.rs new file mode 100644 index 0000000..ecb851b --- /dev/null +++ b/src/kernel/scaffoldia-kernel/src/main.rs @@ -0,0 +1,462 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +//! `scaffoldia-kernel`: the I/O edge over the pure `plan-kernel` crate. +//! +//! ```text +//! scaffoldia-kernel check --plan F --blobs D +//! scaffoldia-kernel instantiate --plan F --blobs D --answers F --out F --out-blobs D +//! scaffoldia-kernel apply --plan F --blobs D --target D --receipt F +//! ``` +//! +//! Exit 0: done. Exit 10: refused, with one JCS object (plus a line feed) on +//! standard output. Exit 1: an I/O failure (a crash). Exit 2: usage error. +//! +//! This file only reads, hashes, observes and writes. Every decision — +//! well-formedness, path safety, blob integrity, preconditions, which writes +//! happen — is made by `plan-kernel` before the first write. + +#![forbid(unsafe_code)] + +use std::collections::BTreeMap; +use std::ffi::OsString; +use std::fs; +use std::io::{ErrorKind, Write}; +use std::os::unix::fs::{MetadataExt, OpenOptionsExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::process::ExitCode; + +use plan_kernel::apply::{decide, receipt, Effect, Node, OpObs, Step, TargetRoot}; +use plan_kernel::check::{blobs_needed, check_blobs, check_plan, BlobObs}; +use plan_kernel::instantiate::instantiate; +use plan_kernel::json::{is_j1, j1, Json}; +use plan_kernel::path::ancestors; +use plan_kernel::plan::{plan_to_json, Action, Plan}; +use plan_kernel::refusal::{Code, Refusal}; +use plan_kernel::Prims; +use sha2::{Digest, Sha256}; + +/// Blob contents by digest (64 lowercase hex). +type Blobs = BTreeMap>; + +const EXIT_CRASH: u8 = 1; +const EXIT_USAGE: u8 = 2; +const EXIT_REFUSED: u8 = 10; + +const USAGE: &str = "usage: + scaffoldia-kernel check --plan F --blobs D + scaffoldia-kernel instantiate --plan F --blobs D --answers F --out F --out-blobs D + scaffoldia-kernel apply --plan F --blobs D --target D --receipt F"; + +enum Fail { + Refused(Refusal), + Crash(String), + Usage(String), +} + +impl From for Fail { + fn from(r: Refusal) -> Self { + Fail::Refused(r) + } +} + +fn crash(what: &str, p: &Path, e: std::io::Error) -> Fail { + Fail::Crash(format!("{what} {}: {e}", p.display())) +} + +/// The edge's primitives: real SHA-256 (`sha2`) and real NFC +/// (`unicode-normalization`). +struct EdgePrims; + +impl Prims for EdgePrims { + fn is_nfc(&self, s: &str) -> bool { + unicode_normalization::is_nfc(s) + } + fn sha256_hex(&self, bytes: &[u8]) -> String { + sha256_hex(bytes) + } +} + +fn sha256_hex(bytes: &[u8]) -> String { + const HEX: &[u8; 16] = b"0123456789abcdef"; + let d = Sha256::digest(bytes); + let mut s = String::with_capacity(64); + for b in d.iter() { + s.push(HEX[(b >> 4) as usize] as char); + s.push(HEX[(b & 0xf) as usize] as char); + } + s +} + +// ── arguments ─────────────────────────────────────────────────────────────── + +fn parse_args(args: &[OsString], allowed: &[&str]) -> Result, Fail> { + let mut out = BTreeMap::new(); + let mut it = args.iter(); + while let Some(flag) = it.next() { + let flag = flag.to_str().unwrap_or(""); + let Some(name) = flag.strip_prefix("--").filter(|n| allowed.contains(n)) else { + return Err(Fail::Usage(format!("unexpected argument {flag:?}"))); + }; + let Some(value) = it.next() else { + return Err(Fail::Usage(format!("--{name} needs a value"))); + }; + if out.insert(name.to_string(), PathBuf::from(value)).is_some() { + return Err(Fail::Usage(format!("--{name} given twice"))); + } + } + for a in allowed { + if !out.contains_key(*a) { + return Err(Fail::Usage(format!("--{a} is required"))); + } + } + Ok(out) +} + +// ── JSON at the edge ──────────────────────────────────────────────────────── + +fn to_json(v: serde_json::Value) -> Result { + use serde_json::Value as V; + Ok(match v { + V::Null => Json::Null, + V::Bool(b) => Json::Bool(b), + V::Number(_) => { + return Err(Refusal::new( + Code::Malformed, + "numbers do not occur in plan format v0.1", + )); + } + V::String(s) => Json::Str(s), + V::Array(a) => Json::Arr(a.into_iter().map(to_json).collect::>()?), + V::Object(m) => Json::Obj( + m.into_iter() + .map(|(k, v)| Ok((k, to_json(v)?))) + .collect::>()?, + ), + }) +} + +/// Read a JSON document that must be in J-1 form (JCS + one line feed). +fn read_j1(path: &Path, what: &str) -> Result<(Vec, Json), Fail> { + let bytes = fs::read(path).map_err(|e| crash("cannot read", path, e))?; + let value: serde_json::Value = serde_json::from_slice(&bytes) + .map_err(|e| Refusal::new(Code::Malformed, format!("{what} is not JSON: {e}")))?; + let doc = to_json(value)?; + if !is_j1(&bytes, &doc) { + return Err(Refusal::new( + Code::Malformed, + format!("{what} is not JCS-serialised followed by exactly one line feed"), + ) + .into()); + } + Ok((bytes, doc)) +} + +// ── observation (never follows symbolic links) ────────────────────────────── + +fn lstat(p: &Path) -> Result, Fail> { + match fs::symlink_metadata(p) { + Ok(m) => Ok(Some(m)), + Err(e) if e.kind() == ErrorKind::NotFound => Ok(None), + Err(e) => Err(crash("cannot inspect", p, e)), + } +} + +fn load_blobs(dir: &Path, plan: &Plan) -> Result<(BTreeMap, Blobs), Fail> { + let mut obs = BTreeMap::new(); + let mut content = BTreeMap::new(); + for h in blobs_needed(plan) { + let p = dir.join("sha256").join(&h); + match lstat(&p)? { + Some(m) if m.file_type().is_file() => { + let bytes = fs::read(&p).map_err(|e| crash("cannot read", &p, e))?; + obs.insert(h.clone(), BlobObs::Present(sha256_hex(&bytes))); + content.insert(h, bytes); + } + _ => { + obs.insert(h, BlobObs::Missing); + } + } + } + Ok((obs, content)) +} + +fn node(p: &Path, hash: bool) -> Result { + let Some(m) = lstat(p)? else { + return Ok(Node::Absent); + }; + let t = m.file_type(); + Ok(if t.is_symlink() { + Node::Symlink + } else if t.is_dir() { + Node::Dir + } else if t.is_file() && hash { + let bytes = fs::read(p).map_err(|e| crash("cannot read", p, e))?; + Node::File { + sha256: sha256_hex(&bytes), + exec: m.mode() & 0o100 != 0, + } + } else { + Node::Other + }) +} + +fn observe(target: &Path, plan: &Plan) -> Result<(TargetRoot, Vec), Fail> { + let root = match lstat(target)? { + None => TargetRoot::Absent, + Some(m) if m.file_type().is_symlink() => TargetRoot::Symlink, + Some(m) if m.file_type().is_dir() => TargetRoot::Dir, + Some(_) => TargetRoot::NotDir, + }; + if root != TargetRoot::Dir { + return Ok((root, Vec::new())); + } + let mut all = Vec::with_capacity(plan.ops.len()); + for op in &plan.ops { + let mut anc = Vec::new(); + let mut blocked = false; + for a in ancestors(&op.path) { + // An ancestor that is a file is not hashed: it is refused anyway. + let n = node(&target.join(a), false)?; + blocked = n != Node::Dir; + anc.push(n); + if blocked { + break; + } + } + let leaf = if blocked { + Node::Absent + } else { + node(&target.join(&op.path), true)? + }; + all.push(OpObs { + ancestors: anc, + leaf, + }); + } + Ok((root, all)) +} + +// ── effects ───────────────────────────────────────────────────────────────── + +/// Write `bytes` to `dest` through a fresh temporary file in the same +/// directory and a rename. The temporary is opened with `O_CREAT|O_EXCL`, so +/// it cannot be a pre-existing link; the rename replaces a directory entry +/// and never follows a link at `dest`. +fn write_atomic(dest: &Path, bytes: &[u8], mode: u32) -> Result<(), Fail> { + let dir = dest.parent().unwrap_or(Path::new(".")); + let name = dest + .file_name() + .map(|n| n.to_string_lossy().into_owned()) + .unwrap_or_default(); + let tmp = dir.join(format!( + ".{name}.plan-kernel-{}.partial", + std::process::id() + )); + let result = (|| { + let mut f = fs::OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .open(&tmp) + .map_err(|e| crash("cannot create", &tmp, e))?; + f.write_all(bytes) + .map_err(|e| crash("cannot write", &tmp, e))?; + f.set_permissions(fs::Permissions::from_mode(mode)) + .map_err(|e| crash("cannot set mode on", &tmp, e))?; + f.sync_all().map_err(|e| crash("cannot sync", &tmp, e))?; + fs::rename(&tmp, dest).map_err(|e| crash("cannot rename onto", dest, e)) + })(); + if result.is_err() { + let _ = fs::remove_file(&tmp); + } + result +} + +/// Create the missing ancestors of `rel` under `target`, one component at a +/// time, re-checking each with `lstat`: if one has become a link or a +/// non-directory since the check, stop (the plan was decided on other state). +fn ensure_dirs(target: &Path, rel: &str) -> Result<(), Fail> { + for a in ancestors(rel) { + let p = target.join(a); + match lstat(&p)? { + None => match fs::create_dir(&p) { + Ok(()) => {} + Err(e) if e.kind() == ErrorKind::AlreadyExists => { + if !matches!(lstat(&p)?, Some(m) if m.file_type().is_dir()) { + return Err(Fail::Crash(format!( + "target changed during apply at {}", + p.display() + ))); + } + } + Err(e) => return Err(crash("cannot create directory", &p, e)), + }, + Some(m) if m.file_type().is_dir() => {} + Some(_) => { + return Err(Fail::Crash(format!( + "target changed during apply at {}", + p.display() + ))) + } + } + } + Ok(()) +} + +fn perform(target: &Path, plan: &Plan, steps: &[Step], blobs: &Blobs) -> Result<(), Fail> { + for s in steps { + let op = &plan.ops[s.op]; + let dest = target.join(&op.path); + match (&s.effect, &op.action) { + (Effect::Write, Action::Write { blob, mode, .. }) => { + ensure_dirs(target, &op.path)?; + if matches!(lstat(&dest)?, Some(m) if m.file_type().is_symlink() || m.file_type().is_dir()) + { + return Err(Fail::Crash(format!( + "target changed during apply at {}", + dest.display() + ))); + } + let bytes = blobs + .get(blob) + .ok_or_else(|| Fail::Crash(format!("internal: blob {blob} not loaded")))?; + write_atomic(&dest, bytes, if mode.is_exec() { 0o755 } else { 0o644 })?; + } + (Effect::Delete, _) => match lstat(&dest)? { + Some(m) if m.file_type().is_file() => { + fs::remove_file(&dest).map_err(|e| crash("cannot delete", &dest, e))?; + } + None => {} + Some(_) => { + return Err(Fail::Crash(format!( + "target changed during apply at {}", + dest.display() + ))) + } + }, + _ => {} + } + } + Ok(()) +} + +// ── commands ──────────────────────────────────────────────────────────────── + +fn checked_plan( + a: &BTreeMap, + closed: bool, +) -> Result<(Vec, Plan, Blobs), Fail> { + let (bytes, doc) = read_j1(&a["plan"], "the plan")?; + let plan = check_plan(&doc, &EdgePrims, closed)?; + let (obs, content) = load_blobs(&a["blobs"], &plan)?; + check_blobs(&plan, &obs)?; + Ok((bytes, plan, content)) +} + +fn cmd_check(args: &[OsString]) -> Result<(), Fail> { + let a = parse_args(args, &["plan", "blobs"])?; + checked_plan(&a, false).map(|_| ()) +} + +fn cmd_instantiate(args: &[OsString]) -> Result<(), Fail> { + let a = parse_args(args, &["plan", "blobs", "answers", "out", "out-blobs"])?; + let (_, plan, content) = checked_plan(&a, false)?; + let (_, doc) = read_j1(&a["answers"], "the answers")?; + let Json::Obj(ms) = doc else { + return Err(Refusal::new(Code::Malformed, "the answers are not an object").into()); + }; + let mut answers = BTreeMap::new(); + for (k, v) in ms { + let Json::Str(v) = v else { + return Err(Refusal::new(Code::Malformed, "every answer must be a string").into()); + }; + answers.insert(k, v); + } + let done = instantiate(&plan, &answers, &content, &EdgePrims)?; + // Decided; now write. Blobs first, plan last, so a reader never sees a + // plan whose blobs are not there yet. + let sha_dir = a["out-blobs"].join("sha256"); + fs::create_dir_all(&sha_dir).map_err(|e| crash("cannot create", &sha_dir, e))?; + for (h, bytes) in &done.blobs { + write_atomic(&sha_dir.join(h), bytes, 0o644)?; + } + write_atomic(&a["out"], j1(&plan_to_json(&done.plan)).as_bytes(), 0o644) +} + +fn cmd_apply(args: &[OsString]) -> Result<(), Fail> { + let a = parse_args(args, &["plan", "blobs", "target", "receipt"])?; + let (bytes, plan, content) = checked_plan(&a, true)?; + let target = &a["target"]; + let (root, obs) = observe(target, &plan)?; + let steps = decide(&plan, root, &obs)?; + // Every operation is decided; only now does anything get written. + perform(target, &plan, &steps, &content)?; + write_atomic( + &a["receipt"], + receipt(&plan, &steps, &sha256_hex(&bytes)).as_bytes(), + 0o644, + ) +} + +fn main() -> ExitCode { + let args: Vec = std::env::args_os().skip(1).collect(); + let (cmd, rest) = match args.split_first() { + Some((c, r)) => (c.to_str().unwrap_or(""), r), + None => ("", &args[..]), + }; + let result = match cmd { + "check" => cmd_check(rest), + "instantiate" => cmd_instantiate(rest), + "apply" => cmd_apply(rest), + _ => Err(Fail::Usage(format!("unknown command {cmd:?}"))), + }; + match result { + Ok(()) => ExitCode::SUCCESS, + Err(Fail::Refused(r)) => { + println!("{}", r.to_jcs()); + eprintln!( + "scaffoldia-kernel: refused {}: {}", + r.code.as_str(), + r.detail + ); + ExitCode::from(EXIT_REFUSED) + } + Err(Fail::Crash(m)) => { + eprintln!("scaffoldia-kernel: error: {m}"); + ExitCode::from(EXIT_CRASH) + } + Err(Fail::Usage(m)) => { + eprintln!("scaffoldia-kernel: {m}\n{USAGE}"); + ExitCode::from(EXIT_USAGE) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn numbers_are_refused_at_the_edge() { + let v: serde_json::Value = serde_json::from_str(r#"{"a":[1]}"#).unwrap(); + assert_eq!(to_json(v).unwrap_err().code, Code::Malformed); + } + + #[test] + fn duplicate_names_fail_the_j1_check() { + let bytes = b"{\"a\":\"x\",\"a\":\"x\"}\n"; + let v: serde_json::Value = serde_json::from_slice(bytes).unwrap(); + assert!(!is_j1(bytes, &to_json(v).unwrap())); + } + + #[test] + fn edge_prims() { + assert_eq!( + sha256_hex(b""), + "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + ); + assert!(EdgePrims.is_nfc("caf\u{e9}")); + assert!(!EdgePrims.is_nfc("cafe\u{301}")); + } +} diff --git a/tests/e2e.sh b/tests/e2e.sh index d2dfd63..2ee4edd 100755 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -2,6 +2,13 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # +# NOT RUN BY CI since 2026-11-17, and not a merge gate. This is the inherited +# RSR template harness for the Idris2 ABI and Zig FFI seam. The owner retired +# the "E2E" CI job until Scaffoldia can mint something end to end; the required +# check is now `Conformance L0` (verification/conformance/README.adoc). Whether +# the Idris2/Zig seam stays is an open decision (docs/status/ROADMAP.adoc, P0), +# and the seam is documented as unproven (README.adoc). Needs idris2 and zig. +# # RSR Standard E2E Test Template # # End-to-end tests validate the full pipeline: build → run → verify output. @@ -11,8 +18,6 @@ # bash tests/e2e.sh # just e2e # -# Merge requirements (STANDING): All 6 test categories must pass before merge: -# P2P, E2E (this file), aspect, execution, lifecycle, benchmarks set -euo pipefail diff --git a/tests/reject/PlanLaws/Controls/Hole.agda b/tests/reject/PlanLaws/Controls/Hole.agda new file mode 100644 index 0000000..ff493f2 --- /dev/null +++ b/tests/reject/PlanLaws/Controls/Hole.agda @@ -0,0 +1,18 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- NEGATIVE CONTROL (must be refused). A law whose proof is an unfilled +-- hole. The gate refuses the hole marker; Agda refuses the unsolved +-- interaction meta. +-- EXPECT-REFUSED: gate: hole + +module PlanLaws.Controls.Hole where + +open import PlanLaws.Prelude +open import PlanLaws.Example +open import PlanLaws.Plan P _≟P_ C _≟C_ +open import PlanLaws.Join P _≟P_ C _≟C_ + +every-pair-compatible : (p q : Plan) → Compatible p q +every-pair-compatible p q = {! !} diff --git a/tests/reject/PlanLaws/Controls/LastWriterWins.agda b/tests/reject/PlanLaws/Controls/LastWriterWins.agda new file mode 100644 index 0000000..1b03ac1 --- /dev/null +++ b/tests/reject/PlanLaws/Controls/LastWriterWins.agda @@ -0,0 +1,18 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- NEGATIVE CONTROL (must be refused). A false lemma: that two packs writing +-- README.adoc differently join by last-writer-wins. The join reports a +-- conflict instead, so `refl` does not type-check. +-- EXPECT-REFUSED: agda: (conflict README-adoc != ok|!=) + +module PlanLaws.Controls.LastWriterWins where + +open import PlanLaws.Prelude +open import PlanLaws.Example +open import PlanLaws.Plan P _≟P_ C _≟C_ +open import PlanLaws.Join P _≟P_ C _≟C_ + +last-writer-wins : pack-A ⊔ pack-B ≡ ok (pack-B ∪ pack-A) +last-writer-wins = refl diff --git a/tests/reject/PlanLaws/Controls/PostulatedSafety.agda b/tests/reject/PlanLaws/Controls/PostulatedSafety.agda new file mode 100644 index 0000000..bae9895 --- /dev/null +++ b/tests/reject/PlanLaws/Controls/PostulatedSafety.agda @@ -0,0 +1,25 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- NEGATIVE CONTROL (must be refused). Assumes, by postulate, the false law +-- that a defined join of plan-safe plans is plan-safe (PlanLaws.Safety, +-- plan-safety-not-preserved, refutes it), and derives a contradiction from +-- the case-fold example. --safe refuses the postulate; the postulate scan +-- would refuse it too. +-- EXPECT-REFUSED: agda: [Cc]annot postulate + +module PlanLaws.Controls.PostulatedSafety where + +open import PlanLaws.Prelude +open import PlanLaws.Example +open import PlanLaws.Plan P _≟P_ C _≟C_ +open import PlanLaws.Join P _≟P_ C _≟C_ +open import PlanLaws.Safety P _≟P_ C _≟C_ Safe Clash clash-sym clash-irrefl + +postulate + plan-safe-join-always : (p q r : Plan) → p ⊔ q ≡ ok r → PlanSafe p → PlanSafe q → PlanSafe r + +absurd : ⊥ +absurd with case-fold-counterexample +... | sp , sq , r , e , unsafe = unsafe (plan-safe-join-always _ _ r e sp sq) diff --git a/tests/reject/PlanLaws/Controls/Terminating.agda b/tests/reject/PlanLaws/Controls/Terminating.agda new file mode 100644 index 0000000..729e583 --- /dev/null +++ b/tests/reject/PlanLaws/Controls/Terminating.agda @@ -0,0 +1,17 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- NEGATIVE CONTROL (must be refused). Proves every compatibility claim by a +-- non-terminating definition admitted with a TERMINATING pragma. The gate's +-- pragma check refuses it before Agda runs (Agda under --safe refuses the +-- pragma as well). +-- EXPECT-REFUSED: gate: pragma other than the canonical OPTIONS line + +module PlanLaws.Controls.Terminating where + +open import PlanLaws.Prelude + +{-# TERMINATING #-} +loop : ⊥ +loop = loop diff --git a/tests/reject/PlanLaws/Controls/WithK.agda b/tests/reject/PlanLaws/Controls/WithK.agda new file mode 100644 index 0000000..d9d883c --- /dev/null +++ b/tests/reject/PlanLaws/Controls/WithK.agda @@ -0,0 +1,17 @@ +{-# OPTIONS --safe --with-K #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- NEGATIVE CONTROL (must be refused). Weakens the flags in the file: its +-- OPTIONS pragma asks for K, and the file proves uniqueness of identity +-- proofs with it. The gate refuses any first line other than the canonical +-- OPTIONS pragma, before Agda runs. (Agda 2.7.0.1 refuses it too: "Cannot +-- set OPTIONS pragmas --cubical-compatible and --with-K with safe flag".) +-- EXPECT-REFUSED: gate: first line is not the canonical OPTIONS pragma + +module PlanLaws.Controls.WithK where + +open import PlanLaws.Prelude + +uip : {A : Set} {x y : A} (e e′ : x ≡ y) → e ≡ e′ +uip refl refl = refl diff --git a/verification/conformance/README.adoc b/verification/conformance/README.adoc new file mode 100644 index 0000000..464a2a4 --- /dev/null +++ b/verification/conformance/README.adoc @@ -0,0 +1,230 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Scaffoldia Conformance Suite +:toc: +:sectnums: + +Engine-neutral cases that say what a Scaffoldia kernel and a Scaffoldia planner +must do, independent of the language either is written in. This suite is the +selection gate of ADR-0002 and the acceptance evidence of ADR-0003. + +*Status:* specification v0.1 (proposed with ADR-0003). A case, runner or +engine is real only when this page's "Evidence" section records a run. + +== The two programs under test + +[cols="1,4",options="header"] +|=== +| Program | Contract +| Kernel | Checks, instantiates and applies a plan. Small, trusted, offline. +| Planner | Produces a plan from pinned inputs. Any language, untrusted. +|=== + +A *minimal engine* (Tier 0) is a kernel used with published plans. A *composer* +(Tier 1) adds a planner. Both use the plan format below. + +== Plan format v0.1 + +A plan is one I-JSON object serialised by JCS. It is internal engine output, +not an RSR document format. Content is never inline: each write names a blob by +SHA-256, held in a blob directory at `sha256/<64 lowercase hex>`. + +[source,json] +---- +{"holes":[], + "inputs":[{"name":"spine","repo":"owner/name","rev":"<40 hex>"}], + "ops":[{"blob":"sha256:<64 hex>","expect":"absent","mode":"644","op":"write", + "path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}], + "plan_version":"0.1"} +---- + +`inputs`:: The pinned sources. `rev` is a full commit id. A plan with an input +that is not pinned is refused. +`holes`:: Names (`[A-Z][A-Z0-9_]*`) a published plan leaves open. A plan with a +non-empty `holes` is _open_; with an empty one, _closed_. Only a closed plan +can be applied. +`ops`:: Sorted by `path` (bytewise), at most one per path. ++ +* `write`: `path`, `blob`, `mode` (`644` or `755`), `expect`, `source`. +* `delete`: `path`, `expect` (a `sha256`, never `absent`), `source`. ++ +`expect` is the precondition on the target: `"absent"`, or +`{"sha256":"<64 hex>"}` (the content the planner saw as the base). There is no +"overwrite whatever is there". +`source`:: `{"input": , "path": }`. Every +operation has one. A replacement authorised by an input contract also carries +`"replaces": {"input": ..., "path": ...}`. + +=== Safe paths + +A path is *safe* when all of these hold: relative; segments separated by `/`; +no empty segment, `.` or `..`; no backslash, NUL or control character; Unicode +NFC; first segment is not `.git`. A plan is *safe* when every path is safe; no +two paths are equal after case folding; and no path is a proper directory +prefix of another. + +=== Instantiate (open plan to closed plan) + +Given answers `{"NAME":"value",...}`: every hole must have an answer and every +answer must name a hole, else refuse. In each blob the token `{{NAME}}` is +replaced for declared holes only. If any `{{...}}` token remains in any blob +afterwards, refuse (`RESIDUE`): a child must not carry unfilled template text. +Output: a closed plan with recomputed blob hashes and `holes` empty. + +=== Apply + +. Check the plan (well formed, closed, safe, every blob present with the + right hash). +. Check the target: it exists and is a directory; no ancestor of any path is a + symbolic link; for each operation, either the target already has the desired + state (then the operation is a no-op), or its `expect` holds. If any check + fails, refuse and *write nothing*. +. Perform the operations. Emit a receipt (JCS): plan digest, and per path one + of `written`, `unchanged`, `deleted`, `already-absent`. + +Consequences the cases assert: applying twice gives the same tree and a +receipt of only `unchanged`/`already-absent`; a refused plan leaves the target +byte-identical. + +== Command-line protocol + +The runner is given commands; it does not care what they are written in. + +[source] +---- +KERNEL check --plan F --blobs D +KERNEL instantiate --plan F --blobs D --answers F --out F --out-blobs D +KERNEL apply --plan F --blobs D --target D --receipt F +PLANNER plan --inputs D --out F --out-blobs D +---- + +Exit `0`: done. Exit `10`: *refused*, with one JCS object on standard output, +`{"refused":"","detail":"..."}`. Any other exit is a crash and fails the +case. A refusal is a correct, expected outcome, not an error. + +Refusal codes (closed list; adding one is a format version change): + +[cols="1,3",options="header"] +|=== +| Code | Meaning +| `MALFORMED` | Not a v0.1 plan, or not JCS. +| `PLAN_VERSION` | A plan version this kernel does not implement. +| `SOURCE_UNPINNED` | An input without a full commit id, or an op naming no input. +| `PATH_UNSAFE` | A path that is not safe. +| `PATH_DUPLICATE` | Two operations on one path, or ops not sorted. +| `PATH_COLLISION` | Case-fold collision, or a file/directory prefix clash. +| `BLOB_MISSING` / `BLOB_MISMATCH` | Blob absent, or its hash is wrong. +| `OPEN_PLAN` | Apply was asked for a plan with holes. +| `HOLE_UNFILLED` / `HOLE_UNKNOWN` | Answers do not match the holes. +| `RESIDUE` | A `{{...}}` token survived instantiation. +| `PRECONDITION` | An `expect` does not hold on the target. +| `TARGET_SYMLINK` / `TARGET_INVALID` | Unsafe or missing target. +| `PIN_INVALID` | Planner: a source pin is missing, ambiguous or unresolvable. +| `CAPABILITY_UNKNOWN` | Planner: a requested capability is not in the gate table. +| `CONFLICT` | Planner: two inputs write one path differently, unauthorised. +| `LOCK_CONFLICT` | Planner: two lock fragments give one action two hashes. +| `TOOLCHAIN_MISSING` | Planner: a required tool is absent and not skippable. +|=== + +== Case layout + +---- +cases//// + case.json {"expect":{"outcome":"ok"|"refused","code":"..."},"id":..., + "kind":"check"|"instantiate"|"apply"|"apply-twice"|"plan", + "level":...,"principle":"...","source":"...","title":"..."} + plan.json blobs/ answers.json before/ expected/ inputs/ (as the kind needs) +---- + +`source` says where the case came from (an issue and item, or an ADR). +`principle` names the invariant the case instantiates. `before/` is the +starting tree, `expected/` the exact resulting tree. For `refused` cases the +runner also asserts the target is unchanged. + +Optional case fields (read by `run.sh`; additive, pending ratification with +the questions recorded alongside ADR-0003): + +`expect.results`:: For an accepted `apply` or `instantiate` case, the receipt +result per path, e.g. `{"README.adoc":"unchanged"}`. Distinguishes "already +realised" from "rewritten with the same bytes", which the tree alone cannot. +`expect.tree_excludes`:: Strings that must occur in no file of the resulting +tree (child identity: the publisher's own name). +`target`:: `"directory"` (default), `"absent"` or `"file"`: what the runner +puts at the target path, for `TARGET_INVALID` cases. + +A missing `before/` or `expected/` is an empty tree (git cannot hold an empty +directory). Accepted trees are compared on files, links and executable bits; +refused trees also on directories. Each case runs in a sandbox whose inputs +are copies and whose target has a sibling directory `outside/`; any write +outside the target, through a link or otherwise, fails the case. + +== Levels + +[cols="1,4",options="header"] +|=== +| Level | A passing engine has shown +| `L0` | Kernel safety and reference mint: every refusal above, idempotence, +all-or-nothing apply, instantiation without residue, child identity distinct +from the publisher's. +| `L1` | Composition: packs and features joined, conflicts refused, authorised +replacement recorded, lock fragments merged by action identity. +| `L2` | Retrofit: three-way against a pinned parent, unrelated user changes +preserved, conflicts stop the plan, unclassifiable content reported. +| `L3` | Sustain: every check a child inherits passes in the child, not only in +the publisher's own repository. +|=== + +A level passes only if every case at and below it passes. Skipped cases are +counted and printed as skipped; a run with skips does not pass its level. + +=== CI check + +The CI check named `Conformance L0` (`.github/workflows/e2e.yml`) runs, on every +pull request, `verification/conformance/check-l0.sh`, the same command list as +`just conformance`: the locked release build of the kernel, `gen-cases.sh --check`, +`run.sh --level L0` and `selftest.sh --level L0`. As levels are added the name +will change to the highest level passed (`Conformance L1`, and so on). No run of +this check on GitHub is recorded yet. + +== Negative control + +`controls/` holds deliberately wrong kernels (for example one that writes any +path it is given). The suite must *fail* each of them; a suite that passes a +control is itself broken, and the runner's self-test says so. + +== Evidence + +This section is updated only with a command, a commit and its output. + +=== 2026-11-17: Rust kernel spike, L0 + +Commit `35752ee` (branch `wo/KERNEL`; a local commit, so the id changes if it +is rebased). Command, from a clean `src/kernel/target/`: + +[source,bash] +---- +just conformance +# = cargo build --release --locked --manifest-path src/kernel/Cargo.toml +# verification/conformance/gen-cases.sh --check +# verification/conformance/run.sh --level L0 --kernel src/kernel/target/release/scaffoldia-kernel +# verification/conformance/selftest.sh --level L0 +---- + +Observed (exit 0; rustc 1.97.0, jq 1.7, GNU coreutils, Linux): + +---- +gen-cases: committed cases match the generator (47 cases) +L0: 47 ok, 0 FAIL, 0 SKIP +level L0: PASS (47 cases) +control naive-kernel.sh: FAILED by the suite, as required (40 of 47 cases caught it) +control no-atomicity-kernel.sh: FAILED by the suite, as required (3 of 47 cases caught it) +control refuse-all-kernel.sh: FAILED by the suite, as required (43 of 47 cases caught it) +selftest: PASS (3 controls, each failed by the suite at L0) +---- + +The no-atomicity control is caught only by `all-or-nothing` and +`target-symlink` (both leave its first write behind) and by +`residue-from-answer` (it substitutes repeatedly). Only `L0` kernel cases +exist; there are no planner cases and no `L1`–`L3` cases, so nothing is +claimed above `L0`. This is a local run, not CI. The kernel's Creusot +(Pearlite) and Verus contracts are *not run* +(`src/kernel/plan-kernel/PROOF-PLAN.adoc`). diff --git a/verification/conformance/backlog/cases-from-mint-defects.jsonl b/verification/conformance/backlog/cases-from-mint-defects.jsonl new file mode 100644 index 0000000..6acdafc --- /dev/null +++ b/verification/conformance/backlog/cases-from-mint-defects.jsonl @@ -0,0 +1,72 @@ +{"given":"pinned spine; answers owner=example-owner, repo=mint-check","id":"SC-L0-001","level":"L0","negative":false,"principle":"P1","source":"rsr-template-repo#200 item 1","then":"every `git clone` URL in the result names example-owner/mint-check (https or ssh form); no URL names another repository except inside (lineage)/(provenance) or the canon-link allowlist","when":"reference mint (no archetype)"} +{"given":"pinned spine whose root CONTRIBUTING.adoc is the spine's own contributor guide and whose docs seed carries a child contributor guide","id":"SC-L0-002","level":"L0","negative":false,"principle":"P2","source":"rsr-template-repo#200 item 1 (residue observed 2026-11-17 in a fresh mint)","then":"the result has exactly one contributor guide per role; no file outside (lineage) contains the template-only prose markers declared by the pack (e.g. 'Contributors work on the *spine*', 'the template every RSR repo is minted from')","when":"reference mint"} +{"given":"a pack file that states a count or inventory of the tree (e.g. remaining substitution tokens across files)","id":"SC-L0-003","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#200 item 2","then":"each stated count equals a recount over the result tree; no shipped allowlist entry names a file that no plan step writes (e.g. ?REQUIRES_INITIALISATION.md)","when":"reference mint"} +{"given":"pinned spine; answers repo=mint-check; spine identity uuid 8e515699-3fb9-8785-8883-ef2a100c2e02, IS 'Canonical RSR-compliant repository template'","id":"SC-L0-004","level":"L0","negative":false,"principle":"P1","source":"rsr-template-repo#201 items 1-3; #211 item 6","then":"the generated agent arrival pack (CLAUDE.md generated region) names repo mint-check, the child's :repo-uuid, forge example-owner/mint-check and the child's IS/IS-NOT/phase; it contains neither the template uuid nor the template IS/IS-NOT text","when":"reference mint"} +{"given":"answers that leave purpose and IS-NOT unknown","id":"SC-L0-005","level":"L0","negative":false,"principle":"P10","source":"rsr-template-repo#201 item 4","then":"the arrival pack renders an explicit unassigned/pending marker for each unknown field and never a value taken from the template","when":"reference mint"} +{"given":"a target deed that is header-only (no identity, ecosystem or status clauses)","id":"SC-L0-006","level":"L0","negative":true,"principle":"P1","source":"rsr-template-repo#201 AC3; #211 negative control","then":"the engine refuses (or the verifier fails loudly naming the missing clauses); no file is written carrying the template's identity","when":"generate the arrival pack"} +{"given":"a fresh child","id":"SC-L3-001","level":"L3","negative":true,"principle":"P6","source":"rsr-template-repo#201 item 2","then":"a check in the child's PR CI (not only a local recipe or pre-commit hook) fails, naming the drifted region; regenerating from the deed restores green and leaves text outside the markers byte-identical","when":"open a PR that hand-edits the generated arrival-pack region"} +{"given":"existing children whose arrival pack still carries the template identity (provenance pins older template commits)","id":"SC-L2-001","level":"L2","negative":false,"principle":"P11","source":"rsr-template-repo#201 item 5","then":"the plan lists each child with a field/hash mismatch and a regeneration diff; nothing is applied without approval; hand-authored text outside markers is preserved","when":"retrofit dry-run"} +{"given":"a source repository with a default branch and extra branches (bot work branches such as coderabbit/*)","id":"SC-L0-007","level":"L0","negative":false,"principle":"P7","source":"rsr-template-repo#203 items 3-4","then":"the plan's provenance records source repo, branch, commit and tree, and the child's branch set is exactly {default branch}","when":"mint"} +{"given":"a request to copy all source branches without an explicit multi-branch product contract","id":"SC-L0-008","level":"L0","negative":true,"principle":"P7","source":"rsr-template-repo#203 item 3","then":"the engine refuses before writing and names the extra branches","when":"mint"} +{"given":"a child holding a parentless branch whose tree equals a source-template branch tree","id":"SC-L2-002","level":"L2","negative":false,"principle":"P11","source":"rsr-template-repo#203 item 5","then":"the plan reports the branch as inherited, proposes no merge of unrelated histories and no deletion; child-local commits on it are listed as preserved","when":"retrofit dry-run"} +{"given":"the shipped Dependabot auto-merge policy and a fixture table: no GHSA; GHSA+patch+CVSS 6.9; GHSA+patch+CVSS 7.0; GHSA+major; GHSA+CVSS empty; GHSA+CVSS 'n/a'; advisory API error","id":"SC-L3-002","level":"L3","negative":false,"principle":"P9","source":"rsr-template-repo#204 AC1-AC3 (ruling D174)","then":"only the GHSA+patch/minor+CVSS<7.0 rows yield automerge; every other row yields manual review; there is no unconditional automerge path","when":"evaluate the policy decision in the child"} +{"given":"children carrying a byte-identical copy of the old unconditional dependabot-automerge.yml, and one child that edited it","id":"SC-L2-003","level":"L2","negative":false,"principle":"P11","source":"rsr-template-repo#204 (D174 propagation to ~135 children)","then":"unedited copies get a clean replacement in the plan; the edited copy yields an explicit conflict and is not overwritten; no change is applied across repos without owner approval","when":"retrofit dry-run against the pinned successor"} +{"given":"spine workflows plus an archetype that adds workflows and a lock fragment","id":"SC-L1-001","level":"L1","negative":false,"principle":"P8","source":"rsr-template-repo#205 item 1; #211 item 1","then":"every `uses:` in every result workflow has a lock record keyed by its workflow path, every record carries a resolved commit, and no lock record is dangling","when":"compose"} +{"given":"a child after a dependency bot changes a `uses:` ref","id":"SC-L3-003","level":"L3","negative":true,"principle":"P8","source":"rsr-template-repo#205 item 1","then":"either the lock was re-derived in the same change (lock gate green) or the change is not auto-mergeable; a lock-desynchronised change never reaches the default branch","when":"the child's lock gate runs"} +{"given":"pack gates whose failure text names a remediation command or script","id":"SC-L0-009","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#205 item 2","then":"every remediation command or script named by a shipped gate exists in the result and is executable","when":"reference mint"} +{"given":"julia-library archetype","id":"SC-L1-002","level":"L1","negative":false,"principle":"P8","source":"rsr-template-repo#211 items 1,3","then":"the merged actions.lock passes the forge's own lock verifier (not mere presence); every action referenced by archetype workflows is on the canonical actions allowlist","when":"compose julia-library"} +{"given":"an archetype workflow that references an action absent from the canonical actions allowlist","id":"SC-L1-003","level":"L1","negative":true,"principle":"P8","source":"rsr-template-repo#211 item 3","then":"the engine refuses with a diagnostic naming the action","when":"compose"} +{"given":"any archetype overlay that adds workflow templates","id":"SC-L1-004","level":"L1","negative":false,"principle":"P3","source":"rsr-template-repo#211 item 2","then":"every added workflow carries an SPDX header and a top-level least-privilege `permissions:` block","when":"compose"} +{"given":"pinned canon version V with criteria and gates hashes","id":"SC-L1-005","level":"L1","negative":false,"principle":"P4","source":"rsr-template-repo#211 item 4","then":"the child deed's (canon) clause carries V and both hashes exactly as the pinned canon.lock states them, and every result workflow is onboarded in actions.lock","when":"compose any archetype"} +{"given":"the julia-library archetype acceptance test","id":"SC-L1-006","level":"L1","negative":true,"principle":"P6","source":"rsr-template-repo#211 AC1 (julia e2e not wired in CI, checked 2026-11-17)","then":"the test runs with the pinned Julia toolchain and fails (never skips to green) when the toolchain is absent","when":"run in CI"} +{"given":"three children minted from the defective archetype (Protoctist.jl, EpistemicTypes.jl, ResidualEvidenceTypes.jl pattern)","id":"SC-L2-004","level":"L2","negative":false,"principle":"P11","source":"rsr-template-repo#211 'Child repair'","then":"the plan is a three-way re-derivation from the pinned parent; child edits are preserved; nothing is hand-patched outside the plan","when":"retrofit against the fixed archetype"} +{"given":"a Cargo workspace archetype whose crates keep sources under /src/","id":"SC-L1-007","level":"L1","negative":false,"principle":"P3","source":"rsr-template-repo#233 (pack fix landed; layout principle)","then":"the gate passes without a root src/ and without the child editing the allowlist","when":"compose and run the root-shape gate"} +{"given":"a pack whose exemption file and rule-order policy both describe a template-only directory the mint removes","id":"SC-L0-010","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#268","then":"no exemption names a path absent from the result, and every module the rule-order policy classifies has an exemption behind it (the two records change together)","when":"reference mint"} +{"given":"template self-tests shipped verbatim into a child","id":"SC-L3-004","level":"L3","negative":false,"principle":"P3","source":"rsr-template-repo#269 (a)","then":"each passes or self-skips with a reason naming the absent subject; no negative control is counted as a pass when its subject is absent","when":"run each in the child"} +{"given":"a README badge block written with owner/repo tokens","id":"SC-L0-011","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo#269 (b)","then":"the badge block is re-rendered with the child's owner/repo (K9 endpoint, Scorecard, Sonar) rather than dropped; a badge whose value cannot be derived (e.g. a Best Practices numeric id) is omitted with a comment","when":"reference mint"} +{"given":"pack files in normal-form dialects (KYAML, I-JSON/JCS) that contain substitution tokens","id":"SC-L0-012","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo#269 (c)","then":"for every file the substitution pass rewrote, format(file) == file under that dialect's formatter","when":"reference mint"} +{"given":"the pack's own gate set","id":"SC-L3-005","level":"L3","negative":false,"principle":"P6","source":"rsr-template-repo#269 'general lesson'","then":"the engine runs the child's gates against the result and reports success only if each is green or is listed as pending with its onboarding step","when":"the plan finishes applying"} +{"given":"a .mailmap containing one token-bearing line and non-token canonicalisation lines, and an empty alternate-email answer","id":"SC-L0-013","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo#280 item 1","then":"only the token-bearing line is removed; every non-token line is byte-preserved","when":"reference mint"} +{"given":"container recipes with a plain-OCI branch and a pipeline (ct-build) branch","id":"SC-L0-014","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#280 item 2","then":"in each branch the image reference that the run recipe starts equals the image reference the build recipe tags","when":"reference mint"} +{"given":"a pack doc that names files whose presence after mint means 'not cured'","id":"SC-L0-015","level":"L0","negative":false,"principle":"P2","source":"rsr-template-repo#280 item 3","then":"either none of those files is in the result, or the doc is not shipped; doc claims about mint behaviour agree with the plan","when":"reference mint"} +{"given":"a child whose deed declares no abi/ffi capability and which replaced the export scaffold","id":"SC-L3-006","level":"L3","negative":false,"principle":"P3","source":"rsr-template-repo#280 item 4","then":"the gate derives expected ABI/FFI files from the deed's (rsr-profile) and passes; with the capability declared and a file missing it fails naming the file","when":"run the template validation gate"} +{"given":"a fresh child with no warm caches","id":"SC-L3-007","level":"L3","negative":false,"principle":"P6","source":"rsr-template-repo#280 comment 1 (pages build)","then":"the workflow completes within its declared timeout because toolchains come from pinned prebuilt artefacts (digest-pinned image or checksummed binary), not a from-source build","when":"its site workflow runs on first push"} +{"given":"a workflow with cancel-in-progress concurrency and a job that downloads artefacts from its needs: jobs","id":"SC-L3-008","level":"L3","negative":false,"principle":"P9","source":"rsr-template-repo#280 comment 2","then":"the downstream job does not run (condition is !cancelled(), not always()); no superseded run turns red","when":"a push supersedes the run"} +{"given":"interactive answers including a service name","id":"SC-L0-016","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo#309 item 1","then":"the confirmation summary lists every answer the plan substitutes, including the service name, port and registry","when":"the engine asks for confirmation"} +{"given":"service-name answer 'y'","id":"SC-L0-017","level":"L0","negative":true,"principle":"P5","source":"rsr-template-repo#309 item 1","then":"the engine refuses the one-character name (or requires explicit confirmation of it) before writing","when":"plan"} +{"given":"a security.txt template with a Canonical field","id":"SC-L0-018","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#309 item 2","then":"the Canonical URL is one the forge serves for the child (derived from the published site root or raw-content URL), not https://github.com///.well-known/security.txt","when":"reference mint"} +{"given":"a reference mint with no archetype preset","id":"SC-L0-019","level":"L0","negative":true,"principle":"P6","source":"rsr-template-repo#309 item 3","then":"the child's (rsr-profile :capabilities) is non-empty and derived from the spine/features, or the engine fails loudly asking for a declaration; an empty set never reaches the result","when":"plan"} +{"given":"a non-Rust archetype (e.g. julia-library)","id":"SC-L1-008","level":"L1","negative":false,"principle":"P3","source":"rsr-template-repo#309 item 4","then":"language-specific workflows (rust-ci.yml) are present iff the language is in the child's declared capabilities; none is left VESTIGIAL","when":"compose"} +{"given":"a pack with analysis exclusions","id":"SC-L0-020","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#309 item 5; #420","then":"the exclusions are in the file the selected analysis mode reads (.sonarcloud.properties for automatic analysis, sonar-project.properties for the scanner), and the project key matches the child's owner_repo","when":"reference mint"} +{"given":"detectors that search for the template's own name, and historical records citing it","id":"SC-L0-021","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo#309 item 6 (confirmed 2026-11-17: guard pattern and verify-template rewritten to the child name)","then":"detector patterns still name the template (not the child), historical provenance lines are unchanged, and running each detector on the fresh child yields no finding","when":"reference mint"} +{"given":"contractiles whose declarations describe the template","id":"SC-L0-022","level":"L0","negative":false,"principle":"P2","source":"rsr-template-repo#309 item 7 (confirmed 2026-11-17: intend.k9.ncl says the child 'serves as the master template')","then":"each contractile declaration is generated from the child's deed (purpose, IS-NOT, invariants) or shipped empty and marked pending with a failing check; none states that the child is the template","when":"reference mint"} +{"given":"unknown build/test command answers","id":"SC-L0-023","level":"L0","negative":false,"principle":"P10","source":"rsr-template-repo#309 item 8","then":"no shipped code block or runnable recipe line consists of or invokes UNASSIGNED; unknown commands render as a marked TODO block","when":"reference mint"} +{"given":"pack docs that advertise recipes","id":"SC-L0-024","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#309 item 9","then":"every `just ` a shipped doc advertises exists in the result and is wired, or the doc marks it as not yet wired","when":"reference mint"} +{"given":"gated proof files in the composed result","id":"SC-L1-009","level":"L1","negative":false,"principle":"P6","source":"rsr-template-repo#309 item 10 (fixed; regression case)","then":"every import of every gated proof file is provided by a toolchain/library the result declares and pins","when":"compose"} +{"given":"canon placement rules (e.g. EXPLAINME.adoc: repository root only)","id":"SC-L0-025","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#309 item 11","then":"every shipped doc sits where the pinned canon places it and the root allowlist admits every root file the canon requires","when":"reference mint"} +{"given":"a test that scans a directory for forbidden patterns","id":"SC-L3-009","level":"L3","negative":true,"principle":"P3","source":"rsr-template-repo#309 item 12a","then":"the test reports NOT_RUN or fails; it never reports PASS over an absent target (the ABI lives in src/interface/Abi, not src/abi)","when":"the scanned directory does not exist in the child"} +{"given":"answers project-name 'Mint Check', repo 'mint-check'","id":"SC-L0-026","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo#309 item 12b (reproduced 2026-11-17: PROJECT_NAME='Mint Check' gave :project \"Mint Check\" vs :canonical-name \"mint-check\"); PR #427","then":"the deed's (manifest :project) equals :canonical-name ('mint-check'); the display name is carried elsewhere","when":"reference mint"} +{"given":"an archetype that changes the tool set relative to the spine","id":"SC-L1-010","level":"L1","negative":false,"principle":"P4","source":"rsr-template-repo#317","then":"mise.lock exists, holds no pin for an undeclared tool, keeps still-declared pins byte-identical, and the root-shape gate (mise.lock required) passes; unpinned new tools are reported, not silently accepted","when":"compose offline"} +{"given":"a denylist of private repository names from the pinned canon/registry","id":"SC-L0-027","level":"L0","negative":false,"principle":"P10","source":"rsr-template-repo#326","then":"no file in the result contains a denylisted name (including generated metadata fields such as _generated_from)","when":"reference mint"} +{"given":"children pinned at canon 2.1.3 and a parent spine pinned at 2.1.5","id":"SC-L2-005","level":"L2","negative":false,"principle":"P7","source":"rsr-template-repo#423 step 3","then":"the child's (canon) clause moves to the parent's version with hashes computed by the tooling (never hand-typed); a child pin ahead of its parent's pin is refused","when":"retrofit the canon pin"} +{"given":"spine (rsr-profile (layout …)) bindings and an archetype prune list","id":"SC-L1-011","level":"L1","negative":false,"principle":"P4","source":"rsr-template-repo PR #427","then":"a binding is carried into the child iff every path it names survives the prune; a binding naming a pruned path is dropped, never left stale","when":"compose"} +{"given":"a child minted at a pinned parent with undeclared additions, removals and divergences","id":"SC-L2-006","level":"L2","negative":false,"principle":"P7","source":"rsr-template-repo PR #434 (drift derives declarations)","then":"additions/removals collapse to the shallowest directory holding nothing of the other side, divergences are single files, an existing wrong declaration is refused by name, and judgement fields (diverged-pending-upstream) are never derived","when":"derive the variant declarations by replay"} +{"given":"recorded answers with an unknown schema version","id":"SC-L0-028","level":"L0","negative":true,"principle":"P7","source":"rsr-template-repo PR #434 (mint-answers schema)","then":"the engine refuses before minting and names the version","when":"replay or retrofit"} +{"given":"a chain mint whose parent was created without history ('Use this template')","id":"SC-L0-029","level":"L0","negative":true,"principle":"P7","source":"rsr-template-repo PR #434 (chain parent commit)","then":"the parent commit is resolved by tree equality and recorded in provenance; if unresolvable the engine stops before writing (an explicit unpinned override records UNASSIGNED)","when":"mint"} +{"given":"canon-owned vendored files with a pin (source repo, commit, sha256 per file)","id":"SC-L3-010","level":"L3","negative":false,"principle":"P11","source":"rsr-template-repo PR #431 (ADR 0004 vendored proof cores)","then":"a hand edit or missing file fails; a stale pin is reported; propagating a canon fix produces a reviewable plan, never a hand repeat","when":"run the vendor check in the child"} +{"given":"repo slug '3d-thing' (becomes the FFI export prefix)","id":"SC-L0-030","level":"L0","negative":true,"principle":"P5","source":"rsr-template-repo PR #421 item 6c","then":"the engine refuses the digit-led slug before writing and says why","when":"plan"} +{"given":"a child that inherits a required status context","id":"SC-L3-011","level":"L3","negative":false,"principle":"P6","source":"rsr-template-repo PR #433; mathesis PR #106; scaffoldia branch rules ('CI / gate', 'scan / gitleaks' required but not emitted, checked 2026-11-17)","then":"a producer for every required context exists and runs in the child, or the plan records the context as onboarding-pending and the child's ruleset does not yet require it","when":"its first PR runs"} +{"given":"a canon version, spine ref or archetype ref that is missing, a moving branch name, or ambiguous","id":"SC-A-001","level":"L0","negative":true,"principle":"P7","source":"scaffoldia ADR-0002 (bad pin)","then":"the engine refuses before producing a plan and names the unpinned input","when":"resolve the source snapshot"} +{"given":"a requested capability or feature not in the pinned canon gate table","id":"SC-A-002","level":"L1","negative":true,"principle":"P4","source":"scaffoldia ADR-0002 (unknown capability)","then":"hard diagnostic naming the capability; no plan is produced","when":"plan"} +{"given":"a pack or overlay entry whose target path is absolute, contains '..', resolves through a symlink outside the target root, or collides by case with another entry","id":"SC-A-003","level":"L0","negative":true,"principle":"P12","source":"scaffoldia ADR-0002 (path traversal)","then":"the engine refuses and names the entry; nothing is written outside the target root","when":"plan"} +{"given":"two lock fragments mapping the same action@ref to different commits","id":"SC-A-004","level":"L1","negative":true,"principle":"P8","source":"scaffoldia ADR-0002 (conflicting lock entry)","then":"the engine refuses naming both fragments; identical entries merge once","when":"compose"} +{"given":"a plan step that needs a tool (e.g. nickel, a KYAML-capable yq) absent from the environment","id":"SC-A-005","level":"L0","negative":true,"principle":"P6","source":"scaffoldia ADR-0002 (missing toolchain)","then":"the engine fails before writing and names the tool and pinned version; no gate is reported green after a skipped required tool","when":"apply"} +{"given":"a completed apply of plan P to target T","id":"SC-A-006","level":"L0","negative":true,"principle":"P12","source":"scaffoldia ADR-0002 (non-idempotent application)","then":"the second apply changes no byte and reports zero operations; a plan whose re-application would change bytes is refused","when":"apply P to T again"} +{"given":"identical pinned inputs","id":"SC-A-007","level":"L0","negative":false,"principle":"P7","source":"scaffoldia ADR-0002 (determinism)","then":"the two plans and resulting trees are byte-identical (dates come from inputs, not the clock)","when":"plan twice (different machines, clocks, locales)"} +{"given":"a target that edited a file the successor also changes","id":"SC-A-008","level":"L2","negative":true,"principle":"P11","source":"scaffoldia ADR-0002 (retrofit conflict)","then":"the plan stops with an explicit conflict for that file; unrelated user changes are preserved; no silent last-writer-wins","when":"three-way retrofit dry-run against the pinned base"} +{"given":"a plan that would change forge settings (visibility, rename, protections)","id":"SC-A-009","level":"L2","negative":true,"principle":"P9","source":"scaffoldia ADR-0002 (forge mutations)","then":"forge operations are not executed and are reported as pending approval","when":"apply without an explicit operator approval"} +{"given":"a target whose licence files or SPDX lines differ from the successor","id":"SC-A-010","level":"L2","negative":false,"principle":"P9","source":"scaffoldia ADR-0002 (licence flag-only)","then":"the plan flags the difference for owner review and contains no operation that edits an existing licence file or SPDX line","when":"retrofit"} +{"given":"an answer containing a newline or a control byte (0x01)","id":"SC-T-001","level":"L0","negative":true,"principle":"P5","source":"rsr-template-repo tests/e2e/use_template_mint_test.sh (existing negative controls)","then":"refused before anything is written","when":"plan"} +{"given":"an answer containing '&' and '|'","id":"SC-T-002","level":"L0","negative":false,"principle":"P5","source":"rsr-template-repo tests/e2e/use_template_mint_test.sh (existing control)","then":"the answer renders literally in every substituted file","when":"reference mint"} +{"given":"a source tree carrying a submodule (gitlink)","id":"SC-T-003","level":"L0","negative":true,"principle":"P7","source":"rsr-template-repo tests/e2e/use_template_mint_test.sh (existing controls)","then":"refused by name, not replayed inexactly","when":"mint or replay"} +{"given":"a generated map of the repository","id":"SC-T-004","level":"L0","negative":false,"principle":"P4","source":"rsr-template-repo tests/e2e/use_template_mint_test.sh (existing control); #269 (a)","then":"the committed map equals a regeneration from the committed tree (not from a stale index)","when":"reference mint"} diff --git a/verification/conformance/cases/.gitattributes b/verification/conformance/cases/.gitattributes new file mode 100644 index 0000000..e09c380 --- /dev/null +++ b/verification/conformance/cases/.gitattributes @@ -0,0 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 +# Case fixtures are compared byte for byte (blob hashes, before/, expected/): +# never let git rewrite line endings in them. +* -text diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/before/c.txt b/verification/conformance/cases/kernel/L0/all-or-nothing/before/c.txt new file mode 100644 index 0000000..da1609e --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/before/c.txt @@ -0,0 +1 @@ +the user wrote this diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/480c2336b410f1ad5f8bf1b28944490255804b65350c527787e74ebdd511e3a4 b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/480c2336b410f1ad5f8bf1b28944490255804b65350c527787e74ebdd511e3a4 new file mode 100644 index 0000000..e019be0 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/480c2336b410f1ad5f8bf1b28944490255804b65350c527787e74ebdd511e3a4 @@ -0,0 +1 @@ +second diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/5eef8098ed6ec0a16249fc7c12422027fc9fd75b16130cc9382cf09102014796 b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/5eef8098ed6ec0a16249fc7c12422027fc9fd75b16130cc9382cf09102014796 new file mode 100644 index 0000000..234496b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/5eef8098ed6ec0a16249fc7c12422027fc9fd75b16130cc9382cf09102014796 @@ -0,0 +1 @@ +third diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/b640e840b19d378660b32fb51ae18d67dccb4a8596a29e7bd72c1b2ae5928f41 b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/b640e840b19d378660b32fb51ae18d67dccb4a8596a29e7bd72c1b2ae5928f41 new file mode 100644 index 0000000..9c59e24 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/blobs/sha256/b640e840b19d378660b32fb51ae18d67dccb4a8596a29e7bd72c1b2ae5928f41 @@ -0,0 +1 @@ +first diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/case.json b/verification/conformance/cases/kernel/L0/all-or-nothing/case.json new file mode 100644 index 0000000..5f4f6c3 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"all-or-nothing","kind":"apply","level":"L0","principle":"All or nothing: a refused plan leaves the target byte-identical, including the first operations","source":"conformance README, Apply","title":"The last operation fails its precondition"} diff --git a/verification/conformance/cases/kernel/L0/all-or-nothing/plan.json b/verification/conformance/cases/kernel/L0/all-or-nothing/plan.json new file mode 100644 index 0000000..5a4231b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/all-or-nothing/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:b640e840b19d378660b32fb51ae18d67dccb4a8596a29e7bd72c1b2ae5928f41","expect":"absent","mode":"644","op":"write","path":"a.txt","source":{"input":"spine","path":"a.txt"}},{"blob":"sha256:480c2336b410f1ad5f8bf1b28944490255804b65350c527787e74ebdd511e3a4","expect":"absent","mode":"755","op":"write","path":"b/b.txt","source":{"input":"spine","path":"b/b.txt"}},{"blob":"sha256:5eef8098ed6ec0a16249fc7c12422027fc9fd75b16130cc9382cf09102014796","expect":"absent","mode":"644","op":"write","path":"c.txt","source":{"input":"spine","path":"c.txt"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/already-realised/before/README.adoc b/verification/conformance/cases/kernel/L0/already-realised/before/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/before/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/already-realised/case.json b/verification/conformance/cases/kernel/L0/already-realised/case.json new file mode 100644 index 0000000..c899310 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"unchanged","docs/index.adoc":"written"}},"id":"already-realised","kind":"apply","level":"L0","principle":"A write whose desired state already holds is a no-op even though expect says absent","source":"conformance README, Apply","title":"A path that already has the desired content is unchanged"} diff --git a/verification/conformance/cases/kernel/L0/already-realised/expected/README.adoc b/verification/conformance/cases/kernel/L0/already-realised/expected/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/expected/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/already-realised/expected/docs/index.adoc b/verification/conformance/cases/kernel/L0/already-realised/expected/docs/index.adoc new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/expected/docs/index.adoc @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/already-realised/plan.json b/verification/conformance/cases/kernel/L0/already-realised/plan.json new file mode 100644 index 0000000..081e346 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/already-realised/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/keep.txt b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/old.txt b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/old.txt new file mode 100644 index 0000000..6e263ab --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/before/old.txt @@ -0,0 +1 @@ +obsolete diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c new file mode 100644 index 0000000..e37f89b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c @@ -0,0 +1,2 @@ +#!/bin/sh +echo ok diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/case.json b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/case.json new file mode 100644 index 0000000..59d9894 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"written","docs/index.adoc":"written","old.txt":"deleted","scripts/run.sh":"written"}},"id":"apply-twice-idempotent","kind":"apply-twice","level":"L0","principle":"Idempotence: the second application leaves the tree identical and reports only unchanged/already-absent","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"Applying a plan twice equals applying it once"} diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/README.adoc b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/docs/index.adoc b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/docs/index.adoc new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/docs/index.adoc @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/keep.txt b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/scripts/run.sh b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/scripts/run.sh new file mode 100755 index 0000000..e37f89b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/expected/scripts/run.sh @@ -0,0 +1,2 @@ +#!/bin/sh +echo ok diff --git a/verification/conformance/cases/kernel/L0/apply-twice-idempotent/plan.json b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/plan.json new file mode 100644 index 0000000..7acf356 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/apply-twice-idempotent/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}},{"expect":{"sha256":"abdcccf4a6a5fae3da2c8232d6fbf33b61d5db886742c35218e724b8e5c6b0e0"},"op":"delete","path":"old.txt","source":{"input":"spine","path":"old.txt"}},{"blob":"sha256:b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c","expect":"absent","mode":"755","op":"write","path":"scripts/run.sh","source":{"input":"spine","path":"scripts/run.sh"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/blob-mismatch/before/keep.txt b/verification/conformance/cases/kernel/L0/blob-mismatch/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-mismatch/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/blob-mismatch/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/blob-mismatch/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..f1cb313 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-mismatch/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1 @@ +tampered diff --git a/verification/conformance/cases/kernel/L0/blob-mismatch/case.json b/verification/conformance/cases/kernel/L0/blob-mismatch/case.json new file mode 100644 index 0000000..569a63c --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-mismatch/case.json @@ -0,0 +1 @@ +{"expect":{"code":"BLOB_MISMATCH","outcome":"refused"},"id":"blob-mismatch","kind":"apply","level":"L0","principle":"Content is addressed by SHA-256 and checked before use","source":"conformance README, Plan format v0.1","title":"A blob whose content does not match its name"} diff --git a/verification/conformance/cases/kernel/L0/blob-mismatch/plan.json b/verification/conformance/cases/kernel/L0/blob-mismatch/plan.json new file mode 100644 index 0000000..7d749d7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-mismatch/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/blob-missing/before/keep.txt b/verification/conformance/cases/kernel/L0/blob-missing/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-missing/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/blob-missing/case.json b/verification/conformance/cases/kernel/L0/blob-missing/case.json new file mode 100644 index 0000000..fe243ce --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-missing/case.json @@ -0,0 +1 @@ +{"expect":{"code":"BLOB_MISSING","outcome":"refused"},"id":"blob-missing","kind":"apply","level":"L0","principle":"Content is never inline and never fetched: every blob is present","source":"conformance README, Plan format v0.1","title":"A write whose blob is absent"} diff --git a/verification/conformance/cases/kernel/L0/blob-missing/plan.json b/verification/conformance/cases/kernel/L0/blob-missing/plan.json new file mode 100644 index 0000000..7d749d7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/blob-missing/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/check-open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 b/verification/conformance/cases/kernel/L0/check-open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 new file mode 100644 index 0000000..cc347d6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 @@ -0,0 +1 @@ += Repository of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/check-open-plan/case.json b/verification/conformance/cases/kernel/L0/check-open-plan/case.json new file mode 100644 index 0000000..ae94248 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-open-plan/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok"},"id":"check-open-plan","kind":"check","level":"L0","principle":"An open plan is a valid plan; only apply requires it closed","source":"conformance README, Plan format v0.1","title":"check accepts a well-formed open plan"} diff --git a/verification/conformance/cases/kernel/L0/check-open-plan/plan.json b/verification/conformance/cases/kernel/L0/check-open-plan/plan.json new file mode 100644 index 0000000..813bcad --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-open-plan/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/check-path-unsafe/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/check-path-unsafe/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-path-unsafe/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/check-path-unsafe/case.json b/verification/conformance/cases/kernel/L0/check-path-unsafe/case.json new file mode 100644 index 0000000..d82893e --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-path-unsafe/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"check-path-unsafe","kind":"check","level":"L0","principle":"check applies the same safety rules as apply","source":"conformance README, Safe paths","title":"check refuses an unsafe path"} diff --git a/verification/conformance/cases/kernel/L0/check-path-unsafe/plan.json b/verification/conformance/cases/kernel/L0/check-path-unsafe/plan.json new file mode 100644 index 0000000..0accdcd --- /dev/null +++ b/verification/conformance/cases/kernel/L0/check-path-unsafe/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"../README.adoc","source":{"input":"spine","path":"../README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/child-identity/answers.json b/verification/conformance/cases/kernel/L0/child-identity/answers.json new file mode 100644 index 0000000..0619f70 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/answers.json @@ -0,0 +1 @@ +{"OWNER":"example-org","REPO":"example-child"} diff --git a/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/58b98a1e7d6412c4eb648f3ff7ad7d74a032e483ad4d2ddebc6578179b8b83ce b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/58b98a1e7d6412c4eb648f3ff7ad7d74a032e483ad4d2ddebc6578179b8b83ce new file mode 100644 index 0000000..f8f0fdd --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/58b98a1e7d6412c4eb648f3ff7ad7d74a032e483ad4d2ddebc6578179b8b83ce @@ -0,0 +1,3 @@ += {{REPO}} + +A repository of {{OWNER}}, minted from a published plan. diff --git a/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/7bbe8b37e8b5e60e92d8bc5f148fdfe2d39b38a01c2da24b1e37e0eb072cfe40 b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/7bbe8b37e8b5e60e92d8bc5f148fdfe2d39b38a01c2da24b1e37e0eb072cfe40 new file mode 100644 index 0000000..2b9dd67 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/7bbe8b37e8b5e60e92d8bc5f148fdfe2d39b38a01c2da24b1e37e0eb072cfe40 @@ -0,0 +1 @@ +CI note: at run time the identity comes from ${{ github.repository }} diff --git a/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/ee02f065782fbe594b6a57d2476228ee492dde41d9642864bf4322db59ff25f1 b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/ee02f065782fbe594b6a57d2476228ee492dde41d9642864bf4322db59ff25f1 new file mode 100644 index 0000000..9000a82 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/blobs/sha256/ee02f065782fbe594b6a57d2476228ee492dde41d9642864bf4322db59ff25f1 @@ -0,0 +1,2 @@ +forge: github.com/{{OWNER}}/{{REPO}} +name: {{REPO}} diff --git a/verification/conformance/cases/kernel/L0/child-identity/case.json b/verification/conformance/cases/kernel/L0/child-identity/case.json new file mode 100644 index 0000000..115816f --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","tree_excludes":["rsr-template-repo","hyperpolymath"]},"id":"child-identity","kind":"instantiate","level":"L0","principle":"Child identity is distinct from the publisher's: the publisher's own name appears nowhere in the child","source":"ADR-0002, Safety invariants (child identity); ADR-0003, Tier 0","title":"A child minted from a published plan carries its own identity"} diff --git a/verification/conformance/cases/kernel/L0/child-identity/expected/README.adoc b/verification/conformance/cases/kernel/L0/child-identity/expected/README.adoc new file mode 100644 index 0000000..5d3bcd3 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/expected/README.adoc @@ -0,0 +1,3 @@ += example-child + +A repository of example-org, minted from a published plan. diff --git a/verification/conformance/cases/kernel/L0/child-identity/expected/docs/ci-note.txt b/verification/conformance/cases/kernel/L0/child-identity/expected/docs/ci-note.txt new file mode 100644 index 0000000..2b9dd67 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/expected/docs/ci-note.txt @@ -0,0 +1 @@ +CI note: at run time the identity comes from ${{ github.repository }} diff --git a/verification/conformance/cases/kernel/L0/child-identity/expected/identity.txt b/verification/conformance/cases/kernel/L0/child-identity/expected/identity.txt new file mode 100644 index 0000000..01fb719 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/expected/identity.txt @@ -0,0 +1,2 @@ +forge: github.com/example-org/example-child +name: example-child diff --git a/verification/conformance/cases/kernel/L0/child-identity/plan.json b/verification/conformance/cases/kernel/L0/child-identity/plan.json new file mode 100644 index 0000000..3c24945 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/child-identity/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER","REPO"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:58b98a1e7d6412c4eb648f3ff7ad7d74a032e483ad4d2ddebc6578179b8b83ce","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:7bbe8b37e8b5e60e92d8bc5f148fdfe2d39b38a01c2da24b1e37e0eb072cfe40","expect":"absent","mode":"644","op":"write","path":"docs/ci-note.txt","source":{"input":"spine","path":"docs/ci-note.txt"}},{"blob":"sha256:ee02f065782fbe594b6a57d2476228ee492dde41d9642864bf4322db59ff25f1","expect":"absent","mode":"644","op":"write","path":"identity.txt","source":{"input":"spine","path":"identity.txt"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/delete-already-absent/before/keep.txt b/verification/conformance/cases/kernel/L0/delete-already-absent/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/delete-already-absent/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/delete-already-absent/case.json b/verification/conformance/cases/kernel/L0/delete-already-absent/case.json new file mode 100644 index 0000000..ce656ce --- /dev/null +++ b/verification/conformance/cases/kernel/L0/delete-already-absent/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"gone.txt":"already-absent"}},"id":"delete-already-absent","kind":"apply","level":"L0","principle":"A delete whose desired state (absent) already holds reports already-absent","source":"conformance README, Apply","title":"Deleting a path that is not there is a no-op"} diff --git a/verification/conformance/cases/kernel/L0/delete-already-absent/expected/keep.txt b/verification/conformance/cases/kernel/L0/delete-already-absent/expected/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/delete-already-absent/expected/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/delete-already-absent/plan.json b/verification/conformance/cases/kernel/L0/delete-already-absent/plan.json new file mode 100644 index 0000000..90d8612 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/delete-already-absent/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"expect":{"sha256":"458417e207076307e3f131d19bf5f67c6423a3298beb4af6a196f61849ae0157"},"op":"delete","path":"gone.txt","source":{"input":"spine","path":"gone.txt"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/hole-unfilled/answers.json b/verification/conformance/cases/kernel/L0/hole-unfilled/answers.json new file mode 100644 index 0000000..b62e25f --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unfilled/answers.json @@ -0,0 +1 @@ +{"OWNER":"alice"} diff --git a/verification/conformance/cases/kernel/L0/hole-unfilled/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 b/verification/conformance/cases/kernel/L0/hole-unfilled/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 new file mode 100644 index 0000000..8f0f4f9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unfilled/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 @@ -0,0 +1 @@ += {{REPO}} of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/hole-unfilled/case.json b/verification/conformance/cases/kernel/L0/hole-unfilled/case.json new file mode 100644 index 0000000..bd59344 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unfilled/case.json @@ -0,0 +1 @@ +{"expect":{"code":"HOLE_UNFILLED","outcome":"refused"},"id":"hole-unfilled","kind":"instantiate","level":"L0","principle":"Every hole must have an answer","source":"conformance README, Instantiate","title":"A hole without an answer"} diff --git a/verification/conformance/cases/kernel/L0/hole-unfilled/plan.json b/verification/conformance/cases/kernel/L0/hole-unfilled/plan.json new file mode 100644 index 0000000..d7ea343 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unfilled/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER","REPO"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/hole-unknown/answers.json b/verification/conformance/cases/kernel/L0/hole-unknown/answers.json new file mode 100644 index 0000000..700550b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unknown/answers.json @@ -0,0 +1 @@ +{"OWNER":"alice","REPO":"widget"} diff --git a/verification/conformance/cases/kernel/L0/hole-unknown/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 b/verification/conformance/cases/kernel/L0/hole-unknown/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 new file mode 100644 index 0000000..cc347d6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unknown/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 @@ -0,0 +1 @@ += Repository of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/hole-unknown/case.json b/verification/conformance/cases/kernel/L0/hole-unknown/case.json new file mode 100644 index 0000000..3821646 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unknown/case.json @@ -0,0 +1 @@ +{"expect":{"code":"HOLE_UNKNOWN","outcome":"refused"},"id":"hole-unknown","kind":"instantiate","level":"L0","principle":"Every answer must name a hole","source":"conformance README, Instantiate","title":"An answer that names no hole"} diff --git a/verification/conformance/cases/kernel/L0/hole-unknown/plan.json b/verification/conformance/cases/kernel/L0/hole-unknown/plan.json new file mode 100644 index 0000000..813bcad --- /dev/null +++ b/verification/conformance/cases/kernel/L0/hole-unknown/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-literal-answer/answers.json b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/answers.json new file mode 100644 index 0000000..536d16b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/answers.json @@ -0,0 +1 @@ +{"OWNER":"a&b|c\\1 $HOME `x` {{ y }} /z"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-literal-answer/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 new file mode 100644 index 0000000..cc347d6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 @@ -0,0 +1 @@ += Repository of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/instantiate-literal-answer/case.json b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/case.json new file mode 100644 index 0000000..f09a72d --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"written"}},"id":"instantiate-literal-answer","kind":"instantiate","level":"L0","principle":"Answers are data: substituted byte for byte, never interpreted","source":"rsr-template-repo tests/e2e/use_template_mint_test.sh (existing control: answer with '&' and '|'), as listed in T6 SC-T-002","title":"An answer with shell and sed metacharacters renders literally"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-literal-answer/expected/README.adoc b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/expected/README.adoc new file mode 100644 index 0000000..79b6ccf --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/expected/README.adoc @@ -0,0 +1 @@ += Repository of a&b|c\1 $HOME `x` {{ y }} /z diff --git a/verification/conformance/cases/kernel/L0/instantiate-literal-answer/plan.json b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/plan.json new file mode 100644 index 0000000..813bcad --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-literal-answer/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/answers.json b/verification/conformance/cases/kernel/L0/instantiate-two-holes/answers.json new file mode 100644 index 0000000..700550b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/answers.json @@ -0,0 +1 @@ +{"OWNER":"alice","REPO":"widget"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/12ad2faebb473f861430c969e33d43664fa53a1c1602f7b6421e8839910ad336 b/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/12ad2faebb473f861430c969e33d43664fa53a1c1602f7b6421e8839910ad336 new file mode 100644 index 0000000..2fd2bf7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/12ad2faebb473f861430c969e33d43664fa53a1c1602f7b6421e8839910ad336 @@ -0,0 +1 @@ +Maintained by {{OWNER}}. diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/1bd8561499d0a3e2518f5e80a676e0370e76cdab67351bef4da77c977b9497f3 b/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/1bd8561499d0a3e2518f5e80a676e0370e76cdab67351bef4da77c977b9497f3 new file mode 100644 index 0000000..9022c11 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/blobs/sha256/1bd8561499d0a3e2518f5e80a676e0370e76cdab67351bef4da77c977b9497f3 @@ -0,0 +1 @@ += {{REPO}} diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/case.json b/verification/conformance/cases/kernel/L0/instantiate-two-holes/case.json new file mode 100644 index 0000000..8dcdfe6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"NOTICE.adoc":"written","README.adoc":"written"}},"id":"instantiate-two-holes","kind":"instantiate","level":"L0","principle":"Every declared token is replaced; the result is a closed plan with recomputed hashes","source":"conformance README, Instantiate","title":"Instantiation fills two holes across two blobs"} diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/NOTICE.adoc b/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/NOTICE.adoc new file mode 100644 index 0000000..9ffd468 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/NOTICE.adoc @@ -0,0 +1 @@ +Maintained by alice. diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/README.adoc b/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/README.adoc new file mode 100644 index 0000000..4192fac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/expected/README.adoc @@ -0,0 +1 @@ += widget diff --git a/verification/conformance/cases/kernel/L0/instantiate-two-holes/plan.json b/verification/conformance/cases/kernel/L0/instantiate-two-holes/plan.json new file mode 100644 index 0000000..9e38e81 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/instantiate-two-holes/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER","REPO"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:12ad2faebb473f861430c969e33d43664fa53a1c1602f7b6421e8839910ad336","expect":"absent","mode":"644","op":"write","path":"NOTICE.adoc","source":{"input":"spine","path":"NOTICE.adoc"}},{"blob":"sha256:1bd8561499d0a3e2518f5e80a676e0370e76cdab67351bef4da77c977b9497f3","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/malformed-missing-field/before/keep.txt b/verification/conformance/cases/kernel/L0/malformed-missing-field/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-missing-field/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/malformed-missing-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/malformed-missing-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-missing-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/malformed-missing-field/case.json b/verification/conformance/cases/kernel/L0/malformed-missing-field/case.json new file mode 100644 index 0000000..3711f09 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-missing-field/case.json @@ -0,0 +1 @@ +{"expect":{"code":"MALFORMED","outcome":"refused"},"id":"malformed-missing-field","kind":"apply","level":"L0","principle":"Every write carries path, blob, mode, expect and source","source":"conformance README, Plan format v0.1","title":"A write without a mode"} diff --git a/verification/conformance/cases/kernel/L0/malformed-missing-field/plan.json b/verification/conformance/cases/kernel/L0/malformed-missing-field/plan.json new file mode 100644 index 0000000..912f6ab --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-missing-field/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/malformed-not-jcs/before/keep.txt b/verification/conformance/cases/kernel/L0/malformed-not-jcs/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-jcs/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/malformed-not-jcs/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/malformed-not-jcs/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-jcs/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/malformed-not-jcs/case.json b/verification/conformance/cases/kernel/L0/malformed-not-jcs/case.json new file mode 100644 index 0000000..4375fe2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-jcs/case.json @@ -0,0 +1 @@ +{"expect":{"code":"MALFORMED","outcome":"refused"},"id":"malformed-not-jcs","kind":"apply","level":"L0","principle":"A plan is I-JSON serialised by JCS; one plan has one byte form, so one digest","source":"conformance README, Plan format v0.1","title":"Valid JSON that is not JCS-serialised"} diff --git a/verification/conformance/cases/kernel/L0/malformed-not-jcs/plan.json b/verification/conformance/cases/kernel/L0/malformed-not-jcs/plan.json new file mode 100644 index 0000000..662413b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-jcs/plan.json @@ -0,0 +1,24 @@ +{ + "holes": [], + "inputs": [ + { + "name": "spine", + "repo": "hyperpolymath/rsr-template-repo", + "rev": "4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1" + } + ], + "ops": [ + { + "blob": "sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec", + "expect": "absent", + "mode": "644", + "op": "write", + "path": "README.adoc", + "source": { + "input": "spine", + "path": "README.adoc" + } + } + ], + "plan_version": "0.1" +} diff --git a/verification/conformance/cases/kernel/L0/malformed-not-json/before/keep.txt b/verification/conformance/cases/kernel/L0/malformed-not-json/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-json/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/malformed-not-json/case.json b/verification/conformance/cases/kernel/L0/malformed-not-json/case.json new file mode 100644 index 0000000..670c0a3 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-json/case.json @@ -0,0 +1 @@ +{"expect":{"code":"MALFORMED","outcome":"refused"},"id":"malformed-not-json","kind":"apply","level":"L0","principle":"Only a v0.1 plan is accepted","source":"conformance README, Plan format v0.1","title":"A plan that is not JSON"} diff --git a/verification/conformance/cases/kernel/L0/malformed-not-json/plan.json b/verification/conformance/cases/kernel/L0/malformed-not-json/plan.json new file mode 100644 index 0000000..e485016 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-not-json/plan.json @@ -0,0 +1 @@ +write README.adoc please diff --git a/verification/conformance/cases/kernel/L0/malformed-unknown-field/before/README.adoc b/verification/conformance/cases/kernel/L0/malformed-unknown-field/before/README.adoc new file mode 100644 index 0000000..6e263ab --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-unknown-field/before/README.adoc @@ -0,0 +1 @@ +obsolete diff --git a/verification/conformance/cases/kernel/L0/malformed-unknown-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/malformed-unknown-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-unknown-field/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/malformed-unknown-field/case.json b/verification/conformance/cases/kernel/L0/malformed-unknown-field/case.json new file mode 100644 index 0000000..f5c6e47 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-unknown-field/case.json @@ -0,0 +1 @@ +{"expect":{"code":"MALFORMED","outcome":"refused"},"id":"malformed-unknown-field","kind":"apply","level":"L0","principle":"A kernel does not ignore what it does not understand (there is no overwrite-anyway)","source":"conformance README, Plan format v0.1","title":"An operation with an unknown member"} diff --git a/verification/conformance/cases/kernel/L0/malformed-unknown-field/plan.json b/verification/conformance/cases/kernel/L0/malformed-unknown-field/plan.json new file mode 100644 index 0000000..8de42fa --- /dev/null +++ b/verification/conformance/cases/kernel/L0/malformed-unknown-field/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","overwrite":true,"path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/case.json b/verification/conformance/cases/kernel/L0/mint-minimal/case.json new file mode 100644 index 0000000..54732ef --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"written","docs/index.adoc":"written"}},"id":"mint-minimal","kind":"apply","level":"L0","principle":"A closed, safe plan applied to an empty target yields exactly the planned tree","source":"ADR-0003, Acceptance evidence","title":"Minimal valid mint into an empty target"} diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/expected/README.adoc b/verification/conformance/cases/kernel/L0/mint-minimal/expected/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/expected/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/expected/docs/index.adoc b/verification/conformance/cases/kernel/L0/mint-minimal/expected/docs/index.adoc new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/expected/docs/index.adoc @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/mint-minimal/plan.json b/verification/conformance/cases/kernel/L0/mint-minimal/plan.json new file mode 100644 index 0000000..081e346 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mint-minimal/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c b/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c new file mode 100644 index 0000000..e37f89b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/blobs/sha256/b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c @@ -0,0 +1,2 @@ +#!/bin/sh +echo ok diff --git a/verification/conformance/cases/kernel/L0/mode-755/case.json b/verification/conformance/cases/kernel/L0/mode-755/case.json new file mode 100644 index 0000000..b758452 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"written","bin/tool.sh":"written"}},"id":"mode-755","kind":"apply","level":"L0","principle":"The mode of each write is part of the desired state","source":"conformance README, Plan format v0.1","title":"Executable mode 755 is honoured"} diff --git a/verification/conformance/cases/kernel/L0/mode-755/expected/README.adoc b/verification/conformance/cases/kernel/L0/mode-755/expected/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/expected/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/mode-755/expected/bin/tool.sh b/verification/conformance/cases/kernel/L0/mode-755/expected/bin/tool.sh new file mode 100755 index 0000000..e37f89b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/expected/bin/tool.sh @@ -0,0 +1,2 @@ +#!/bin/sh +echo ok diff --git a/verification/conformance/cases/kernel/L0/mode-755/plan.json b/verification/conformance/cases/kernel/L0/mode-755/plan.json new file mode 100644 index 0000000..dd5b221 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/mode-755/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c","expect":"absent","mode":"755","op":"write","path":"bin/tool.sh","source":{"input":"spine","path":"bin/tool.sh"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/open-plan/before/keep.txt b/verification/conformance/cases/kernel/L0/open-plan/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/open-plan/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 b/verification/conformance/cases/kernel/L0/open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 new file mode 100644 index 0000000..cc347d6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/open-plan/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 @@ -0,0 +1 @@ += Repository of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/open-plan/case.json b/verification/conformance/cases/kernel/L0/open-plan/case.json new file mode 100644 index 0000000..f45bb70 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/open-plan/case.json @@ -0,0 +1 @@ +{"expect":{"code":"OPEN_PLAN","outcome":"refused"},"id":"open-plan","kind":"apply","level":"L0","principle":"Only a closed plan can be applied","source":"conformance README, Plan format v0.1","title":"Apply of a plan with holes"} diff --git a/verification/conformance/cases/kernel/L0/open-plan/plan.json b/verification/conformance/cases/kernel/L0/open-plan/plan.json new file mode 100644 index 0000000..813bcad --- /dev/null +++ b/verification/conformance/cases/kernel/L0/open-plan/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-collision-case-fold/before/keep.txt b/verification/conformance/cases/kernel/L0/path-collision-case-fold/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-case-fold/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-case-fold/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-collision-case-fold/case.json b/verification/conformance/cases/kernel/L0/path-collision-case-fold/case.json new file mode 100644 index 0000000..01679eb --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-case-fold/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_COLLISION","outcome":"refused"},"id":"path-collision-case-fold","kind":"apply","level":"L0","principle":"No path alias or case collision","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"Two paths equal after case folding"} diff --git a/verification/conformance/cases/kernel/L0/path-collision-case-fold/plan.json b/verification/conformance/cases/kernel/L0/path-collision-case-fold/plan.json new file mode 100644 index 0000000..230cb8b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-case-fold/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"readme.adoc","source":{"input":"spine","path":"readme.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-collision-prefix/before/keep.txt b/verification/conformance/cases/kernel/L0/path-collision-prefix/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-prefix/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-prefix/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-collision-prefix/case.json b/verification/conformance/cases/kernel/L0/path-collision-prefix/case.json new file mode 100644 index 0000000..42e1208 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-prefix/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_COLLISION","outcome":"refused"},"id":"path-collision-prefix","kind":"apply","level":"L0","principle":"No path is a proper directory prefix of another","source":"conformance README, Safe paths","title":"A file path that is a directory prefix of another"} diff --git a/verification/conformance/cases/kernel/L0/path-collision-prefix/plan.json b/verification/conformance/cases/kernel/L0/path-collision-prefix/plan.json new file mode 100644 index 0000000..e55d968 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-collision-prefix/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"docs","source":{"input":"spine","path":"docs"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-duplicate/before/keep.txt b/verification/conformance/cases/kernel/L0/path-duplicate/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-duplicate/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-duplicate/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-duplicate/case.json b/verification/conformance/cases/kernel/L0/path-duplicate/case.json new file mode 100644 index 0000000..dd44e52 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-duplicate/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_DUPLICATE","outcome":"refused"},"id":"path-duplicate","kind":"apply","level":"L0","principle":"A plan maps each path to at most one operation","source":"conformance README, Plan format v0.1","title":"Two operations on one path"} diff --git a/verification/conformance/cases/kernel/L0/path-duplicate/plan.json b/verification/conformance/cases/kernel/L0/path-duplicate/plan.json new file mode 100644 index 0000000..a104c69 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-duplicate/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-absolute/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-absolute/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/case.json new file mode 100644 index 0000000..70ef450 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-absolute","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"An absolute path"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-absolute/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/plan.json new file mode 100644 index 0000000..19729a4 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-absolute/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"/dev/null/escape.txt","source":{"input":"spine","path":"/dev/null/escape.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-backslash/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-backslash/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/case.json new file mode 100644 index 0000000..77c89ad --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-backslash","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path with a backslash"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-backslash/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/plan.json new file mode 100644 index 0000000..bd3603a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-backslash/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"docs\\escape.txt","source":{"input":"spine","path":"docs\\escape.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-control-char/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-control-char/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/case.json new file mode 100644 index 0000000..411d878 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-control-char","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path with a control character"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-control-char/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/plan.json new file mode 100644 index 0000000..b2ad2af --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-control-char/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"bad\u0001name.txt","source":{"input":"spine","path":"bad\u0001name.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/case.json new file mode 100644 index 0000000..0eba665 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-dot-git-case","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path into .GIT (case variant of .git)"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/plan.json new file mode 100644 index 0000000..25c4d54 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git-case/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":".GIT/hooks/post-checkout","source":{"input":"spine","path":".GIT/hooks/post-checkout"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/case.json new file mode 100644 index 0000000..c16c431 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-dot-git","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path into .git"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/plan.json new file mode 100644 index 0000000..8ba625a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dot-git/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":".git/hooks/post-checkout","source":{"input":"spine","path":".git/hooks/post-checkout"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/case.json new file mode 100644 index 0000000..a87b0f1 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-dotdot","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path with a '..' segment"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/plan.json new file mode 100644 index 0000000..6dd64e4 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-dotdot/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"../escape.txt","source":{"input":"spine","path":"../escape.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/case.json new file mode 100644 index 0000000..07106b7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-empty-segment","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path with an empty segment"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/plan.json new file mode 100644 index 0000000..b8652c6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-empty-segment/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"docs//escape.txt","source":{"input":"spine","path":"docs//escape.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a new file mode 100644 index 0000000..f1a5da2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a @@ -0,0 +1 @@ +planted diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/case.json b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/case.json new file mode 100644 index 0000000..9975dab --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_UNSAFE","outcome":"refused"},"id":"path-unsafe-non-nfc","kind":"apply","level":"L0","principle":"No write outside the target or into repository metadata","source":"conformance README, Safe paths","title":"A path not in Unicode NFC"} diff --git a/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/plan.json b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/plan.json new file mode 100644 index 0000000..3d62394 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsafe-non-nfc/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:60f97c7b5bf55c5f186c5d1c79c8e3b6929c83bf2766434df9f1e1b9069db73a","expect":"absent","mode":"644","op":"write","path":"café.txt","source":{"input":"spine","path":"café.txt"}},{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/path-unsorted/before/keep.txt b/verification/conformance/cases/kernel/L0/path-unsorted/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsorted/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsorted/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/path-unsorted/case.json b/verification/conformance/cases/kernel/L0/path-unsorted/case.json new file mode 100644 index 0000000..d78a184 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsorted/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PATH_DUPLICATE","outcome":"refused"},"id":"path-unsorted","kind":"apply","level":"L0","principle":"Operations are sorted bytewise by path, so a plan has one canonical order","source":"conformance README, Plan format v0.1","title":"Operations not sorted by path"} diff --git a/verification/conformance/cases/kernel/L0/path-unsorted/plan.json b/verification/conformance/cases/kernel/L0/path-unsorted/plan.json new file mode 100644 index 0000000..3aa0088 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/path-unsorted/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"b.adoc","source":{"input":"spine","path":"b.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"a.adoc","source":{"input":"spine","path":"a.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/plan-version/before/keep.txt b/verification/conformance/cases/kernel/L0/plan-version/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/plan-version/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/plan-version/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/plan-version/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/plan-version/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/plan-version/case.json b/verification/conformance/cases/kernel/L0/plan-version/case.json new file mode 100644 index 0000000..a1789cc --- /dev/null +++ b/verification/conformance/cases/kernel/L0/plan-version/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PLAN_VERSION","outcome":"refused"},"id":"plan-version","kind":"apply","level":"L0","principle":"An unknown plan version is refused, not guessed","source":"conformance README, Plan format v0.1","title":"A plan version this kernel does not implement"} diff --git a/verification/conformance/cases/kernel/L0/plan-version/plan.json b/verification/conformance/cases/kernel/L0/plan-version/plan.json new file mode 100644 index 0000000..582440a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/plan-version/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.2"} diff --git a/verification/conformance/cases/kernel/L0/precondition-ancestor-file/before/docs b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/before/docs new file mode 100644 index 0000000..757af72 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/before/docs @@ -0,0 +1 @@ +a file, not a directory diff --git a/verification/conformance/cases/kernel/L0/precondition-ancestor-file/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/precondition-ancestor-file/case.json b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/case.json new file mode 100644 index 0000000..745b546 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"precondition-ancestor-file","kind":"apply","level":"L0","principle":"A planned path needs directories, not files, above it","source":"conformance README, Apply","title":"A planned path under an existing file"} diff --git a/verification/conformance/cases/kernel/L0/precondition-ancestor-file/plan.json b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/plan.json new file mode 100644 index 0000000..bc91d8c --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-ancestor-file/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/before/old.txt b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/before/old.txt new file mode 100644 index 0000000..eedb639 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/before/old.txt @@ -0,0 +1 @@ +obsolete, but edited by the user diff --git a/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/case.json b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/case.json new file mode 100644 index 0000000..270e092 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"precondition-delete-wrong-sha","kind":"apply","level":"L0","principle":"A delete removes only the content the planner saw","source":"conformance README, Apply","title":"Delete of a file whose content differs"} diff --git a/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/plan.json b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/plan.json new file mode 100644 index 0000000..2f39a3a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-delete-wrong-sha/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"expect":{"sha256":"abdcccf4a6a5fae3da2c8232d6fbf33b61d5db886742c35218e724b8e5c6b0e0"},"op":"delete","path":"old.txt","source":{"input":"spine","path":"old.txt"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-absent/before/README.adoc b/verification/conformance/cases/kernel/L0/precondition-expect-absent/before/README.adoc new file mode 100644 index 0000000..c9ddff0 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-absent/before/README.adoc @@ -0,0 +1 @@ += My own README diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/precondition-expect-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-absent/case.json b/verification/conformance/cases/kernel/L0/precondition-expect-absent/case.json new file mode 100644 index 0000000..db42431 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-absent/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"precondition-expect-absent","kind":"apply","level":"L0","principle":"No silent overwrite: there is no overwrite-whatever-is-there","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"expect absent, but a file with other content exists"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-absent/plan.json b/verification/conformance/cases/kernel/L0/precondition-expect-absent/plan.json new file mode 100644 index 0000000..7d749d7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-absent/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/before/keep.txt b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/case.json b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/case.json new file mode 100644 index 0000000..2bc0b8a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"precondition-expect-sha-absent","kind":"apply","level":"L0","principle":"A replacement of something that is not there is not a creation","source":"conformance README, Apply","title":"expect sha256, but the path is absent"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/plan.json b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/plan.json new file mode 100644 index 0000000..283fe08 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha-absent/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":{"sha256":"32871246df6918d52fc58eb197e3ced4ac6fc9b7f43795e828e9f7adc8027b77"},"mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha/before/README.adoc b/verification/conformance/cases/kernel/L0/precondition-expect-sha/before/README.adoc new file mode 100644 index 0000000..96f6d20 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha/before/README.adoc @@ -0,0 +1 @@ += Old, then edited by the user diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/precondition-expect-sha/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha/case.json b/verification/conformance/cases/kernel/L0/precondition-expect-sha/case.json new file mode 100644 index 0000000..a5bc67a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha/case.json @@ -0,0 +1 @@ +{"expect":{"code":"PRECONDITION","outcome":"refused"},"id":"precondition-expect-sha","kind":"apply","level":"L0","principle":"A replacement needs exactly the base content the planner saw","source":"conformance README, Apply","title":"expect sha256, but the content differs"} diff --git a/verification/conformance/cases/kernel/L0/precondition-expect-sha/plan.json b/verification/conformance/cases/kernel/L0/precondition-expect-sha/plan.json new file mode 100644 index 0000000..283fe08 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/precondition-expect-sha/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":{"sha256":"32871246df6918d52fc58eb197e3ced4ac6fc9b7f43795e828e9f7adc8027b77"},"mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/residue-from-answer/answers.json b/verification/conformance/cases/kernel/L0/residue-from-answer/answers.json new file mode 100644 index 0000000..c0fb579 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue-from-answer/answers.json @@ -0,0 +1 @@ +{"OWNER":"{{REPO}}","REPO":"widget"} diff --git a/verification/conformance/cases/kernel/L0/residue-from-answer/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 b/verification/conformance/cases/kernel/L0/residue-from-answer/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 new file mode 100644 index 0000000..8f0f4f9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue-from-answer/blobs/sha256/e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9 @@ -0,0 +1 @@ += {{REPO}} of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/residue-from-answer/case.json b/verification/conformance/cases/kernel/L0/residue-from-answer/case.json new file mode 100644 index 0000000..b0b208f --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue-from-answer/case.json @@ -0,0 +1 @@ +{"expect":{"code":"RESIDUE","outcome":"refused"},"id":"residue-from-answer","kind":"instantiate","level":"L0","principle":"Substitution is one pass and residue is checked on the result, so an answer cannot smuggle in template text","source":"conformance README, Instantiate","title":"An answer that itself contains a token"} diff --git a/verification/conformance/cases/kernel/L0/residue-from-answer/plan.json b/verification/conformance/cases/kernel/L0/residue-from-answer/plan.json new file mode 100644 index 0000000..d7ea343 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue-from-answer/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER","REPO"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:e358d074e66094ccdefcf175658232ae944b02a8917ba374dd85b910cb34bfd9","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/residue/answers.json b/verification/conformance/cases/kernel/L0/residue/answers.json new file mode 100644 index 0000000..b62e25f --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue/answers.json @@ -0,0 +1 @@ +{"OWNER":"alice"} diff --git a/verification/conformance/cases/kernel/L0/residue/blobs/sha256/738d156564c61171c21f6e23bc096973fdd03843e2d66ab19512b2a4383dc673 b/verification/conformance/cases/kernel/L0/residue/blobs/sha256/738d156564c61171c21f6e23bc096973fdd03843e2d66ab19512b2a4383dc673 new file mode 100644 index 0000000..7df5ddc --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue/blobs/sha256/738d156564c61171c21f6e23bc096973fdd03843e2d66ab19512b2a4383dc673 @@ -0,0 +1 @@ +Licence holder: {{LICENSOR}} diff --git a/verification/conformance/cases/kernel/L0/residue/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 b/verification/conformance/cases/kernel/L0/residue/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 new file mode 100644 index 0000000..cc347d6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue/blobs/sha256/e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224 @@ -0,0 +1 @@ += Repository of {{OWNER}} diff --git a/verification/conformance/cases/kernel/L0/residue/case.json b/verification/conformance/cases/kernel/L0/residue/case.json new file mode 100644 index 0000000..404e000 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue/case.json @@ -0,0 +1 @@ +{"expect":{"code":"RESIDUE","outcome":"refused"},"id":"residue","kind":"instantiate","level":"L0","principle":"A child must not carry unfilled template text","source":"conformance README, Instantiate","title":"An undeclared token survives instantiation"} diff --git a/verification/conformance/cases/kernel/L0/residue/plan.json b/verification/conformance/cases/kernel/L0/residue/plan.json new file mode 100644 index 0000000..6b3456c --- /dev/null +++ b/verification/conformance/cases/kernel/L0/residue/plan.json @@ -0,0 +1 @@ +{"holes":["OWNER"],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:738d156564c61171c21f6e23bc096973fdd03843e2d66ab19512b2a4383dc673","expect":"absent","mode":"644","op":"write","path":"NOTICE.adoc","source":{"input":"spine","path":"NOTICE.adoc"}},{"blob":"sha256:e15d9b36ca091636883b329845f392cd857947239440d90ece452f9683392224","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/target-invalid-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/target-invalid-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-absent/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/target-invalid-absent/case.json b/verification/conformance/cases/kernel/L0/target-invalid-absent/case.json new file mode 100644 index 0000000..3b0c40b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-absent/case.json @@ -0,0 +1 @@ +{"expect":{"code":"TARGET_INVALID","outcome":"refused"},"id":"target-invalid-absent","kind":"apply","level":"L0","principle":"Apply needs an existing target directory; it does not create one","source":"conformance README, Apply","target":"absent","title":"The target does not exist"} diff --git a/verification/conformance/cases/kernel/L0/target-invalid-absent/plan.json b/verification/conformance/cases/kernel/L0/target-invalid-absent/plan.json new file mode 100644 index 0000000..7d749d7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-absent/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/target-invalid-file/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/target-invalid-file/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-file/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/target-invalid-file/case.json b/verification/conformance/cases/kernel/L0/target-invalid-file/case.json new file mode 100644 index 0000000..c0fb6b6 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-file/case.json @@ -0,0 +1 @@ +{"expect":{"code":"TARGET_INVALID","outcome":"refused"},"id":"target-invalid-file","kind":"apply","level":"L0","principle":"Apply needs an existing target directory","source":"conformance README, Apply","target":"file","title":"The target is a regular file"} diff --git a/verification/conformance/cases/kernel/L0/target-invalid-file/plan.json b/verification/conformance/cases/kernel/L0/target-invalid-file/plan.json new file mode 100644 index 0000000..7d749d7 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-invalid-file/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/target-symlink-leaf/before/README.adoc b/verification/conformance/cases/kernel/L0/target-symlink-leaf/before/README.adoc new file mode 120000 index 0000000..dbe0fee --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink-leaf/before/README.adoc @@ -0,0 +1 @@ +../outside/README.adoc \ No newline at end of file diff --git a/verification/conformance/cases/kernel/L0/target-symlink-leaf/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/target-symlink-leaf/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink-leaf/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/target-symlink-leaf/case.json b/verification/conformance/cases/kernel/L0/target-symlink-leaf/case.json new file mode 100644 index 0000000..293e9e0 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink-leaf/case.json @@ -0,0 +1 @@ +{"expect":{"code":"TARGET_SYMLINK","outcome":"refused"},"id":"target-symlink-leaf","kind":"apply","level":"L0","principle":"No symlink escape: a link at a planned path is not read through or written through","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"The planned path itself is a link pointing outside"} diff --git a/verification/conformance/cases/kernel/L0/target-symlink-leaf/plan.json b/verification/conformance/cases/kernel/L0/target-symlink-leaf/plan.json new file mode 100644 index 0000000..283fe08 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink-leaf/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":{"sha256":"32871246df6918d52fc58eb197e3ced4ac6fc9b7f43795e828e9f7adc8027b77"},"mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/target-symlink/before/docs b/verification/conformance/cases/kernel/L0/target-symlink/before/docs new file mode 120000 index 0000000..d09b807 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink/before/docs @@ -0,0 +1 @@ +../outside \ No newline at end of file diff --git a/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 b/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 new file mode 100644 index 0000000..27c9fa2 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232 @@ -0,0 +1 @@ += Documentation diff --git a/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/target-symlink/case.json b/verification/conformance/cases/kernel/L0/target-symlink/case.json new file mode 100644 index 0000000..959ba7b --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink/case.json @@ -0,0 +1 @@ +{"expect":{"code":"TARGET_SYMLINK","outcome":"refused"},"id":"target-symlink","kind":"apply","level":"L0","principle":"No symlink escape: links are never followed when writing","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"An ancestor directory is a link pointing outside"} diff --git a/verification/conformance/cases/kernel/L0/target-symlink/plan.json b/verification/conformance/cases/kernel/L0/target-symlink/plan.json new file mode 100644 index 0000000..081e346 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/target-symlink/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}},{"blob":"sha256:1e25202bfd2f9f6a007fa6c4e19eecbddd9deab440910b457db37d3ed80c5232","expect":"absent","mode":"644","op":"write","path":"docs/index.adoc","source":{"input":"spine","path":"docs/index.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/unpinned-short-rev/before/keep.txt b/verification/conformance/cases/kernel/L0/unpinned-short-rev/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-short-rev/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/unpinned-short-rev/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/unpinned-short-rev/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-short-rev/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/unpinned-short-rev/case.json b/verification/conformance/cases/kernel/L0/unpinned-short-rev/case.json new file mode 100644 index 0000000..617f5de --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-short-rev/case.json @@ -0,0 +1 @@ +{"expect":{"code":"SOURCE_UNPINNED","outcome":"refused"},"id":"unpinned-short-rev","kind":"apply","level":"L0","principle":"Sources are pinned by full commit id, never inferred","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"An input pinned by an abbreviated commit id"} diff --git a/verification/conformance/cases/kernel/L0/unpinned-short-rev/plan.json b/verification/conformance/cases/kernel/L0/unpinned-short-rev/plan.json new file mode 100644 index 0000000..c31431a --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-short-rev/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/before/keep.txt b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/case.json b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/case.json new file mode 100644 index 0000000..896e126 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/case.json @@ -0,0 +1 @@ +{"expect":{"code":"SOURCE_UNPINNED","outcome":"refused"},"id":"unpinned-undeclared-input","kind":"apply","level":"L0","principle":"Every write has provenance in a pinned input","source":"ADR-0002, Safety invariants and Acceptance evidence","title":"An operation naming an undeclared input"} diff --git a/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/plan.json b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/plan.json new file mode 100644 index 0000000..f591802 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/unpinned-undeclared-input/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":"absent","mode":"644","op":"write","path":"README.adoc","source":{"input":"elsewhere","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/before/README.adoc b/verification/conformance/cases/kernel/L0/update-expected-content/before/README.adoc new file mode 100644 index 0000000..0dda777 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/before/README.adoc @@ -0,0 +1 @@ += Old diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/before/keep.txt b/verification/conformance/cases/kernel/L0/update-expected-content/before/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/before/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec b/verification/conformance/cases/kernel/L0/update-expected-content/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/blobs/sha256/95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/case.json b/verification/conformance/cases/kernel/L0/update-expected-content/case.json new file mode 100644 index 0000000..b237b42 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/case.json @@ -0,0 +1 @@ +{"expect":{"outcome":"ok","results":{"README.adoc":"written"}},"id":"update-expected-content","kind":"apply","level":"L0","principle":"expect {sha256} authorises replacing exactly the content the planner saw","source":"conformance README, Apply","title":"A write whose expected base content matches replaces it"} diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/expected/README.adoc b/verification/conformance/cases/kernel/L0/update-expected-content/expected/README.adoc new file mode 100644 index 0000000..ce21bac --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/expected/README.adoc @@ -0,0 +1,3 @@ += Example + +A minimal repository. diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/expected/keep.txt b/verification/conformance/cases/kernel/L0/update-expected-content/expected/keep.txt new file mode 100644 index 0000000..1360ca9 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/expected/keep.txt @@ -0,0 +1 @@ +user content, not planned diff --git a/verification/conformance/cases/kernel/L0/update-expected-content/plan.json b/verification/conformance/cases/kernel/L0/update-expected-content/plan.json new file mode 100644 index 0000000..283fe08 --- /dev/null +++ b/verification/conformance/cases/kernel/L0/update-expected-content/plan.json @@ -0,0 +1 @@ +{"holes":[],"inputs":[{"name":"spine","repo":"hyperpolymath/rsr-template-repo","rev":"4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1"}],"ops":[{"blob":"sha256:95469b9aca6b78d8fdd258b0e331da56a1098dc671724bed3be90738ed6198ec","expect":{"sha256":"32871246df6918d52fc58eb197e3ced4ac6fc9b7f43795e828e9f7adc8027b77"},"mode":"644","op":"write","path":"README.adoc","source":{"input":"spine","path":"README.adoc"}}],"plan_version":"0.1"} diff --git a/verification/conformance/check-l0.sh b/verification/conformance/check-l0.sh new file mode 100755 index 0000000..6e058a1 --- /dev/null +++ b/verification/conformance/check-l0.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# The one list of commands behind the `Conformance L0` CI check and +# `just conformance`. Both call this script so they cannot drift. +# Needs: cargo, bash, jq, coreutils. Run from anywhere. +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$root" + +kernel_bin="src/kernel/target/release/scaffoldia-kernel" + +cargo build --release --locked --manifest-path src/kernel/Cargo.toml +verification/conformance/gen-cases.sh --check +verification/conformance/run.sh --level L0 --kernel "$kernel_bin" +verification/conformance/selftest.sh --level L0 diff --git a/verification/conformance/controls/naive-kernel.sh b/verification/conformance/controls/naive-kernel.sh new file mode 100755 index 0000000..052423f --- /dev/null +++ b/verification/conformance/controls/naive-kernel.sh @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# NEGATIVE CONTROL — deliberately wrong. Never use as a kernel. +# +# naive-kernel.sh: writes every operation it is given, with no check at all: +# no JCS or version check, no pin check, no path safety, no blob hashing, no +# preconditions, no symlink check, no hole or residue check. `check` always +# succeeds. The conformance suite must FAIL this kernel (selftest.sh). +set -euo pipefail + +cmd="${1:-}" +shift || true +declare -A A=() +while [ "$#" -ge 2 ]; do A["${1#--}"]="$2"; shift 2; done + +case "$cmd" in + check) exit 0 ;; + instantiate) + plan="$(jq -c . "${A[plan]}")" + mkdir -p "${A[out-blobs]}/sha256" + while IFS= read -r h; do + content="$(cat -- "${A[blobs]}/sha256/$h"; echo x)" + content="${content%x}" + while IFS=$'\t' read -r k v; do + content="${content//"{{$k}}"/"$v"}" + done < <(jq -r 'to_entries[] | "\(.key)\t\(.value)"' "${A[answers]}") + new="$(printf '%s' "$content" | sha256sum | cut -c1-64)" + printf '%s' "$content" >"${A[out-blobs]}/sha256/$new" + plan="$(jq -c --arg o "sha256:$h" --arg n "sha256:$new" '(.ops[] | select(.blob == $o) | .blob) |= $n' <<<"$plan")" + done < <(jq -r '.ops[] | select(.op == "write") | .blob | ltrimstr("sha256:")' <<<"$plan" | sort -u) + jq -cS '.holes = []' <<<"$plan" >"${A[out]}" + ;; + apply) + t="${A[target]}" + results="[]" + while IFS=$'\t' read -r op path blob mode; do + if [ "$op" = write ]; then + mkdir -p "$(dirname "$t/$path")" + cp -- "${A[blobs]}/sha256/${blob#sha256:}" "$t/$path" + chmod "$mode" "$t/$path" + r=written + else + rm -f -- "$t/$path" + r=deleted + fi + results="$(jq -c --arg p "$path" --arg r "$r" '. + [{path: $p, result: $r}]' <<<"$results")" + done < <(jq -r '.ops[] | [.op, .path, (.blob // "-"), (.mode // "-")] | @tsv' "${A[plan]}") + jq -cS -n --argjson o "$results" --arg d "sha256:$(sha256sum <"${A[plan]}" | cut -c1-64)" \ + '{ops: $o, plan: $d}' >"${A[receipt]}" + ;; + *) echo "usage: naive-kernel.sh check|instantiate|apply ..." >&2; exit 2 ;; +esac diff --git a/verification/conformance/controls/no-atomicity-kernel.sh b/verification/conformance/controls/no-atomicity-kernel.sh new file mode 100755 index 0000000..3f0f6b9 --- /dev/null +++ b/verification/conformance/controls/no-atomicity-kernel.sh @@ -0,0 +1,176 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# NEGATIVE CONTROL — deliberately wrong. Never use as a kernel. +# +# no-atomicity-kernel.sh: checks the plan itself carefully (JCS, version, +# shape, pins, holes, path safety with an ASCII-only stand-in for NFC, order, +# collisions, blobs), but checks the TARGET one operation at a time and writes +# as it goes. A plan whose later operation fails its precondition therefore +# leaves the earlier writes behind. Its only intended defect is the missing +# check-everything-then-write phase; the suite must FAIL it (selftest.sh). +set -euo pipefail +export LC_ALL=C + +refuse() { + jq -cS -n --arg c "$1" --arg d "$2" '{detail: $d, refused: $c}' + exit 10 +} + +cmd="${1:-}" +shift || true +declare -A A=() +while [ "$#" -ge 2 ]; do A["${1#--}"]="$2"; shift 2; done +PLAN="${A[plan]:-}" +BLOBS="${A[blobs]:-}" + +sha() { sha256sum <"$1" | cut -c1-64; } + +is_j1() { # file + local canon body + canon="$(jq -cS . <"$1" 2>/dev/null)" || return 1 + body="$(cat -- "$1"; echo x)" + [ "$body" = "$canon"$'\n'x ] +} + +check_plan() { # $1 = closed|open + jq -e . "$PLAN" >/dev/null 2>&1 || refuse MALFORMED "not JSON" + is_j1 "$PLAN" || refuse MALFORMED "not JCS" + local v + v="$(jq -r 'if type == "object" and has("plan_version") then .plan_version else "" end' "$PLAN")" + [ "$v" != "" ] || refuse MALFORMED "no plan_version" + [ "$v" = "0.1" ] || refuse PLAN_VERSION "plan_version $v" + jq -e ' + def hex($n): type == "string" and test("^[0-9a-f]{\($n)}$"); + def src: type == "object" and keys == ["input", "path"] and (.input | type) == "string" and (.path | type) == "string"; + keys == ["holes", "inputs", "ops", "plan_version"] + and (.holes | type == "array" and all(type == "string" and test("^[A-Z][A-Z0-9_]*$"))) + and (.inputs | type == "array" and all(type == "object" and keys == ["name", "repo", "rev"])) + and (.ops | type == "array" and all( + type == "object" and (.path | type) == "string" and (.source | src) + and ((.replaces // {input: "", path: ""}) | src) + and ((.op == "write" and (keys - ["replaces"]) == ["blob", "expect", "mode", "op", "path", "source"] + and (.blob | type == "string" and test("^sha256:[0-9a-f]{64}$")) + and (.mode | IN("644", "755")) + and (.expect == "absent" or (.expect | type == "object" and keys == ["sha256"] and (.sha256 | hex(64)))))) + or (.op == "delete" and (keys - ["replaces"]) == ["expect", "op", "path", "source"] + and (.expect | type == "object" and keys == ["sha256"] and (.sha256 | hex(64)))))) + ' "$PLAN" >/dev/null || refuse MALFORMED "plan shape" + jq -e '.inputs | all(.rev | test("^[0-9a-f]{40}$"))' "$PLAN" >/dev/null || refuse SOURCE_UNPINNED "short rev" + jq -e '[.inputs[].name] as $n | .ops | all((.source.input | IN($n[])) and ((.replaces.input // $n[0]) | IN($n[])))' \ + "$PLAN" >/dev/null || refuse SOURCE_UNPINNED "undeclared input" + if [ "$1" = closed ] && jq -e '.holes | length > 0' "$PLAN" >/dev/null; then refuse OPEN_PLAN "holes"; fi + + local p prev="" seg folded + local -A seen=() + local -a all=() + while IFS= read -r -d '' p; do + [ -n "$p" ] || refuse PATH_UNSAFE "empty" + case "$p" in /* | *\\*) refuse PATH_UNSAFE "absolute or backslash" ;; esac + [[ ! "$p" =~ [[:cntrl:]] ]] || refuse PATH_UNSAFE "control character" + [ "$(printf '%s' "$p" | tr -d '\000-\177' | wc -c)" = 0 ] || refuse PATH_UNSAFE "non-ASCII (NFC stand-in)" + IFS=/ read -r -a segs <<<"$p" + case "$p" in */) refuse PATH_UNSAFE "empty segment" ;; esac + for seg in "${segs[@]}"; do + case "$seg" in "" | . | ..) refuse PATH_UNSAFE "bad segment" ;; esac + [ "$(printf '%s' "$seg" | tr '[:upper:]' '[:lower:]')" != ".git" ] || refuse PATH_UNSAFE ".git" + done + if [ -n "$prev" ]; then + [ "$prev" != "$p" ] || refuse PATH_DUPLICATE "duplicate" + [[ "$prev" < "$p" ]] || refuse PATH_DUPLICATE "unsorted" + fi + prev="$p" + folded="$(printf '%s' "$p" | tr '[:upper:]' '[:lower:]')" + [ -z "${seen[$folded]+x}" ] || refuse PATH_COLLISION "case fold" + seen[$folded]=1 + all+=("$folded") + done < <(jq --raw-output0 '.ops[].path' "$PLAN") + for p in "${all[@]}"; do + while [[ "$p" == */* ]]; do + p="${p%/*}" + [ -z "${seen[$p]+x}" ] || refuse PATH_COLLISION "prefix" + done + done + + local h + while IFS= read -r h; do + [ -f "$BLOBS/sha256/$h" ] || refuse BLOB_MISSING "$h" + [ "$(sha "$BLOBS/sha256/$h")" = "$h" ] || refuse BLOB_MISMATCH "$h" + done < <(jq -r '.ops[] | select(.op == "write") | .blob | ltrimstr("sha256:")' "$PLAN") +} + +case "$cmd" in + check) check_plan open ;; + instantiate) + check_plan open + jq -e 'type == "object" and all(.[]; type == "string")' "${A[answers]}" >/dev/null 2>&1 || refuse MALFORMED "answers" + jq -e --slurpfile a "${A[answers]}" '.holes | all(. as $h | $a[0] | has($h))' "$PLAN" >/dev/null || refuse HOLE_UNFILLED "unfilled" + jq -e --slurpfile p "$PLAN" 'keys | all(. as $k | $p[0].holes | index($k))' "${A[answers]}" >/dev/null || refuse HOLE_UNKNOWN "unknown" + out_plan="$(jq -c '.holes = []' "$PLAN")" + mkdir -p "${A[out-blobs]}/sha256" + while IFS= read -r h; do + content="$(cat -- "$BLOBS/sha256/$h"; echo x)" + content="${content%x}" + while IFS=$'\t' read -r k v; do + content="${content//"{{$k}}"/"$v"}" + done < <(jq -r 'to_entries[] | "\(.key)\t\(.value)"' "${A[answers]}") + if printf '%s' "$content" | grep -qE '\{\{[A-Z][A-Z0-9_]*\}\}'; then refuse RESIDUE "token left"; fi + new="$(printf '%s' "$content" | sha256sum | cut -c1-64)" + printf '%s' "$content" >"${A[out-blobs]}/sha256/$new" + out_plan="$(jq -c --arg o "sha256:$h" --arg n "sha256:$new" '(.ops[] | select(.blob == $o) | .blob) |= $n' <<<"$out_plan")" + done < <(jq -r '.ops[] | select(.op == "write") | .blob | ltrimstr("sha256:")' "$PLAN" | sort -u) + jq -cS . <<<"$out_plan" >"${A[out]}" + ;; + apply) + check_plan closed + t="${A[target]}" + [ ! -L "$t" ] || refuse TARGET_SYMLINK "target is a link" + [ -d "$t" ] || refuse TARGET_INVALID "target is not a directory" + results="[]" + # THE DEFECT: decide and write one operation at a time. + while IFS=$'\t' read -r op path blob mode expect; do + a="" + IFS=/ read -r -a segs <<<"$path" + for seg in "${segs[@]:0:${#segs[@]}-1}"; do + a="${a:+$a/}$seg" + [ ! -L "$t/$a" ] || refuse TARGET_SYMLINK "ancestor $a" + [ ! -e "$t/$a" ] || [ -d "$t/$a" ] || refuse PRECONDITION "ancestor $a is not a directory" + done + leaf="$t/$path" + [ ! -L "$leaf" ] || refuse TARGET_SYMLINK "leaf" + if [ "$op" = write ]; then + want="${blob#sha256:}" + if [ -f "$leaf" ] && [ "$(sha "$leaf")" = "$want" ] && + { [ -x "$leaf" ] && [ "$mode" = 755 ] || { [ ! -x "$leaf" ] && [ "$mode" = 644 ]; }; }; then + r=unchanged + elif [ ! -e "$leaf" ]; then + [ "$expect" = absent ] || refuse PRECONDITION "expected content, absent" + r=written + elif [ -f "$leaf" ] && [ "$expect" = "$(sha "$leaf")" ]; then + r=written + else + refuse PRECONDITION "expect does not hold for $path" + fi + if [ "$r" = written ]; then + mkdir -p "$(dirname "$leaf")" + cp -- "$BLOBS/sha256/$want" "$leaf" + chmod "$mode" "$leaf" + fi + else + if [ ! -e "$leaf" ]; then + r=already-absent + elif [ -f "$leaf" ] && [ "$expect" = "$(sha "$leaf")" ]; then + rm -f -- "$leaf" + r=deleted + else + refuse PRECONDITION "delete expect does not hold for $path" + fi + fi + results="$(jq -c --arg p "$path" --arg r "$r" '. + [{path: $p, result: $r}]' <<<"$results")" + done < <(jq -r '.ops[] | [.op, .path, (.blob // "-"), (.mode // "-"), + (if .expect == "absent" then "absent" else .expect.sha256 end)] | @tsv' "$PLAN") + jq -cS -n --argjson o "$results" --arg d "sha256:$(sha "$PLAN")" '{ops: $o, plan: $d}' >"${A[receipt]}" + ;; + *) echo "usage: no-atomicity-kernel.sh check|instantiate|apply ..." >&2; exit 2 ;; +esac diff --git a/verification/conformance/controls/refuse-all-kernel.sh b/verification/conformance/controls/refuse-all-kernel.sh new file mode 100755 index 0000000..a34d1cb --- /dev/null +++ b/verification/conformance/controls/refuse-all-kernel.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# NEGATIVE CONTROL — deliberately wrong. Never use as a kernel. +# +# refuse-all-kernel.sh: refuses everything. It never writes, so it can never +# be unsafe; the suite must still FAIL it, or "safe" would be satisfiable by +# doing nothing (selftest.sh). +set -euo pipefail +printf '%s\n' '{"detail":"this control refuses every plan","refused":"MALFORMED"}' +exit 10 diff --git a/verification/conformance/gen-cases.sh b/verification/conformance/gen-cases.sh new file mode 100755 index 0000000..7c85530 --- /dev/null +++ b/verification/conformance/gen-cases.sh @@ -0,0 +1,427 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# gen-cases.sh — generate the L0 kernel conformance cases. +# +# gen-cases.sh regenerate cases/kernel/L0/ in place +# gen-cases.sh --check regenerate into a temporary directory and fail if +# the committed cases differ (generate-and-diff) +# +# The cases are committed; this script exists so that blob hashes, plan +# serialisation (JCS + one line feed, via `jq -cS`) and case metadata are +# derived, never typed by hand. Bash + jq + coreutils only. It writes only +# under the output directory. +set -euo pipefail + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +MODE="write" +if [ "${1:-}" = "--check" ]; then MODE="check"; fi + +if [ "$MODE" = check ]; then + TMP="$(mktemp -d)" + trap 'rm -rf "$TMP"' EXIT + ROOT="$TMP/cases" +else + ROOT="$HERE/cases" +fi +L0="$ROOT/kernel/L0" +rm -rf "$L0" +mkdir -p "$L0" + +# Fixed pins. The spine name is the publisher whose own name must not appear +# in a child (case child-identity). +REV="4d3c2b1a09f8e7d6c5b4a3928170f6e5d4c3b2a1" +SPINE_REPO="hyperpolymath/rsr-template-repo" + +D="" # current case directory +HOLES="[]" # holes of the current plan (JSON array) +INPUTS="" # inputs override (JSON array) or empty for the default + +# new_case ID KIND OUTCOME CODE TITLE PRINCIPLE SOURCE [EXTRA-JSON] +new_case() { + local id="$1" kind="$2" outcome="$3" code="$4" title="$5" principle="$6" source="$7" extra="{}" + if [ "$#" -ge 8 ]; then extra="$8"; fi + D="$L0/$id" + HOLES="[]" + INPUTS="" + mkdir -p "$D" + jq -cS -n --arg id "$id" --arg kind "$kind" --arg outcome "$outcome" --arg code "$code" \ + --arg title "$title" --arg principle "$principle" --arg source "$source" --argjson extra "$extra" ' + {id: $id, kind: $kind, level: "L0", title: $title, principle: $principle, source: $source, + expect: ({outcome: $outcome} + (if $code == "" then {} else {code: $code} end) + ($extra.expect // {}))} + + ($extra | del(.expect))' >"$D/case.json" +} + +# blob CONTENT -> prints the 64-hex digest; stores blobs/sha256/. +blob() { + local tmp h + mkdir -p "$D/blobs/sha256" + tmp="$D/blobs/.new" + printf '%s' "$1" >"$tmp" + h="$(sha256sum <"$tmp" | cut -c1-64)" + mv -- "$tmp" "$D/blobs/sha256/$h" + echo "$h" +} + +# sha CONTENT -> 64-hex digest, nothing stored. +sha() { printf '%s' "$1" | sha256sum | cut -c1-64; } + +# put ROOT PATH CONTENT [MODE]: put a file in before/ or expected/. +put() { + local root="$1" p="$2" content="$3" mode="${4:-644}" + mkdir -p "$(dirname "$D/$root/$p")" + printf '%s' "$content" >"$D/$root/$p" + chmod "$mode" "$D/$root/$p" +} + +# w PATH DIGEST MODE EXPECT -> a write op (EXPECT: absent | <64 hex>). +w() { + jq -cn --arg p "$1" --arg b "sha256:$2" --arg m "$3" --arg e "$4" ' + {op: "write", path: $p, blob: $b, mode: $m, + expect: (if $e == "absent" then "absent" else {sha256: $e} end), + source: {input: "spine", path: $p}}' +} + +# del PATH SHA -> a delete op. +del() { + jq -cn --arg p "$1" --arg e "$2" '{op: "delete", path: $p, expect: {sha256: $e}, source: {input: "spine", path: $p}}' +} + +# plan OP... -> plan.json (JCS + LF), ops in the order given. +plan() { + local ops + ops="$(printf '%s\n' "$@" | jq -cs .)" + local inputs="$INPUTS" + if [ -z "$inputs" ]; then + inputs="$(jq -cn --arg r "$SPINE_REPO" --arg v "$REV" '[{name: "spine", repo: $r, rev: $v}]')" + fi + jq -cS -n --argjson ops "$ops" --argjson holes "$HOLES" --argjson inputs "$inputs" \ + '{plan_version: "0.1", holes: $holes, inputs: $inputs, ops: $ops}' >"$D/plan.json" +} + +# answers JSON-OBJECT -> answers.json (JCS + LF). +answers() { jq -cS -n --argjson a "$1" '$a' >"$D/answers.json"; } + +# A user file present in most starting trees, so any stray write shows. +KEEP=$'user content, not planned\n' +keep_before() { put before keep.txt "$KEEP"; } +keep_expected() { put expected keep.txt "$KEEP"; } + +README=$'= Example\n\nA minimal repository.\n' +INDEX=$'= Documentation\n' +SCRIPT=$'#!/bin/sh\necho ok\n' + +SRC_README="conformance README, Plan format v0.1" +SRC_SAFE="conformance README, Safe paths" +SRC_APPLY="conformance README, Apply" +SRC_INST="conformance README, Instantiate" +SRC_ADR2="ADR-0002, Safety invariants and Acceptance evidence" +SRC_ADR3="ADR-0003, Acceptance evidence" + +# ── accepted plans ────────────────────────────────────────────────────────── + +new_case mint-minimal apply ok "" "Minimal valid mint into an empty target" \ + "A closed, safe plan applied to an empty target yields exactly the planned tree" "$SRC_ADR3" \ + '{"expect":{"results":{"README.adoc":"written","docs/index.adoc":"written"}}}' +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w docs/index.adoc "$h2" 644 absent)" +put expected README.adoc "$README"; put expected docs/index.adoc "$INDEX" + +new_case apply-twice-idempotent apply-twice ok "" "Applying a plan twice equals applying it once" \ + "Idempotence: the second application leaves the tree identical and reports only unchanged/already-absent" "$SRC_ADR2" \ + '{"expect":{"results":{"README.adoc":"written","docs/index.adoc":"written","old.txt":"deleted","scripts/run.sh":"written"}}}' +OLD=$'obsolete\n' +h1="$(blob "$README")"; h2="$(blob "$INDEX")"; h3="$(blob "$SCRIPT")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w docs/index.adoc "$h2" 644 absent)" \ + "$(del old.txt "$(sha "$OLD")")" "$(w scripts/run.sh "$h3" 755 absent)" +keep_before; put before old.txt "$OLD" +keep_expected; put expected README.adoc "$README"; put expected docs/index.adoc "$INDEX" +put expected scripts/run.sh "$SCRIPT" 755 + +new_case already-realised apply ok "" "A path that already has the desired content is unchanged" \ + "A write whose desired state already holds is a no-op even though expect says absent" "$SRC_APPLY" \ + '{"expect":{"results":{"README.adoc":"unchanged","docs/index.adoc":"written"}}}' +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w docs/index.adoc "$h2" 644 absent)" +put before README.adoc "$README" +put expected README.adoc "$README"; put expected docs/index.adoc "$INDEX" + +new_case update-expected-content apply ok "" "A write whose expected base content matches replaces it" \ + "expect {sha256} authorises replacing exactly the content the planner saw" "$SRC_APPLY" \ + '{"expect":{"results":{"README.adoc":"written"}}}' +OLDREADME=$'= Old\n' +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 "$(sha "$OLDREADME")")" +put before README.adoc "$OLDREADME"; keep_before +put expected README.adoc "$README"; keep_expected + +new_case delete-already-absent apply ok "" "Deleting a path that is not there is a no-op" \ + "A delete whose desired state (absent) already holds reports already-absent" "$SRC_APPLY" \ + '{"expect":{"results":{"gone.txt":"already-absent"}}}' +plan "$(del gone.txt "$(sha $'was here\n')")" +keep_before; keep_expected + +new_case mode-755 apply ok "" "Executable mode 755 is honoured" \ + "The mode of each write is part of the desired state" "$SRC_README" \ + '{"expect":{"results":{"README.adoc":"written","bin/tool.sh":"written"}}}' +h1="$(blob "$README")"; h2="$(blob "$SCRIPT")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w bin/tool.sh "$h2" 755 absent)" +put expected README.adoc "$README"; put expected bin/tool.sh "$SCRIPT" 755 + +new_case check-open-plan check ok "" "check accepts a well-formed open plan" \ + "An open plan is a valid plan; only apply requires it closed" "$SRC_README" +HOLES='["OWNER"]' +h1="$(blob $'= Repository of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" + +new_case instantiate-two-holes instantiate ok "" "Instantiation fills two holes across two blobs" \ + "Every declared token is replaced; the result is a closed plan with recomputed hashes" "$SRC_INST" \ + '{"expect":{"results":{"NOTICE.adoc":"written","README.adoc":"written"}}}' +HOLES='["OWNER","REPO"]' +h1="$(blob $'= {{REPO}}\n')"; h2="$(blob $'Maintained by {{OWNER}}.\n')" +plan "$(w NOTICE.adoc "$h2" 644 absent)" "$(w README.adoc "$h1" 644 absent)" +answers '{"OWNER":"alice","REPO":"widget"}' +put expected README.adoc $'= widget\n'; put expected NOTICE.adoc $'Maintained by alice.\n' + +new_case child-identity instantiate ok "" "A child minted from a published plan carries its own identity" \ + "Child identity is distinct from the publisher's: the publisher's own name appears nowhere in the child" \ + "ADR-0002, Safety invariants (child identity); ADR-0003, Tier 0" \ + '{"expect":{"tree_excludes":["rsr-template-repo","hyperpolymath"]}}' +HOLES='["OWNER","REPO"]' +h1="$(blob $'= {{REPO}}\n\nA repository of {{OWNER}}, minted from a published plan.\n')" +h2="$(blob $'forge: github.com/{{OWNER}}/{{REPO}}\nname: {{REPO}}\n')" +h3="$(blob $'CI note: at run time the identity comes from ${{ github.repository }}\n')" +plan "$(w README.adoc "$h1" 644 absent)" "$(w docs/ci-note.txt "$h3" 644 absent)" "$(w identity.txt "$h2" 644 absent)" +answers '{"OWNER":"example-org","REPO":"example-child"}' +put expected README.adoc $'= example-child\n\nA repository of example-org, minted from a published plan.\n' +put expected identity.txt $'forge: github.com/example-org/example-child\nname: example-child\n' +put expected docs/ci-note.txt $'CI note: at run time the identity comes from ${{ github.repository }}\n' + +# ── refusals: plan shape ──────────────────────────────────────────────────── + +new_case malformed-not-json apply refused MALFORMED "A plan that is not JSON" \ + "Only a v0.1 plan is accepted" "$SRC_README" +printf 'write README.adoc please\n' >"$D/plan.json" +keep_before + +new_case malformed-not-jcs apply refused MALFORMED "Valid JSON that is not JCS-serialised" \ + "A plan is I-JSON serialised by JCS; one plan has one byte form, so one digest" "$SRC_README" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" +jq . "$D/plan.json" >"$D/plan.pretty" && mv -- "$D/plan.pretty" "$D/plan.json" +keep_before + +new_case malformed-missing-field apply refused MALFORMED "A write without a mode" \ + "Every write carries path, blob, mode, expect and source" "$SRC_README" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent | jq -c 'del(.mode)')" +keep_before + +new_case malformed-unknown-field apply refused MALFORMED "An operation with an unknown member" \ + "A kernel does not ignore what it does not understand (there is no overwrite-anyway)" "$SRC_README" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent | jq -c '. + {overwrite: true}')" +put before README.adoc "$OLD" + +new_case plan-version apply refused PLAN_VERSION "A plan version this kernel does not implement" \ + "An unknown plan version is refused, not guessed" "$SRC_README" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" +jq -cS '.plan_version = "0.2"' "$D/plan.json" >"$D/plan.v2" && mv -- "$D/plan.v2" "$D/plan.json" +keep_before + +new_case unpinned-short-rev apply refused SOURCE_UNPINNED "An input pinned by an abbreviated commit id" \ + "Sources are pinned by full commit id, never inferred" "$SRC_ADR2" +INPUTS="[{\"name\":\"spine\",\"repo\":\"$SPINE_REPO\",\"rev\":\"4d3c2b1\"}]" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" +keep_before + +new_case unpinned-undeclared-input apply refused SOURCE_UNPINNED "An operation naming an undeclared input" \ + "Every write has provenance in a pinned input" "$SRC_ADR2" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent | jq -c '.source.input = "elsewhere"')" +keep_before + +# ── refusals: paths ───────────────────────────────────────────────────────── + +unsafe_case() { # ID TITLE PATH + new_case "$1" apply refused PATH_UNSAFE "$2" \ + "No write outside the target or into repository metadata" "$SRC_SAFE" + local h1 + h1="$(blob $'planted\n')" + local hr + hr="$(blob "$README")" + plan "$(w "$3" "$h1" 644 absent)" "$(w README.adoc "$hr" 644 absent)" + keep_before +} +unsafe_case path-unsafe-dotdot "A path with a '..' segment" "../escape.txt" +unsafe_case path-unsafe-absolute "An absolute path" "/dev/null/escape.txt" +unsafe_case path-unsafe-backslash "A path with a backslash" 'docs\escape.txt' +unsafe_case path-unsafe-empty-segment "A path with an empty segment" "docs//escape.txt" +unsafe_case path-unsafe-dot-git "A path into .git" ".git/hooks/post-checkout" +unsafe_case path-unsafe-dot-git-case "A path into .GIT (case variant of .git)" ".GIT/hooks/post-checkout" +unsafe_case path-unsafe-control-char "A path with a control character" $'bad\001name.txt' +unsafe_case path-unsafe-non-nfc "A path not in Unicode NFC" $'cafe\xcc\x81.txt' + +new_case path-duplicate apply refused PATH_DUPLICATE "Two operations on one path" \ + "A plan maps each path to at most one operation" "$SRC_README" +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w README.adoc "$h2" 644 absent)" +keep_before + +new_case path-unsorted apply refused PATH_DUPLICATE "Operations not sorted by path" \ + "Operations are sorted bytewise by path, so a plan has one canonical order" "$SRC_README" +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w b.adoc "$h1" 644 absent)" "$(w a.adoc "$h2" 644 absent)" +keep_before + +new_case path-collision-case-fold apply refused PATH_COLLISION "Two paths equal after case folding" \ + "No path alias or case collision" "$SRC_ADR2" +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w readme.adoc "$h2" 644 absent)" +keep_before + +new_case path-collision-prefix apply refused PATH_COLLISION "A file path that is a directory prefix of another" \ + "No path is a proper directory prefix of another" "$SRC_SAFE" +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w docs "$h1" 644 absent)" "$(w docs/index.adoc "$h2" 644 absent)" +keep_before + +# ── refusals: blobs, holes ────────────────────────────────────────────────── + +new_case blob-missing apply refused BLOB_MISSING "A write whose blob is absent" \ + "Content is never inline and never fetched: every blob is present" "$SRC_README" +plan "$(w README.adoc "$(sha "$README")" 644 absent)" +keep_before + +new_case blob-mismatch apply refused BLOB_MISMATCH "A blob whose content does not match its name" \ + "Content is addressed by SHA-256 and checked before use" "$SRC_README" +h1="$(sha "$README")" +mkdir -p "$D/blobs/sha256"; printf 'tampered\n' >"$D/blobs/sha256/$h1" +plan "$(w README.adoc "$h1" 644 absent)" +keep_before + +new_case open-plan apply refused OPEN_PLAN "Apply of a plan with holes" \ + "Only a closed plan can be applied" "$SRC_README" +HOLES='["OWNER"]' +h1="$(blob $'= Repository of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" +keep_before + +new_case hole-unfilled instantiate refused HOLE_UNFILLED "A hole without an answer" \ + "Every hole must have an answer" "$SRC_INST" +HOLES='["OWNER","REPO"]' +h1="$(blob $'= {{REPO}} of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" +answers '{"OWNER":"alice"}' + +new_case hole-unknown instantiate refused HOLE_UNKNOWN "An answer that names no hole" \ + "Every answer must name a hole" "$SRC_INST" +HOLES='["OWNER"]' +h1="$(blob $'= Repository of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" +answers '{"OWNER":"alice","REPO":"widget"}' + +new_case residue instantiate refused RESIDUE "An undeclared token survives instantiation" \ + "A child must not carry unfilled template text" "$SRC_INST" +HOLES='["OWNER"]' +h1="$(blob $'= Repository of {{OWNER}}\n')"; h2="$(blob $'Licence holder: {{LICENSOR}}\n')" +plan "$(w NOTICE.adoc "$h2" 644 absent)" "$(w README.adoc "$h1" 644 absent)" +answers '{"OWNER":"alice"}' + +new_case residue-from-answer instantiate refused RESIDUE "An answer that itself contains a token" \ + "Substitution is one pass and residue is checked on the result, so an answer cannot smuggle in template text" "$SRC_INST" +HOLES='["OWNER","REPO"]' +h1="$(blob $'= {{REPO}} of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" +answers '{"OWNER":"{{REPO}}","REPO":"widget"}' + +# From the engine-neutral mint-defect list (work order T6, row SC-T-002). +new_case instantiate-literal-answer instantiate ok "" "An answer with shell and sed metacharacters renders literally" \ + "Answers are data: substituted byte for byte, never interpreted" \ + "rsr-template-repo tests/e2e/use_template_mint_test.sh (existing control: answer with '&' and '|'), as listed in T6 SC-T-002" \ + '{"expect":{"results":{"README.adoc":"written"}}}' +HOLES='["OWNER"]' +h1="$(blob $'= Repository of {{OWNER}}\n')" +plan "$(w README.adoc "$h1" 644 absent)" +# shellcheck disable=SC2016 # the dollar and backticks are literal answer text +answers '{"OWNER":"a&b|c\\1 $HOME `x` {{ y }} /z"}' +put expected README.adoc $'= Repository of a&b|c\\1 $HOME `x` {{ y }} /z\n' + +# ── refusals: target state ────────────────────────────────────────────────── + +new_case precondition-expect-absent apply refused PRECONDITION "expect absent, but a file with other content exists" \ + "No silent overwrite: there is no overwrite-whatever-is-there" "$SRC_ADR2" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" +put before README.adoc $'= My own README\n' + +new_case precondition-expect-sha apply refused PRECONDITION "expect sha256, but the content differs" \ + "A replacement needs exactly the base content the planner saw" "$SRC_APPLY" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 "$(sha $'= Old\n')")" +put before README.adoc $'= Old, then edited by the user\n' + +new_case precondition-expect-sha-absent apply refused PRECONDITION "expect sha256, but the path is absent" \ + "A replacement of something that is not there is not a creation" "$SRC_APPLY" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 "$(sha $'= Old\n')")" +keep_before + +new_case precondition-delete-wrong-sha apply refused PRECONDITION "Delete of a file whose content differs" \ + "A delete removes only the content the planner saw" "$SRC_APPLY" +plan "$(del old.txt "$(sha $'obsolete\n')")" +put before old.txt $'obsolete, but edited by the user\n' + +new_case precondition-ancestor-file apply refused PRECONDITION "A planned path under an existing file" \ + "A planned path needs directories, not files, above it" "$SRC_APPLY" +h1="$(blob "$INDEX")" +plan "$(w docs/index.adoc "$h1" 644 absent)" +put before docs $'a file, not a directory\n' + +new_case all-or-nothing apply refused PRECONDITION "The last operation fails its precondition" \ + "All or nothing: a refused plan leaves the target byte-identical, including the first operations" "$SRC_APPLY" +h1="$(blob $'first\n')"; h2="$(blob $'second\n')"; h3="$(blob $'third\n')" +plan "$(w a.txt "$h1" 644 absent)" "$(w b/b.txt "$h2" 755 absent)" "$(w c.txt "$h3" 644 absent)" +put before c.txt $'the user wrote this\n' + +new_case target-symlink apply refused TARGET_SYMLINK "An ancestor directory is a link pointing outside" \ + "No symlink escape: links are never followed when writing" "$SRC_ADR2" +h1="$(blob "$README")"; h2="$(blob "$INDEX")" +plan "$(w README.adoc "$h1" 644 absent)" "$(w docs/index.adoc "$h2" 644 absent)" +mkdir -p "$D/before"; ln -s ../outside "$D/before/docs" + +new_case target-symlink-leaf apply refused TARGET_SYMLINK "The planned path itself is a link pointing outside" \ + "No symlink escape: a link at a planned path is not read through or written through" "$SRC_ADR2" +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 "$(sha $'= Old\n')")" +mkdir -p "$D/before"; ln -s ../outside/README.adoc "$D/before/README.adoc" + +new_case target-invalid-absent apply refused TARGET_INVALID "The target does not exist" \ + "Apply needs an existing target directory; it does not create one" "$SRC_APPLY" '{"target":"absent"}' +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" + +new_case target-invalid-file apply refused TARGET_INVALID "The target is a regular file" \ + "Apply needs an existing target directory" "$SRC_APPLY" '{"target":"file"}' +h1="$(blob "$README")" +plan "$(w README.adoc "$h1" 644 absent)" + +new_case check-path-unsafe check refused PATH_UNSAFE "check refuses an unsafe path" \ + "check applies the same safety rules as apply" "$SRC_SAFE" +h1="$(blob "$README")" +plan "$(w ../README.adoc "$h1" 644 absent)" + +if [ "$MODE" = check ]; then + if diff -r --no-dereference "$HERE/cases/kernel/L0" "$L0" >"$TMP/diff" 2>&1; then + echo "gen-cases: committed cases match the generator ($(find "$L0" -name case.json | wc -l) cases)" + else + echo "gen-cases: committed cases differ from the generator:" >&2 + head -40 "$TMP/diff" >&2 + exit 1 + fi +else + echo "gen-cases: wrote $(find "$L0" -name case.json | wc -l) cases under $L0" +fi diff --git a/verification/conformance/run.sh b/verification/conformance/run.sh new file mode 100755 index 0000000..3223434 --- /dev/null +++ b/verification/conformance/run.sh @@ -0,0 +1,391 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# run.sh — engine-neutral conformance runner (verification/conformance/README.adoc). +# +# run.sh --kernel "" [--planner ""] [--level L0|L1|L2|L3] [--cases DIR] +# +# For each case directory cases//// at or below the +# requested level (default L3), the runner copies the inputs and before/ into +# a fresh sandbox, runs the case's kind (check, instantiate, apply, +# apply-twice, plan) and asserts the README's contract. It prints one line per +# case (ok / FAIL / SKIP), then totals per level. +# +# Exit 0: every case at or below the level passed. Exit 1: any FAIL, or any +# SKIP at or below the level (a skip is never a pass). Exit 2: the runner could +# not run (usage, missing tool, no case found, malformed case.json). +# +# Command strings are split into words on whitespace with `read -a` (no eval, +# no globbing, no quote processing): a command whose path contains spaces is +# not supported. A first word containing `/` is made absolute, because the +# engine runs with its working directory inside the sandbox. +set -euo pipefail + +usage() { + sed -n '7,7p' "$0" | sed 's/^# *//' >&2 + exit 2 +} + +KERNEL_CMD="" +PLANNER_CMD="" +LEVEL="L3" +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +CASES="$HERE/cases" + +while [ "$#" -gt 0 ]; do + case "$1" in + --kernel) KERNEL_CMD="${2:-}"; shift 2 || usage ;; + --planner) PLANNER_CMD="${2:-}"; shift 2 || usage ;; + --level) LEVEL="${2:-}"; shift 2 || usage ;; + --cases) CASES="${2:-}"; shift 2 || usage ;; + *) usage ;; + esac +done + +case "$LEVEL" in L0 | L1 | L2 | L3) ;; *) echo "run.sh: --level must be L0..L3" >&2; exit 2 ;; esac +[ -n "$KERNEL_CMD" ] || { echo "run.sh: --kernel is required" >&2; exit 2; } +[ -d "$CASES" ] || { echo "run.sh: cases directory $CASES not found" >&2; exit 2; } +for tool in jq sha256sum find stat sort cmp timeout mktemp readlink; do + command -v "$tool" >/dev/null 2>&1 || { echo "run.sh: $tool not found" >&2; exit 2; } +done + +# Split a command string into an argv array (named by $1) without eval. +split_cmd() { + local -n _out="$1" + read -r -a _out <<<"$2" + if [ "${#_out[@]}" -eq 0 ]; then + return 1 + fi + if [[ "${_out[0]}" == */* ]]; then + _out[0]="$(cd "$(dirname "${_out[0]}")" && pwd)/$(basename "${_out[0]}")" + fi +} + +KERNEL=() +PLANNER=() +split_cmd KERNEL "$KERNEL_CMD" || { echo "run.sh: empty --kernel" >&2; exit 2; } +if [ -n "$PLANNER_CMD" ]; then + split_cmd PLANNER "$PLANNER_CMD" || { echo "run.sh: empty --planner" >&2; exit 2; } +fi + +level_num() { echo "${1#L}"; } +MAXLEVEL="$(level_num "$LEVEL")" +TIMEOUT="${CONFORMANCE_TIMEOUT:-60}" + +WORKROOT="$(mktemp -d)" +trap 'rm -rf "$WORKROOT"' EXIT + +# ── tree manifests ────────────────────────────────────────────────────────── +# One line per entry, sorted, paths %q-escaped so any byte is representable: +# f regular file (x = owner-execute bit set) +# l symbolic link (never followed) +# d directory (only when $2 = 1) +# o anything else +# Further arguments are paths to prune from the walk. +manifest() { + local root="$1" dirs="$2" + shift 2 + if [ -L "$root" ]; then + printf 'root-link %q\n' "$(readlink -- "$root")" + return + fi + if [ ! -e "$root" ]; then + echo "root-absent" + return + fi + if [ ! -d "$root" ]; then + printf 'root-file %s\n' "$(sha256sum <"$root" | cut -c1-64)" + return + fi + local -a expr=() + if [ "$#" -gt 0 ]; then + expr+=("(") + local first=1 p + for p in "$@"; do + if [ "$first" = 0 ]; then expr+=(-o); fi + expr+=(-path "$p") + first=0 + done + expr+=(")" -prune -o) + fi + find "$root" -mindepth 1 "${expr[@]}" -print0 | LC_ALL=C sort -z | while IFS= read -r -d '' p; do + local rel="${p#"$root"/}" + if [ -L "$p" ]; then + printf 'l %q %q\n' "$rel" "$(readlink -- "$p")" + elif [ -d "$p" ]; then + if [ "$dirs" = 1 ]; then printf 'd %q\n' "$rel"; fi + elif [ -f "$p" ]; then + local mode x + mode="$(stat -c %a -- "$p")" + x="-" + if (((8#$mode & 8#100) != 0)); then x="x"; fi + printf 'f %s %s %q\n' "$x" "$(sha256sum <"$p" | cut -c1-64)" "$rel" + else + printf 'o %q\n' "$rel" + fi + done +} + +# Print a short difference between two manifests (for FAIL reasons). +mdiff() { + diff <(echo "$1") <(echo "$2") | grep '^[<>]' | head -3 | tr '\n' ';' || true +} + +# ── per-case state ────────────────────────────────────────────────────────── +REASON="" +fail() { REASON="$1"; return 1; } + +# Run an engine with stdout/stderr captured; sets RC. $1 = log name. +run_engine() { + local name="$1" + shift + RC=0 + (cd "$CWD" && timeout "$TIMEOUT" "$@") >"$C/log/$name.out" 2>"$C/log/$name.err" || RC=$? +} + +# Is the file's content its own JCS form (as far as jq can tell), with at +# most one final line feed ($2 = "lf" requires exactly one)? +is_jcs_file() { + local f="$1" need="$2" canon body + canon="$(jq -cS . <"$f" 2>/dev/null)" || return 1 + body="$(cat -- "$f"; echo x)" + body="${body%x}" + if [ "$need" = lf ]; then + [ "$body" = "$canon"$'\n' ] + else + [ "$body" = "$canon"$'\n' ] || [ "$body" = "$canon" ] + fi +} + +assert_refused() { # $1 log name, $2 expected code + local out="$C/log/$1.out" got + [ "$RC" = 10 ] || { + if [ "$RC" = 0 ]; then fail "accepted; expected refusal $2"; else fail "crashed (exit $RC); expected refusal $2"; fi + return 1 + } + jq -e 'type == "object" and (.refused | type) == "string" and (.detail | type) == "string"' <"$out" >/dev/null 2>&1 || + fail "refusal output is not {\"refused\":...,\"detail\":...}" || return 1 + is_jcs_file "$out" any || fail "refusal output is not JCS" || return 1 + got="$(jq -r .refused <"$out")" + [ "$got" = "$2" ] || fail "refused $got; expected $2" || return 1 +} + +assert_escape_free() { + local now + now="$(manifest "$C" 1 "$TARGET" "$C/out" "$C/log")" + [ "$now" = "$ESCAPE0" ] || fail "wrote outside the target: $(mdiff "$ESCAPE0" "$now")" +} + +assert_target_unchanged() { + local now + now="$(manifest "$TARGET" 1)" + [ "$now" = "$TARGET0" ] || fail "target changed although refused: $(mdiff "$TARGET0" "$now")" +} + +assert_tree_expected() { + local want got + want="$(manifest "$CASE/expected" 0)" + if [ ! -d "$CASE/expected" ]; then want=""; fi + got="$(manifest "$TARGET" 0)" + [ "$got" = "$want" ] || fail "tree differs from expected/: $(mdiff "$want" "$got")" +} + +# $1 receipt, $2 plan file. Checks shape, digest and paths; with $3 = "rerun" +# also that every result is unchanged/already-absent. +assert_receipt() { + local r="$1" plan="$2" mode="${3:-}" digest + [ -f "$r" ] || fail "no receipt written" || return 1 + is_jcs_file "$r" lf || fail "receipt is not JCS followed by one line feed" || return 1 + digest="sha256:$(sha256sum <"$plan" | cut -c1-64)" + jq -e --arg d "$digest" '.plan == $d' <"$r" >/dev/null || fail "receipt plan digest is not $digest" || return 1 + jq -e --slurpfile p "$plan" '(.ops | map(.path)) == ($p[0].ops | map(.path))' <"$r" >/dev/null || + fail "receipt does not list the plan's paths in order" || return 1 + jq -e '.ops | all(.result | IN("written", "unchanged", "deleted", "already-absent"))' <"$r" >/dev/null || + fail "receipt has an unknown result" || return 1 + if [ "$mode" = rerun ]; then + jq -e '.ops | all(.result | IN("unchanged", "already-absent"))' <"$r" >/dev/null || + fail "second application did work: $(jq -c '[.ops[] | select(.result | IN("written", "deleted"))]' <"$r")" || return 1 + elif jq -e '.expect | has("results")' "$CASE/case.json" >/dev/null; then + jq -e --slurpfile c "$CASE/case.json" '(.ops | map({(.path): .result}) | add // {}) == $c[0].expect.results' <"$r" >/dev/null || + fail "receipt results $(jq -c '.ops | map({(.path): .result}) | add // {}' <"$r") differ from expected" || return 1 + fi +} + +assert_excludes() { + local s + while IFS= read -r s; do + [ -n "$s" ] || continue + if grep -rqF -- "$s" "$TARGET" 2>/dev/null; then + fail "the resulting tree contains the excluded string $(printf '%q' "$s")" || return 1 + fi + done < <(jq -r '.expect.tree_excludes // [] | .[]' "$CASE/case.json") +} + +kernel_apply() { # $1 log name, $2 plan, $3 blobs, $4 receipt + run_engine "$1" "${KERNEL[@]}" apply --plan "$2" --blobs "$3" --target "$TARGET" --receipt "$4" +} + +# Check case.json; prints nothing, returns 1 with REASON on a bad case. +validate_case() { + local dir="$1" half="$2" lvl="$3" id="$4" + [ -f "$dir/case.json" ] || fail "case.json missing" || return 1 + is_jcs_file "$dir/case.json" lf || fail "case.json is not JCS followed by one line feed" || return 1 + jq -e --arg id "$id" --arg lvl "$lvl" --arg half "$half" ' + (.id == $id) and (.level == $lvl) + and (.kind | IN("check", "instantiate", "apply", "apply-twice", "plan")) + and ((.kind == "plan") == ($half == "planner")) + and (.expect.outcome | IN("ok", "refused")) + and (if .expect.outcome == "refused" then (.expect.code | type) == "string" else (.expect | has("code") | not) end) + and ([.principle, .source, .title] | all(type == "string" and length > 0)) + and ((.target // "directory") | IN("directory", "absent", "file")) + ' "$dir/case.json" >/dev/null || fail "case.json does not follow the case schema" || return 1 +} + +run_case() { + local half="$1" lvl="$2" id="$3" + CASE="$CASES/$half/$lvl/$id" + validate_case "$CASE" "$half" "$lvl" "$id" || return 1 + local kind outcome code target_kind + kind="$(jq -r .kind "$CASE/case.json")" + outcome="$(jq -r .expect.outcome "$CASE/case.json")" + code="$(jq -r '.expect.code // ""' "$CASE/case.json")" + target_kind="$(jq -r '.target // "directory"' "$CASE/case.json")" + + if [ "$kind" = plan ] && [ "${#PLANNER[@]}" -eq 0 ]; then + REASON="needs --planner" + return 2 + fi + + # Sandbox: inputs are copies, so an engine cannot alter the suite. + C="$(mktemp -d "$WORKROOT/case.XXXXXX")" + mkdir -p "$C/box/in" "$C/box/l1/l2/cwd" "$C/box/l1/l2/outside" "$C/out" "$C/log" + TARGET="$C/box/l1/l2/target" + CWD="$C/box/l1/l2/cwd" + local f + for f in plan.json answers.json; do + if [ -f "$CASE/$f" ]; then cp -- "$CASE/$f" "$C/box/in/$f"; fi + done + for f in blobs inputs; do + if [ -d "$CASE/$f" ]; then cp -a -- "$CASE/$f" "$C/box/in/$f"; else mkdir -p "$C/box/in/$f"; fi + done + case "$target_kind" in + directory) + mkdir -p "$TARGET" + if [ -d "$CASE/before" ]; then cp -a -- "$CASE/before/." "$TARGET/"; fi + ;; + file) printf 'not a directory\n' >"$TARGET" ;; + absent) ;; + esac + TARGET0="$(manifest "$TARGET" 1)" + ESCAPE0="$(manifest "$C" 1 "$TARGET" "$C/out" "$C/log")" + local plan="$C/box/in/plan.json" blobs="$C/box/in/blobs" + + case "$kind" in + check) + run_engine check "${KERNEL[@]}" check --plan "$plan" --blobs "$blobs" + if [ "$outcome" = refused ]; then assert_refused check "$code" || return 1 + else [ "$RC" = 0 ] || fail "check exited $RC; expected 0" || return 1; fi + assert_target_unchanged || return 1 + ;; + apply | apply-twice) + kernel_apply apply1 "$plan" "$blobs" "$C/out/receipt1.json" + if [ "$outcome" = refused ]; then + assert_refused apply1 "$code" || return 1 + assert_target_unchanged || return 1 + [ ! -e "$C/out/receipt1.json" ] || fail "a receipt was written although refused" || return 1 + else + [ "$RC" = 0 ] || fail "apply exited $RC; expected 0 ($(head -c 200 "$C/log/apply1.out"))" || return 1 + assert_tree_expected || return 1 + assert_receipt "$C/out/receipt1.json" "$plan" || return 1 + assert_excludes || return 1 + if [ "$kind" = apply-twice ]; then + local after + after="$(manifest "$TARGET" 1)" + kernel_apply apply2 "$plan" "$blobs" "$C/out/receipt2.json" + [ "$RC" = 0 ] || fail "second apply exited $RC; expected 0" || return 1 + [ "$(manifest "$TARGET" 1)" = "$after" ] || fail "second apply changed the tree" || return 1 + assert_receipt "$C/out/receipt2.json" "$plan" rerun || return 1 + fi + fi + ;; + instantiate) + run_engine inst "${KERNEL[@]}" instantiate --plan "$plan" --blobs "$blobs" \ + --answers "$C/box/in/answers.json" --out "$C/out/closed.json" --out-blobs "$C/out/blobs" + if [ "$outcome" = refused ]; then + assert_refused inst "$code" || return 1 + [ ! -e "$C/out/closed.json" ] || fail "an instantiated plan was written although refused" || return 1 + assert_target_unchanged || return 1 + else + [ "$RC" = 0 ] || fail "instantiate exited $RC; expected 0 ($(head -c 200 "$C/log/inst.out"))" || return 1 + [ -f "$C/out/closed.json" ] || fail "no instantiated plan written" || return 1 + is_jcs_file "$C/out/closed.json" lf || fail "instantiated plan is not JCS followed by one line feed" || return 1 + jq -e '.holes == []' <"$C/out/closed.json" >/dev/null || fail "instantiated plan still has holes" || return 1 + kernel_apply apply1 "$C/out/closed.json" "$C/out/blobs" "$C/out/receipt1.json" + [ "$RC" = 0 ] || fail "apply of the instantiated plan exited $RC" || return 1 + assert_tree_expected || return 1 + assert_receipt "$C/out/receipt1.json" "$C/out/closed.json" || return 1 + assert_excludes || return 1 + fi + ;; + plan) + run_engine plan "${PLANNER[@]}" plan --inputs "$C/box/in/inputs" --out "$C/out/plan.json" --out-blobs "$C/out/blobs" + if [ "$outcome" = refused ]; then + assert_refused plan "$code" || return 1 + [ ! -e "$C/out/plan.json" ] || fail "a plan was written although refused" || return 1 + else + [ "$RC" = 0 ] || fail "planner exited $RC; expected 0" || return 1 + kernel_apply apply1 "$C/out/plan.json" "$C/out/blobs" "$C/out/receipt1.json" + [ "$RC" = 0 ] || fail "apply of the planned plan exited $RC" || return 1 + assert_tree_expected || return 1 + assert_receipt "$C/out/receipt1.json" "$C/out/plan.json" || return 1 + assert_excludes || return 1 + fi + ;; + esac + assert_escape_free || return 1 + return 0 +} + +declare -A OK=() BAD=() SKIPPED=() +TOTAL=0 +for half in kernel planner; do + for n in 0 1 2 3; do + lvl="L$n" + [ "$n" -le "$MAXLEVEL" ] || continue + [ -d "$CASES/$half/$lvl" ] || continue + while IFS= read -r -d '' dir; do + id="$(basename "$dir")" + TOTAL=$((TOTAL + 1)) + REASON="" + status=0 + run_case "$half" "$lvl" "$id" || status=$? + case "$status" in + 0) OK[$lvl]=$((${OK[$lvl]:-0} + 1)); printf 'ok %s/%s/%s\n' "$half" "$lvl" "$id" ;; + 2) SKIPPED[$lvl]=$((${SKIPPED[$lvl]:-0} + 1)); printf 'SKIP %s/%s/%s: %s\n' "$half" "$lvl" "$id" "$REASON" ;; + *) BAD[$lvl]=$((${BAD[$lvl]:-0} + 1)); printf 'FAIL %s/%s/%s: %s\n' "$half" "$lvl" "$id" "${REASON:-unknown}" ;; + esac + done < <(find "$CASES/$half/$lvl" -mindepth 1 -maxdepth 1 -type d -print0 | LC_ALL=C sort -z) + done +done + +if [ "$TOTAL" -eq 0 ]; then + echo "run.sh: no case found at or below $LEVEL under $CASES" >&2 + exit 2 +fi + +echo "---" +rc=0 +for n in 0 1 2 3; do + [ "$n" -le "$MAXLEVEL" ] || continue + lvl="L$n" + o="${OK[$lvl]:-0}" b="${BAD[$lvl]:-0}" s="${SKIPPED[$lvl]:-0}" + printf '%s: %d ok, %d FAIL, %d SKIP\n' "$lvl" "$o" "$b" "$s" + if [ "$b" -gt 0 ] || [ "$s" -gt 0 ]; then rc=1; fi +done +if [ "$rc" = 0 ]; then + echo "level $LEVEL: PASS ($TOTAL cases)" +else + echo "level $LEVEL: NOT PASSED (a level passes only when every case at and below it passes; skips do not pass)" +fi +exit "$rc" diff --git a/verification/conformance/selftest.sh b/verification/conformance/selftest.sh new file mode 100755 index 0000000..98bf685 --- /dev/null +++ b/verification/conformance/selftest.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# selftest.sh — prove the conformance suite has teeth. +# +# selftest.sh [--level L0|L1|L2|L3] [--cases DIR] +# +# Runs run.sh against every deliberately wrong kernel in controls/ +# (*-kernel.sh) and requires the suite to FAIL each of them (run.sh exit 1). +# For each control it lists the cases that caught it. Exits 1 if any control +# passes (the suite is broken) or the runner could not run on it (exit 2), and +# 2 if there are no controls. +set -euo pipefail + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +LEVEL="L0" +CASES="$HERE/cases" +while [ "$#" -gt 0 ]; do + case "$1" in + --level) LEVEL="${2:-}"; shift 2 ;; + --cases) CASES="${2:-}"; shift 2 ;; + *) echo "usage: selftest.sh [--level L0|L1|L2|L3] [--cases DIR]" >&2; exit 2 ;; + esac +done + +mapfile -t CONTROLS < <(find "$HERE/controls" -maxdepth 1 -type f -name '*-kernel.sh' | LC_ALL=C sort) +if [ "${#CONTROLS[@]}" -eq 0 ]; then + echo "selftest: no controls found in $HERE/controls" >&2 + exit 2 +fi + +status=0 +for control in "${CONTROLS[@]}"; do + name="$(basename "$control")" + rc=0 + out="$("$HERE/run.sh" --kernel "$control" --level "$LEVEL" --cases "$CASES")" || rc=$? + caught="$(grep -c '^FAIL ' <<<"$out" || true)" + total="$(grep -cE '^(ok|FAIL|SKIP) ' <<<"$out" || true)" + case "$rc" in + 1) + echo "control $name: FAILED by the suite, as required ($caught of $total cases caught it)" + grep '^FAIL ' <<<"$out" | sed -E 's/^FAIL ([^:]*): (.*)$/ caught by \1 -- \2/' + ;; + 0) + echo "control $name: PASSED $LEVEL -- the suite is broken (a deliberately wrong kernel conforms)" + status=1 + ;; + *) + echo "control $name: runner could not run (exit $rc); not evidence either way" + tail -3 <<<"$out" + status=1 + ;; + esac +done +if [ "$status" = 0 ]; then + echo "selftest: PASS (${#CONTROLS[@]} controls, each failed by the suite at $LEVEL)" +else + echo "selftest: FAIL" +fi +exit "$status" diff --git a/verification/proofs/README.adoc b/verification/proofs/README.adoc index eb22d4c..99d08b1 100644 --- a/verification/proofs/README.adoc +++ b/verification/proofs/README.adoc @@ -20,6 +20,7 @@ proofs/ ├── lean4/ # Lean4 proofs (algebra, lattices) │ └── ApiTypes.lean ├── agda/ # Agda proofs (induction, metatheory) +│ ├── PlanLaws/ # ADR-0003 plan laws (just proof-check-plan-laws) │ └── Properties.agda ├── coq/ # Coq proofs (type systems, compilation) │ └── TypeSafety.v diff --git a/verification/proofs/agda/PlanLaws/All.agda b/verification/proofs/agda/PlanLaws/All.agda new file mode 100644 index 0000000..a759b05 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/All.agda @@ -0,0 +1,30 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.All: the graded root of the plan-law development. +-- +-- Proves nothing itself. Checking this module checks every PlanLaws module, +-- and `agda --dependency-graph` on it gives the import cone that a proof +-- receipt records (PROOF-POLICY §1.1, §8.4). The modules and what each +-- proves: +-- Prelude the logic (no plan content); +-- Plan plans, lookup, union, ≈; +-- Join ADR-0003 law 1 and conflict soundness and completeness; +-- Apply ADR-0003 laws 3 and 4, and the converse of law 4; +-- Safety ADR-0003 law 2: true per path, false per plan (with the +-- exact condition and a counterexample); +-- Semilattice the total join on Plan/≈ with a top for conflict; +-- Kernel the refinement with preconditions (expect); +-- Example a concrete instance, so no law is vacuous. + +module PlanLaws.All where + +import PlanLaws.Prelude +import PlanLaws.Plan +import PlanLaws.Join +import PlanLaws.Apply +import PlanLaws.Safety +import PlanLaws.Semilattice +import PlanLaws.Kernel +import PlanLaws.Example diff --git a/verification/proofs/agda/PlanLaws/Apply.agda b/verification/proofs/agda/PlanLaws/Apply.agda new file mode 100644 index 0000000..6d50724 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Apply.agda @@ -0,0 +1,182 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Apply: applying a plan to a file system (ADR-0003 laws 3 and 4). +-- +-- A file system is a total map from paths to states (a file with content, +-- or absent). apply p fs overrides fs at the paths p mentions and leaves +-- every other path as it was. Proves: +-- apply-establishes after apply p, each path of p has its desired state; +-- apply-frame a path p does not mention is unchanged; +-- apply-idem apply p (apply p fs) ≗ apply p fs (law 3); +-- apply-join if p ⊔ q ≡ ok r then +-- apply r fs ≗ apply q (apply p fs) (law 4); +-- apply-comm for compatible p, q the two orders agree; +-- commute-compatible the converse: if the two orders agree on one file +-- system, then p and q are compatible, so +-- apply-comm-iff compatibility is exactly "apply commutes"; +-- apply-≈, apply-faithful +-- ≈ is exactly equality of effect: plans with equal +-- lookup have equal effect, and (given one content +-- value) plans with equal effect on every file system +-- are ≈. +-- +-- Equality used. On file systems, ≗: pointwise equality (a record around +-- (x : Path) → f x ≡ g x). Function extensionality is never assumed. +-- Preconditions (expect) are not modelled here; see PlanLaws.Kernel. + +open import PlanLaws.Prelude + +module PlanLaws.Apply + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + where + +open import PlanLaws.Plan Path _≟P_ Content _≟C_ +open import PlanLaws.Join Path _≟P_ Content _≟C_ + +infix 4 _≗_ + +------------------------------------------------------------------------ +-- File systems and their equality + +FS : Set +FS = Path → State + +record _≗_ (f g : FS) : Set where + constructor ≗-intro + field + ≗-at : (x : Path) → f x ≡ g x +open _≗_ public + +≗-refl : {f : FS} → f ≗ f +≗-refl = ≗-intro (λ x → refl) + +≗-sym : {f g : FS} → f ≗ g → g ≗ f +≗-sym e = ≗-intro (λ x → sym (≗-at e x)) + +≗-trans : {f g h : FS} → f ≗ g → g ≗ h → f ≗ h +≗-trans e e′ = ≗-intro (λ x → trans (≗-at e x) (≗-at e′ x)) + +------------------------------------------------------------------------ +-- Apply + +-- The desired state if there is one, else the current state. +override : Maybe State → State → State +override (just s) t = s +override nothing t = t + +apply : Plan → FS → FS +apply p fs x = override (lookup p x) (fs x) + +apply-establishes : (p : Plan) (fs : FS) {x : Path} {s : State} → + lookup p x ≡ just s → apply p fs x ≡ s +apply-establishes p fs {x} e = cong (λ m → override m (fs x)) e + +apply-frame : (p : Plan) (fs : FS) {x : Path} → + lookup p x ≡ nothing → apply p fs x ≡ fs x +apply-frame p fs {x} e = cong (λ m → override m (fs x)) e + +-- apply respects equality of file systems... +apply-cong : (p : Plan) {fs gs : FS} → fs ≗ gs → apply p fs ≗ apply p gs +apply-cong p e = ≗-intro (λ x → cong (override (lookup p x)) (≗-at e x)) + +-- ...and equality of plans. +apply-≈ : {p q : Plan} → p ≈ q → (fs : FS) → apply p fs ≗ apply q fs +apply-≈ e fs = ≗-intro (λ x → cong (λ m → override m (fs x)) (≈-at e x)) + +------------------------------------------------------------------------ +-- ADR-0003 law 3: applying a plan twice equals applying it once + +private + override-idem : (m : Maybe State) (t : State) → override m (override m t) ≡ override m t + override-idem (just s) t = refl + override-idem nothing t = refl + +apply-idem : (p : Plan) (fs : FS) → apply p (apply p fs) ≗ apply p fs +apply-idem p fs = ≗-intro (λ x → override-idem (lookup p x) (fs x)) + +------------------------------------------------------------------------ +-- ADR-0003 law 4: for compatible plans, applying the join is applying one, then +-- the other + +apply-∪ : (p q : Plan) → Compatible p q → (fs : FS) → + apply (p ∪ q) fs ≗ apply q (apply p fs) +apply-∪ p q h fs = ≗-intro at + where + at : (x : Path) → apply (p ∪ q) fs x ≡ apply q (apply p fs) x + at x with maybe-cases (lookup p x) + ... | inj₂ en = trans (cong (λ m → override m (fs x)) (∪-nothing p q en)) + (cong (λ m → override (lookup q x) (override m (fs x))) (sym en)) + ... | inj₁ (a , ea) = trans (cong (λ m → override m (fs x)) (∪-just p q ea)) + (trans (right (maybe-cases (lookup q x))) + (cong (λ m → override (lookup q x) (override m (fs x))) (sym ea))) + where + right : Σ State (λ b → lookup q x ≡ just b) ⊎ (lookup q x ≡ nothing) → + a ≡ override (lookup q x) a + right (inj₁ (b , eb)) = trans (agree h x ea eb) (cong (λ m → override m a) (sym eb)) + right (inj₂ en′) = cong (λ m → override m a) (sym en′) + +apply-join : (p q : Plan) {r : Plan} → p ⊔ q ≡ ok r → (fs : FS) → + apply r fs ≗ apply q (apply p fs) +apply-join p q e fs with ok-sound p q e +... | h , refl = apply-∪ p q h fs + +-- Hence the two orders agree. +apply-comm : (p q : Plan) → Compatible p q → (fs : FS) → + apply q (apply p fs) ≗ apply p (apply q fs) +apply-comm p q h fs = + ≗-trans (≗-sym (apply-∪ p q h fs)) + (≗-trans (apply-≈ (∪-comm p q h) fs) (apply-∪ q p (compatible-sym h) fs)) + +-- The converse: if the two orders agree on one file system, the plans are +-- compatible. (At a path both plans mention, applying q last leaves q's +-- state and applying p last leaves p's.) So no side condition beyond +-- compatibility is needed, and none can be dropped. +commute-compatible : (p q : Plan) (fs : FS) → + apply q (apply p fs) ≗ apply p (apply q fs) → Compatible p q +commute-compatible p q fs e = compatible at + where + at : (x : Path) → CompatibleAt p q x + at x {a} {b} ea eb = + sym (trans (cong₂ (λ m n → override m (override n (fs x))) (sym eb) (sym ea)) + (trans (≗-at e x) + (cong₂ (λ m n → override m (override n (fs x))) ea eb))) + +apply-comm-iff : (p q : Plan) → + Compatible p q ⇔ ((fs : FS) → apply q (apply p fs) ≗ apply p (apply q fs)) +apply-comm-iff p q = + mk⇔ (apply-comm p q) (λ c → commute-compatible p q (λ _ → absent) (c (λ _ → absent))) + +------------------------------------------------------------------------ +-- ≈ is exactly equality of effect + +private + -- A state other than s (needs one content value). + other : Content → State → State + other c₀ (file _) = absent + other c₀ absent = file c₀ + + other-≢ : (c₀ : Content) (s : State) → ¬ (s ≡ other c₀ s) + other-≢ c₀ (file c) e = file≢absent e + other-≢ c₀ absent e = file≢absent (sym e) + +apply-faithful : Content → (p q : Plan) → + ((fs : FS) → apply p fs ≗ apply q fs) → p ≈ q +apply-faithful c₀ p q obs = ≈-intro at + where + -- Observe both plans at x on a constant file system. + seen : (x : Path) (t : State) {m n : Maybe State} → + lookup p x ≡ m → lookup q x ≡ n → override m t ≡ override n t + seen x t em en = + trans (cong (λ m → override m t) (sym em)) + (trans (≗-at (obs (λ _ → t)) x) (cong (λ n → override n t) en)) + + at : (x : Path) → lookup p x ≡ lookup q x + at x with maybe-cases (lookup p x) | maybe-cases (lookup q x) + ... | inj₁ (a , ea) | inj₁ (b , eb) = + trans ea (trans (cong just (seen x absent ea eb)) (sym eb)) + ... | inj₁ (a , ea) | inj₂ en = ⊥-elim (other-≢ c₀ a (seen x (other c₀ a) ea en)) + ... | inj₂ en | inj₁ (b , eb) = ⊥-elim (other-≢ c₀ b (sym (seen x (other c₀ b) en eb))) + ... | inj₂ en | inj₂ en′ = trans en (sym en′) diff --git a/verification/proofs/agda/PlanLaws/Example.agda b/verification/proofs/agda/PlanLaws/Example.agda new file mode 100644 index 0000000..44ec233 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Example.agda @@ -0,0 +1,90 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Example: a concrete instance, so that no law is vacuous. +-- +-- Three paths (README.adoc, readme.adoc, LICENSE) and two contents. Shows, +-- by evaluation (refl), that the join computes: two packs writing one path +-- differently give a conflict naming that path, two packs writing it the +-- same way join, and the join is order-independent. Then instantiates +-- PlanLaws.Safety with a case-fold clash relation and obtains the +-- counterexample: README.adoc and readme.adoc are each a safe one-entry +-- plan, they are compatible, and their join is not plan-safe. + +module PlanLaws.Example where + +open import PlanLaws.Prelude + +data P : Set where + README-adoc readme-adoc LICENSE : P + +_≟P_ : (x y : P) → Dec (x ≡ y) +README-adoc ≟P README-adoc = yes refl +README-adoc ≟P readme-adoc = no (λ ()) +README-adoc ≟P LICENSE = no (λ ()) +readme-adoc ≟P README-adoc = no (λ ()) +readme-adoc ≟P readme-adoc = yes refl +readme-adoc ≟P LICENSE = no (λ ()) +LICENSE ≟P README-adoc = no (λ ()) +LICENSE ≟P readme-adoc = no (λ ()) +LICENSE ≟P LICENSE = yes refl + +data C : Set where + blob₁ blob₂ : C + +_≟C_ : (c d : C) → Dec (c ≡ d) +blob₁ ≟C blob₁ = yes refl +blob₁ ≟C blob₂ = no (λ ()) +blob₂ ≟C blob₁ = no (λ ()) +blob₂ ≟C blob₂ = yes refl + +open import PlanLaws.Plan P _≟P_ C _≟C_ +open import PlanLaws.Join P _≟P_ C _≟C_ + +pack-A pack-B pack-B′ : Plan +pack-A = (LICENSE , file blob₁) ∷ (README-adoc , file blob₁) ∷ [] +pack-B = (README-adoc , file blob₂) ∷ [] +pack-B′ = (README-adoc , file blob₁) ∷ (readme-adoc , absent) ∷ [] + +-- Two packs write README.adoc differently: a conflict at README.adoc, in +-- either order. Never last-writer-wins. +conflict-AB : pack-A ⊔ pack-B ≡ conflict README-adoc +conflict-AB = refl + +conflict-BA : pack-B ⊔ pack-A ≡ conflict README-adoc +conflict-BA = refl + +-- Two packs write README.adoc the same way: they join. +joined-AB′ : pack-A ⊔ pack-B′ ≡ ok (pack-A ∪ pack-B′) +joined-AB′ = refl + +------------------------------------------------------------------------ +-- Plan-level safety: a case-fold clash + +data Clash : P → P → Set where + fold₁ : Clash README-adoc readme-adoc + fold₂ : Clash readme-adoc README-adoc + +clash-sym : {x y : P} → Clash x y → Clash y x +clash-sym fold₁ = fold₂ +clash-sym fold₂ = fold₁ + +clash-irrefl : {x : P} → ¬ Clash x x +clash-irrefl () + +-- Every path of this example is individually safe. +Safe : P → Set +Safe _ = ⊤ + +open import PlanLaws.Safety P _≟P_ C _≟C_ Safe Clash clash-sym clash-irrefl + +-- README.adoc in one pack and readme.adoc in another: each plan is safe, +-- they are compatible and join, and the joined plan is not. +case-fold-counterexample : + PlanSafe ((README-adoc , file blob₁) ∷ []) × + PlanSafe ((readme-adoc , file blob₂) ∷ []) × + Σ Plan (λ r → ((README-adoc , file blob₁) ∷ []) ⊔ ((readme-adoc , file blob₂) ∷ []) ≡ ok r + × ¬ PlanSafe r) +case-fold-counterexample = + plan-safety-not-preserved README-adoc readme-adoc tt tt fold₁ (file blob₁) (file blob₂) diff --git a/verification/proofs/agda/PlanLaws/Join.agda b/verification/proofs/agda/PlanLaws/Join.agda new file mode 100644 index 0000000..8e9533d --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Join.agda @@ -0,0 +1,513 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Join: composition of plans is a join, not an overwrite +-- (ADR-0003, "Composition is a join, not an overwrite", law 1, and the +-- never-last-writer-wins guarantee). +-- +-- Proves, for the join _⊔_ : Plan → Plan → Outcome, which either reports a +-- conflict at a path or returns the union: +-- conflict-sound a reported path is given two different desired states; +-- conflict-complete if some path is given two different desired states, +-- the join reports a conflict; +-- join-ok, ok-sound otherwise the join is the union, and only then; +-- join-lub the result is the least plan extending both inputs, so +-- it keeps every desired state of each (no last writer); +-- join-defined-sym definedness is symmetric; +-- join-comm p ⊔ q ~ q ⊔ p; +-- join-assoc (p ⊔ q) ⊔ r ~ p ⊔ (q ⊔ r), with +-- join-assoc-defined either side is defined exactly when p, q and r are +-- pairwise compatible; +-- join-idem p ⊔ p ~ ok p; +-- join-cong _⊔_ respects ≈ on both arguments. +-- +-- Equality used. On plans, ≈ (pointwise equality of lookup; PlanLaws.Plan). +-- On outcomes, ~: two conflicts are related whatever paths they name, and +-- ok r ~ ok s exactly when r ≈ s. The conflict path is deliberately left out +-- of ~: p ⊔ q and q ⊔ p can name different conflicting paths (each names +-- the first one in its left argument), and conflict-sound says each named +-- path is a genuine conflict. +-- +-- Out of scope: a replacement that an input contract authorises by name +-- (ADR-0003; issue #70). It is not a join and is not modelled here. + +open import PlanLaws.Prelude + +module PlanLaws.Join + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + where + +open import PlanLaws.Plan Path _≟P_ Content _≟C_ + +infixl 6 _⊔_ _⊔ᴼ_ +infix 4 _⊑_ _~_ + +------------------------------------------------------------------------ +-- Compatibility and conflicts + +-- p and q agree at x: if both give x a desired state, it is the same one. +CompatibleAt : Plan → Plan → Path → Set +CompatibleAt p q x = {a b : State} → lookup p x ≡ just a → lookup q x ≡ just b → a ≡ b + +-- p and q agree on every path both mention. (A record, so that p and q can +-- be inferred from a proof.) +record Compatible (p q : Plan) : Set where + constructor compatible + field + agree : (x : Path) → CompatibleAt p q x +open Compatible public + +-- A path that p and q give two different desired states. +record Conflict (p q : Plan) : Set where + constructor conflict-at + field + path : Path + left : State + right : State + in-left : lookup p path ≡ just left + in-right : lookup q path ≡ just right + differ : ¬ (left ≡ right) + +conflict-incompatible : {p q : Plan} → Conflict p q → ¬ Compatible p q +conflict-incompatible (conflict-at x a b ea eb ne) h = ne (agree h x ea eb) + +private + compatible-at? : (p q : Plan) (x : Path) → Conflict p q ⊎ CompatibleAt p q x + compatible-at? p q x with maybe-cases (lookup p x) | maybe-cases (lookup q x) + ... | inj₂ en | _ = inj₂ (λ ea _ → ⊥-elim (nothing≢just (trans (sym en) ea))) + ... | inj₁ _ | inj₂ en = inj₂ (λ _ eb → ⊥-elim (nothing≢just (trans (sym en) eb))) + ... | inj₁ (a , ea) | inj₁ (b , eb) with a ≟S b + ... | no ne = inj₁ (conflict-at x a b ea eb ne) + ... | yes a≡b = inj₂ (λ ea′ eb′ → + trans (just-injective (trans (sym ea′) ea)) + (trans a≡b (just-injective (trans (sym eb) eb′)))) + + compatible-on? : (p q : Plan) (ks : List Path) → + Conflict p q ⊎ ((x : Path) → x ∈ ks → CompatibleAt p q x) + compatible-on? p q [] = inj₂ (λ x ()) + compatible-on? p q (k ∷ ks) with compatible-at? p q k + ... | inj₁ c = inj₁ c + ... | inj₂ hk with compatible-on? p q ks + ... | inj₁ c = inj₁ c + ... | inj₂ hs = inj₂ λ { x (inj₁ x≡k) → subst (CompatibleAt p q) (sym x≡k) hk + ; x (inj₂ m) → hs x m } + +-- The decision procedure: a conflict, or a proof of compatibility. It +-- inspects the paths of p in order and reports the first that conflicts. +compatible? : (p q : Plan) → Conflict p q ⊎ Compatible p q +compatible? p q with compatible-on? p q (keys p) +... | inj₁ c = inj₁ c +... | inj₂ h = inj₂ (compatible (λ x ea eb → h x (lookup-keys p ea) ea eb)) + +compatible-dec : (p q : Plan) → Dec (Compatible p q) +compatible-dec p q with compatible? p q +... | inj₁ c = no (conflict-incompatible c) +... | inj₂ h = yes h + +------------------------------------------------------------------------ +-- The join + +-- What a kernel returns: a refusal naming a path, or the composed plan. +data Outcome : Set where + conflict : Path → Outcome + ok : Plan → Outcome + +outcome : (p q : Plan) → Conflict p q ⊎ Compatible p q → Outcome +outcome p q (inj₁ c) = conflict (Conflict.path c) +outcome p q (inj₂ _) = ok (p ∪ q) + +_⊔_ : Plan → Plan → Outcome +p ⊔ q = outcome p q (compatible? p q) + +private + ok-injective : {r s : Plan} → ok r ≡ ok s → r ≡ s + ok-injective {r} e = cong pick e + where + pick : Outcome → Plan + pick (ok s) = s + pick (conflict _) = r + + conflict-injective : {x y : Path} → conflict x ≡ conflict y → x ≡ y + conflict-injective {x} e = cong pick e + where + pick : Outcome → Path + pick (conflict y) = y + pick (ok _) = x + + ok≢conflict : {r : Plan} {x : Path} → ¬ (ok r ≡ conflict x) + ok≢conflict () + + outcome-ok : (p q : Plan) (d : Conflict p q ⊎ Compatible p q) → + Compatible p q → outcome p q d ≡ ok (p ∪ q) + outcome-ok p q (inj₁ c) h = ⊥-elim (conflict-incompatible c h) + outcome-ok p q (inj₂ _) h = refl + + outcome-ko : (p q : Plan) (d : Conflict p q ⊎ Compatible p q) → + ¬ Compatible p q → Σ Path (λ x → outcome p q d ≡ conflict x) + outcome-ko p q (inj₁ c) n = Conflict.path c , refl + outcome-ko p q (inj₂ h) n = ⊥-elim (n h) + + outcome-ok-inv : (p q : Plan) (d : Conflict p q ⊎ Compatible p q) {r : Plan} → + outcome p q d ≡ ok r → Compatible p q × r ≡ p ∪ q + outcome-ok-inv p q (inj₁ c) e = ⊥-elim (ok≢conflict (sym e)) + outcome-ok-inv p q (inj₂ h) e = h , sym (ok-injective e) + + outcome-conflict : (p q : Plan) (d : Conflict p q ⊎ Compatible p q) {x : Path} → + outcome p q d ≡ conflict x → + Σ State (λ a → Σ State (λ b → + (lookup p x ≡ just a) × (lookup q x ≡ just b) × ¬ (a ≡ b))) + outcome-conflict p q (inj₁ (conflict-at y a b ea eb ne)) {x} e = + subst (λ z → Σ State (λ a → Σ State (λ b → + (lookup p z ≡ just a) × (lookup q z ≡ just b) × ¬ (a ≡ b)))) + (conflict-injective e) (a , b , ea , eb , ne) + outcome-conflict p q (inj₂ h) e = ⊥-elim (ok≢conflict e) + +-- For compatible plans the join is their union. +join-ok : (p q : Plan) → Compatible p q → p ⊔ q ≡ ok (p ∪ q) +join-ok p q = outcome-ok p q (compatible? p q) + +-- For incompatible plans the join is a conflict. +join-ko : (p q : Plan) → ¬ Compatible p q → Σ Path (λ x → p ⊔ q ≡ conflict x) +join-ko p q = outcome-ko p q (compatible? p q) + +-- A plan returned by the join is the union, of compatible plans. +ok-sound : (p q : Plan) {r : Plan} → p ⊔ q ≡ ok r → Compatible p q × r ≡ p ∪ q +ok-sound p q = outcome-ok-inv p q (compatible? p q) + +------------------------------------------------------------------------ +-- Conflicts are exact: never last-writer-wins + +-- A reported path is one that p and q give two different desired states. +conflict-sound : (p q : Plan) {x : Path} → p ⊔ q ≡ conflict x → + Σ State (λ a → Σ State (λ b → + (lookup p x ≡ just a) × (lookup q x ≡ just b) × ¬ (a ≡ b))) +conflict-sound p q = outcome-conflict p q (compatible? p q) + +-- If some path is given two different desired states, the join reports a +-- conflict (at some path, which conflict-sound says is also a conflict). +conflict-complete : (p q : Plan) {x : Path} {a b : State} → + lookup p x ≡ just a → lookup q x ≡ just b → ¬ (a ≡ b) → + Σ Path (λ y → p ⊔ q ≡ conflict y) +conflict-complete p q {x} ea eb ne = join-ko p q (λ h → ne (agree h x ea eb)) + +-- Both directions at once: the join is a conflict iff the plans are not +-- compatible. +conflict-iff : (p q : Plan) → (Σ Path (λ y → p ⊔ q ≡ conflict y)) ⇔ ¬ Compatible p q +conflict-iff p q = mk⇔ to′ (join-ko p q) + where + to′ : Σ Path (λ y → p ⊔ q ≡ conflict y) → ¬ Compatible p q + to′ (y , e) h with conflict-sound p q e + ... | a , b , ea , eb , ne = ne (agree h y ea eb) + +------------------------------------------------------------------------ +-- The extension order: the join is a least upper bound + +-- q extends p: q gives every path of p the same desired state. +record _⊑_ (p q : Plan) : Set where + constructor ⊑-intro + field + extends : (x : Path) {a : State} → lookup p x ≡ just a → lookup q x ≡ just a +open _⊑_ public + +⊑-refl : {p : Plan} → p ⊑ p +⊑-refl = ⊑-intro (λ x e → e) + +⊑-trans : {p q r : Plan} → p ⊑ q → q ⊑ r → p ⊑ r +⊑-trans f g = ⊑-intro (λ x e → extends g x (extends f x e)) + +-- ≈ is mutual extension. +≈⇔⊑⊒ : {p q : Plan} → p ≈ q ⇔ (p ⊑ q × q ⊑ p) +≈⇔⊑⊒ {p} {q} = mk⇔ to′ from′ + where + to′ : p ≈ q → p ⊑ q × q ⊑ p + to′ e = ⊑-intro (λ x ea → trans (sym (≈-at e x)) ea) , ⊑-intro (λ x eb → trans (≈-at e x) eb) + + from′ : p ⊑ q × q ⊑ p → p ≈ q + from′ (f , g) = ≈-intro at + where + at : (x : Path) → lookup p x ≡ lookup q x + at x with maybe-cases (lookup p x) | maybe-cases (lookup q x) + ... | inj₁ (a , ea) | _ = trans ea (sym (extends f x ea)) + ... | inj₂ _ | inj₁ (b , eb) = trans (extends g x eb) (sym eb) + ... | inj₂ en | inj₂ en′ = trans en (sym en′) + +∪-upperˡ : (p q : Plan) → p ⊑ (p ∪ q) +∪-upperˡ p q = ⊑-intro (λ x e → ∪-just p q e) + +∪-upperʳ : (p q : Plan) → Compatible p q → q ⊑ (p ∪ q) +∪-upperʳ p q h = ⊑-intro at + where + at : (x : Path) {b : State} → lookup q x ≡ just b → lookup (p ∪ q) x ≡ just b + at x eb with maybe-cases (lookup p x) + ... | inj₁ (a , ea) = trans (∪-just p q ea) (cong just (agree h x ea eb)) + ... | inj₂ en = trans (∪-nothing p q en) eb + +∪-least : (p q s : Plan) → p ⊑ s → q ⊑ s → (p ∪ q) ⊑ s +∪-least p q s f g = ⊑-intro at + where + at : (x : Path) {a : State} → lookup (p ∪ q) x ≡ just a → lookup s x ≡ just a + at x e with ∪-inv p q e + ... | inj₁ ea = extends f x ea + ... | inj₂ (_ , eb) = extends g x eb + +-- Plans with a common extension are compatible. +bounded-compatible : {p q s : Plan} → p ⊑ s → q ⊑ s → Compatible p q +bounded-compatible f g = + compatible (λ x ea eb → just-injective (trans (sym (extends f x ea)) (extends g x eb))) + +-- The join, when defined, is the least common extension of its inputs: it +-- keeps every desired state of p and every desired state of q, and adds +-- nothing else. +join-lub : (p q : Plan) {r : Plan} → p ⊔ q ≡ ok r → + (p ⊑ r) × (q ⊑ r) × ((s : Plan) → p ⊑ s → q ⊑ s → r ⊑ s) +join-lub p q e with ok-sound p q e +... | h , refl = ∪-upperˡ p q , ∪-upperʳ p q h , ∪-least p q + +-- The join is defined exactly when the inputs have a common extension. +join-defined-iff-bounded : (p q : Plan) → + (Σ Plan (λ r → p ⊔ q ≡ ok r)) ⇔ (Σ Plan (λ s → p ⊑ s × q ⊑ s)) +join-defined-iff-bounded p q = mk⇔ to′ from′ + where + to′ : Σ Plan (λ r → p ⊔ q ≡ ok r) → Σ Plan (λ s → p ⊑ s × q ⊑ s) + to′ (r , e) with join-lub p q e + ... | f , g , _ = r , f , g + + from′ : Σ Plan (λ s → p ⊑ s × q ⊑ s) → Σ Plan (λ r → p ⊔ q ≡ ok r) + from′ (s , f , g) = p ∪ q , join-ok p q (bounded-compatible {p} {q} {s} f g) + +------------------------------------------------------------------------ +-- Facts about compatibility and union + +compatible-refl : (p : Plan) → Compatible p p +compatible-refl p = compatible (λ x ea ea′ → just-injective (trans (sym ea) ea′)) + +compatible-sym : {p q : Plan} → Compatible p q → Compatible q p +compatible-sym h = compatible (λ x eb ea → sym (agree h x ea eb)) + +compatible-cong : {p p′ q q′ : Plan} → p ≈ p′ → q ≈ q′ → + Compatible p q → Compatible p′ q′ +compatible-cong ep eq h = + compatible (λ x ea eb → agree h x (trans (≈-at ep x) ea) (trans (≈-at eq x) eb)) + +∪-comm : (p q : Plan) → Compatible p q → (p ∪ q) ≈ (q ∪ p) +∪-comm p q h = from (≈⇔⊑⊒ {p ∪ q} {q ∪ p}) + ( ∪-least p q (q ∪ p) (∪-upperʳ q p (compatible-sym {p} {q} h)) (∪-upperˡ q p) + , ∪-least q p (p ∪ q) (∪-upperʳ p q h) (∪-upperˡ p q) ) + +∪-idem : (p : Plan) → (p ∪ p) ≈ p +∪-idem p = from (≈⇔⊑⊒ {p ∪ p} {p}) (∪-least p p p (⊑-refl {p}) (⊑-refl {p}) , ∪-upperˡ p p) + +-- A union is compatible with r when both parts are (no side condition). +∪-compatibleˡ : (p q r : Plan) → Compatible p r → Compatible q r → Compatible (p ∪ q) r +∪-compatibleˡ p q r hp hq = compatible at + where + at : (x : Path) → CompatibleAt (p ∪ q) r x + at x e ec with ∪-inv p q e + ... | inj₁ ea = agree hp x ea ec + ... | inj₂ (_ , eb) = agree hq x eb ec + +-- Conversely, for compatible p and q, a union compatible with r has both +-- parts compatible with r. (Without Compatible p q the second part fails: +-- p can hide a disagreement between q and r.) +∪-compatibleˡ⁻ : (p q r : Plan) → Compatible p q → Compatible (p ∪ q) r → + Compatible p r × Compatible q r +∪-compatibleˡ⁻ p q r hpq h = hp , hq + where + hp : Compatible p r + hp = compatible (λ x ea ec → agree h x (∪-just p q ea) ec) + + at : (x : Path) → CompatibleAt q r x + at x eb ec with maybe-cases (lookup p x) + ... | inj₁ (a , ea) = trans (sym (agree hpq x ea eb)) (agree h x (∪-just p q ea) ec) + ... | inj₂ en = agree h x (trans (∪-nothing p q en) eb) ec + + hq : Compatible q r + hq = compatible at + +-- Pairwise compatibility of three plans. +Compatible₃ : Plan → Plan → Plan → Set +Compatible₃ p q r = Compatible p q × Compatible q r × Compatible p r + +-- The definedness condition of the left-nested join is pairwise +-- compatibility... +assoc-definedˡ : (p q r : Plan) → (Compatible p q × Compatible (p ∪ q) r) ⇔ Compatible₃ p q r +assoc-definedˡ p q r = mk⇔ to′ from′ + where + to′ : Compatible p q × Compatible (p ∪ q) r → Compatible₃ p q r + to′ (hpq , h) with ∪-compatibleˡ⁻ p q r hpq h + ... | hpr , hqr = hpq , hqr , hpr + + from′ : Compatible₃ p q r → Compatible p q × Compatible (p ∪ q) r + from′ (hpq , hqr , hpr) = hpq , ∪-compatibleˡ p q r hpr hqr + +-- ...and so is that of the right-nested join. +assoc-definedʳ : (p q r : Plan) → (Compatible q r × Compatible p (q ∪ r)) ⇔ Compatible₃ p q r +assoc-definedʳ p q r = mk⇔ to′ from′ + where + to′ : Compatible q r × Compatible p (q ∪ r) → Compatible₃ p q r + to′ (hqr , h) with ∪-compatibleˡ⁻ q r p hqr (compatible-sym {p} {q ∪ r} h) + ... | hqp , hrp = compatible-sym {q} {p} hqp , hqr , compatible-sym {r} {p} hrp + + from′ : Compatible₃ p q r → Compatible q r × Compatible p (q ∪ r) + from′ (hpq , hqr , hpr) = + hqr , compatible-sym {q ∪ r} {p} + (∪-compatibleˡ q r p (compatible-sym {p} {q} hpq) (compatible-sym {p} {r} hpr)) + +------------------------------------------------------------------------ +-- Equality of outcomes + +-- Two conflicts are equal whatever paths they name; two plans are equal +-- when ≈. Under ~, Outcome is the quotient Plan/≈ with one adjoined element +-- for "conflict". +-- (Defined by recursion and wrapped in a record, rather than as an indexed +-- family, so that no proof needs injectivity of conflict or ok, which +-- --cubical-compatible warns about, and the outcomes stay inferable.) +SameOutcome : Outcome → Outcome → Set +SameOutcome (conflict x) (conflict y) = ⊤ +SameOutcome (conflict x) (ok s) = ⊥ +SameOutcome (ok r) (conflict y) = ⊥ +SameOutcome (ok r) (ok s) = r ≈ s + +record _~_ (o o′ : Outcome) : Set where + constructor ~-by + field + same-outcome : SameOutcome o o′ +open _~_ public + +conflict~ : {x y : Path} → conflict x ~ conflict y +conflict~ = ~-by tt + +ok~ : {r s : Plan} → r ≈ s → ok r ~ ok s +ok~ e = ~-by e + +~-refl : {o : Outcome} → o ~ o +~-refl {conflict x} = conflict~ +~-refl {ok r} = ok~ ≈-refl + +~-sym : {o o′ : Outcome} → o ~ o′ → o′ ~ o +~-sym {conflict x} {conflict y} _ = conflict~ +~-sym {conflict x} {ok s} (~-by ()) +~-sym {ok r} {conflict y} (~-by ()) +~-sym {ok r} {ok s} (~-by e) = ok~ (≈-sym e) + +~-trans : {o o′ o″ : Outcome} → o ~ o′ → o′ ~ o″ → o ~ o″ +~-trans {conflict x} {conflict y} {conflict z} _ _ = conflict~ +~-trans {ok r} {ok s} {ok t} (~-by e) (~-by f) = ok~ (≈-trans e f) +~-trans {conflict x} {ok s} (~-by ()) _ +~-trans {ok r} {conflict y} (~-by ()) _ +~-trans {conflict x} {conflict y} {ok t} _ (~-by ()) +~-trans {ok r} {ok s} {conflict z} _ (~-by ()) + +-- Outcomes are ~ when they are defined together and agree when defined. +~-intro : (o o′ : Outcome) → + (Σ Plan (λ r → o ≡ ok r)) ⇔ (Σ Plan (λ r′ → o′ ≡ ok r′)) → + ((r r′ : Plan) → o ≡ ok r → o′ ≡ ok r′ → r ≈ r′) → o ~ o′ +~-intro (conflict x) (conflict y) d f = conflict~ +~-intro (ok r) (ok r′) d f = ok~ (f r r′ refl refl) +~-intro (ok r) (conflict y) d f with to d (r , refl) +... | _ , () +~-intro (conflict x) (ok r′) d f with from d (r′ , refl) +... | _ , () + +------------------------------------------------------------------------ +-- ADR-0003 law 1: commutative, associative, idempotent wherever defined + +-- Definedness is symmetric. +join-defined-sym : (p q : Plan) → Σ Plan (λ r → p ⊔ q ≡ ok r) → Σ Plan (λ r → q ⊔ p ≡ ok r) +join-defined-sym p q (r , e) with ok-sound p q e +... | h , _ = q ∪ p , join-ok q p (compatible-sym h) + +join-comm : (p q : Plan) → p ⊔ q ~ q ⊔ p +join-comm p q = ~-intro (p ⊔ q) (q ⊔ p) + (mk⇔ (join-defined-sym p q) (join-defined-sym q p)) + (λ r r′ e e′ → same (ok-sound p q e) (ok-sound q p e′)) + where + same : {r r′ : Plan} → Compatible p q × r ≡ p ∪ q → Compatible q p × r′ ≡ q ∪ p → r ≈ r′ + same (h , refl) (_ , refl) = ∪-comm p q h + +-- The join lifted to outcomes: a conflict on either side is kept (the left +-- one first), otherwise the plans are joined. PlanLaws.Semilattice proves +-- that it is a total join-semilattice operation up to ~. +_⊔ᴼ_ : Outcome → Outcome → Outcome +conflict x ⊔ᴼ o = conflict x +ok r ⊔ᴼ conflict y = conflict y +ok r ⊔ᴼ ok s = r ⊔ s + +private + ⊔ᴼ-okˡ-inv : (o : Outcome) (r : Plan) {s : Plan} → o ⊔ᴼ ok r ≡ ok s → + Σ Plan (λ t → (o ≡ ok t) × (t ⊔ r ≡ ok s)) + ⊔ᴼ-okˡ-inv (conflict x) r () + ⊔ᴼ-okˡ-inv (ok t) r e = t , refl , e + + ⊔ᴼ-okʳ-inv : (p : Plan) (o : Outcome) {s : Plan} → ok p ⊔ᴼ o ≡ ok s → + Σ Plan (λ t → (o ≡ ok t) × (p ⊔ t ≡ ok s)) + ⊔ᴼ-okʳ-inv p (conflict y) () + ⊔ᴼ-okʳ-inv p (ok t) e = t , refl , e + + ≡→≈ : {p q : Plan} → p ≡ q → p ≈ q + ≡→≈ refl = ≈-refl + +-- Associativity. Either side is defined exactly when p, q and r are +-- pairwise compatible... +join-assoc-defined : (p q r : Plan) → + ((Σ Plan (λ s → (p ⊔ q) ⊔ᴼ ok r ≡ ok s)) ⇔ Compatible₃ p q r) × + ((Σ Plan (λ s → ok p ⊔ᴼ (q ⊔ r) ≡ ok s)) ⇔ Compatible₃ p q r) +join-assoc-defined p q r = mk⇔ lto lfrom , mk⇔ rto rfrom + where + lto : Σ Plan (λ s → (p ⊔ q) ⊔ᴼ ok r ≡ ok s) → Compatible₃ p q r + lto (s , e) with ⊔ᴼ-okˡ-inv (p ⊔ q) r e + ... | t , e₁ , e₂ with ok-sound p q e₁ | ok-sound t r e₂ + ... | hpq , refl | h , _ = to (assoc-definedˡ p q r) (hpq , h) + + lfrom : Compatible₃ p q r → Σ Plan (λ s → (p ⊔ q) ⊔ᴼ ok r ≡ ok s) + lfrom c with from (assoc-definedˡ p q r) c + ... | hpq , h = (p ∪ q) ∪ r , + trans (cong (_⊔ᴼ ok r) (join-ok p q hpq)) (join-ok (p ∪ q) r h) + + rto : Σ Plan (λ s → ok p ⊔ᴼ (q ⊔ r) ≡ ok s) → Compatible₃ p q r + rto (s , e) with ⊔ᴼ-okʳ-inv p (q ⊔ r) e + ... | t , e₁ , e₂ with ok-sound q r e₁ | ok-sound p t e₂ + ... | hqr , refl | h , _ = to (assoc-definedʳ p q r) (hqr , h) + + rfrom : Compatible₃ p q r → Σ Plan (λ s → ok p ⊔ᴼ (q ⊔ r) ≡ ok s) + rfrom c with from (assoc-definedʳ p q r) c + ... | hqr , h = p ∪ (q ∪ r) , + trans (cong (ok p ⊔ᴼ_) (join-ok q r hqr)) (join-ok p (q ∪ r) h) + +-- ...and then the two sides are equal. +join-assoc : (p q r : Plan) → (p ⊔ q) ⊔ᴼ ok r ~ ok p ⊔ᴼ (q ⊔ r) +join-assoc p q r = ~-intro ((p ⊔ q) ⊔ᴼ ok r) (ok p ⊔ᴼ (q ⊔ r)) + (mk⇔ (λ d → from (proj₂ defined) (to (proj₁ defined) d)) + (λ d → from (proj₁ defined) (to (proj₂ defined) d))) + same + where + defined = join-assoc-defined p q r + + same : (s s′ : Plan) → (p ⊔ q) ⊔ᴼ ok r ≡ ok s → ok p ⊔ᴼ (q ⊔ r) ≡ ok s′ → s ≈ s′ + same s s′ e e′ with ⊔ᴼ-okˡ-inv (p ⊔ q) r e | ⊔ᴼ-okʳ-inv p (q ⊔ r) e′ + ... | t , e₁ , e₂ | t′ , e₁′ , e₂′ + with ok-sound p q e₁ | ok-sound t r e₂ | ok-sound q r e₁′ | ok-sound p t′ e₂′ + ... | _ , refl | _ , refl | _ , refl | _ , refl = ≡→≈ (∪-assoc p q r) + +-- Idempotence: a plan joined with itself is defined and is itself. +join-idem : (p : Plan) → p ⊔ p ~ ok p +join-idem p = ~-intro (p ⊔ p) (ok p) + (mk⇔ (λ _ → p , refl) (λ _ → p ∪ p , join-ok p p (compatible-refl p))) + (λ r r′ e e′ → same (ok-sound p p e) e′) + where + same : {r r′ : Plan} → Compatible p p × r ≡ p ∪ p → ok p ≡ ok r′ → r ≈ r′ + same (_ , refl) e′ = ≈-trans (∪-idem p) (≡→≈ (ok-injective e′)) + +-- The join respects ≈, so the laws above are laws of the quotient Plan/≈. +join-cong : {p p′ q q′ : Plan} → p ≈ p′ → q ≈ q′ → p ⊔ q ~ p′ ⊔ q′ +join-cong {p} {p′} {q} {q′} ep eq = ~-intro (p ⊔ q) (p′ ⊔ q′) + (mk⇔ (λ { (r , e) → p′ ∪ q′ , + join-ok p′ q′ (compatible-cong ep eq (proj₁ (ok-sound p q e))) }) + (λ { (r , e) → p ∪ q , + join-ok p q (compatible-cong (≈-sym ep) (≈-sym eq) (proj₁ (ok-sound p′ q′ e))) })) + (λ r r′ e e′ → same (ok-sound p q e) (ok-sound p′ q′ e′)) + where + same : {r r′ : Plan} → Compatible p q × r ≡ p ∪ q → Compatible p′ q′ × r′ ≡ p′ ∪ q′ → r ≈ r′ + same (_ , refl) (_ , refl) = ∪-cong ep eq diff --git a/verification/proofs/agda/PlanLaws/Kernel.agda b/verification/proofs/agda/PlanLaws/Kernel.agda new file mode 100644 index 0000000..48f6eba --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Kernel.agda @@ -0,0 +1,187 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Kernel: the refinement that brings preconditions (expect) back. +-- +-- The laws in PlanLaws.Join and PlanLaws.Apply are about desired states. A +-- kernel operation also carries a precondition, `expect` in plan format +-- v0.1, on the state the target has before the write. Expect is abstract +-- here: any type with a decidable "holds on this state" relation (in v0.1: +-- "absent", or a content hash). The kernel step of "Apply" in +-- verification/conformance/README.adoc is modelled as kapply: every +-- operation must find its path already in the desired state (a no-op) or +-- find its expect holding; otherwise refuse and write nothing. Proves: +-- kapply-refines an accepted kernel apply is the model's apply of the +-- desired states; +-- kapply-refuses a refusal is exact: some operation is neither done nor +-- expected; +-- unique-functional +-- in a plan with no two operations on one path (v0.1, +-- PATH_DUPLICATE), lookup finds each operation's state; +-- kapply-idem for such a plan, a second kernel apply is accepted, finds +-- every path already in its desired state (receipt: only +-- unchanged or already-absent), and changes nothing. +-- Not modelled: blobs and hashes, modes beyond what Content holds, symbolic +-- links, the directory structure of the target, and partial writes. The +-- refinement from this model to kernel code is a Creusot/Pearlite and Verus +-- obligation on the Rust kernel (PROOF-POLICY §1.2), which does not exist yet. + +open import PlanLaws.Prelude + +module PlanLaws.Kernel + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + where + +open import PlanLaws.Plan Path _≟P_ Content _≟C_ +open import PlanLaws.Apply Path _≟P_ Content _≟C_ + +-- The precondition language is a parameter of this inner module, because +-- it mentions State. +module WithExpect + (Expect : Set) + (Holds : Expect → State → Set) + (holds? : (e : Expect) (s : State) → Dec (Holds e s)) + where + + record KOp : Set where + constructor kop + field + kpath : Path + desired : State + expect : Expect + open KOp public + + KPlan : Set + KPlan = List KOp + + -- The plan of desired states that a kernel plan carries. + desired-plan : KPlan → Plan + desired-plan = map (λ o → kpath o , desired o) + + -- A property of every operation of a kernel plan. + Every : (KOp → Set) → KPlan → Set + Every P [] = ⊤ + Every P (o ∷ kp) = P o × Every P kp + + -- An operation may run on fs: its path is already in the desired state, + -- or its expect holds there. + Ready : FS → KOp → Set + Ready fs o = (fs (kpath o) ≡ desired o) ⊎ Holds (expect o) (fs (kpath o)) + + private + ready? : (fs : FS) (o : KOp) → Dec (Ready fs o) + ready? fs o with fs (kpath o) ≟S desired o + ... | yes e = yes (inj₁ e) + ... | no ne with holds? (expect o) (fs (kpath o)) + ... | yes h = yes (inj₂ h) + ... | no nh = no (λ { (inj₁ e) → ne e ; (inj₂ h) → nh h }) + + every-ready? : (fs : FS) (kp : KPlan) → Dec (Every (Ready fs) kp) + every-ready? fs [] = yes tt + every-ready? fs (o ∷ kp) with ready? fs o + ... | no n = no (λ r → n (proj₁ r)) + ... | yes r with every-ready? fs kp + ... | yes rs = yes (r , rs) + ... | no n = no (λ r′ → n (proj₂ r′)) + + -- The kernel: refuse (nothing) unless every operation is ready, then + -- apply all of them. + decide-apply : (kp : KPlan) (fs : FS) → Dec (Every (Ready fs) kp) → Maybe FS + decide-apply kp fs (yes _) = just (apply (desired-plan kp) fs) + decide-apply kp fs (no _) = nothing + + kapply : KPlan → FS → Maybe FS + kapply kp fs = decide-apply kp fs (every-ready? fs kp) + + private + decide-refines : (kp : KPlan) (fs : FS) (d : Dec (Every (Ready fs) kp)) {fs′ : FS} → + decide-apply kp fs d ≡ just fs′ → + Every (Ready fs) kp × apply (desired-plan kp) fs ≡ fs′ + decide-refines kp fs (yes r) e = r , just-injective e + decide-refines kp fs (no _) e = ⊥-elim (nothing≢just e) + + decide-refuses : (kp : KPlan) (fs : FS) (d : Dec (Every (Ready fs) kp)) → + decide-apply kp fs d ≡ nothing → ¬ Every (Ready fs) kp + decide-refuses kp fs (yes r) e = ⊥-elim (nothing≢just (sym e)) + decide-refuses kp fs (no n) e = n + + decide-accepts : (kp : KPlan) (fs : FS) (d : Dec (Every (Ready fs) kp)) → + Every (Ready fs) kp → decide-apply kp fs d ≡ just (apply (desired-plan kp) fs) + decide-accepts kp fs (yes _) r = refl + decide-accepts kp fs (no n) r = ⊥-elim (n r) + + kapply-refines : (kp : KPlan) (fs : FS) {fs′ : FS} → kapply kp fs ≡ just fs′ → + Every (Ready fs) kp × apply (desired-plan kp) fs ≡ fs′ + kapply-refines kp fs = decide-refines kp fs (every-ready? fs kp) + + kapply-refuses : (kp : KPlan) (fs : FS) → kapply kp fs ≡ nothing → ¬ Every (Ready fs) kp + kapply-refuses kp fs = decide-refuses kp fs (every-ready? fs kp) + + ---------------------------------------------------------------------- + -- Plans with one operation per path + + Unique : List Path → Set + Unique [] = ⊤ + Unique (x ∷ xs) = ¬ (x ∈ xs) × Unique xs + + -- Lookup in the desired plan finds each operation's own desired state. + Functional : KPlan → Set + Functional kp = Every (λ o → lookup (desired-plan kp) (kpath o) ≡ just (desired o)) kp + + private + every-map : {P Q : KOp → Set} (kp : KPlan) → Every (λ o → P o → Q o) kp → Every P kp → Every Q kp + every-map [] _ _ = tt + every-map (o ∷ kp) (f , fs) (p , ps) = f p , every-map kp fs ps + + every-intro : {P : KOp → Set} (kp : KPlan) → ((o : KOp) → P o) → Every P kp + every-intro [] f = tt + every-intro (o ∷ kp) f = f o , every-intro kp f + + -- Each operation's path is among the paths of the plan. + every-mem : (kp : KPlan) → Every (λ o → kpath o ∈ map kpath kp) kp + every-mem [] = tt + every-mem (o ∷ kp) = inj₁ refl , + every-map kp (every-intro kp (λ o′ m → inj₂ m)) (every-mem kp) + + lookup-head : (x : Path) (s : State) (p : Plan) → lookup ((x , s) ∷ p) x ≡ just s + lookup-head x s p with x ≟P x + ... | yes _ = refl + ... | no ne = ⊥-elim (ne refl) + + lookup-tail : (x y : Path) (s : State) (p : Plan) → ¬ (y ≡ x) → + lookup ((x , s) ∷ p) y ≡ lookup p y + lookup-tail x y s p ne with y ≟P x + ... | yes e = ⊥-elim (ne e) + ... | no _ = refl + + unique-functional : (kp : KPlan) → Unique (map kpath kp) → Functional kp + unique-functional [] _ = tt + unique-functional (o ∷ kp) (fresh , uq) = + lookup-head (kpath o) (desired o) (desired-plan kp) , + every-map kp + (every-map kp + (every-intro kp (λ o′ m e → + trans (lookup-tail (kpath o) (kpath o′) (desired o) (desired-plan kp) + (λ eq → fresh (subst (_∈ map kpath kp) eq m))) + e)) + (every-mem kp)) + (unique-functional kp uq) + + ---------------------------------------------------------------------- + -- A second kernel apply changes nothing + + kapply-idem : (kp : KPlan) → Functional kp → (fs : FS) {fs′ : FS} → + kapply kp fs ≡ just fs′ → + Every (λ o → fs′ (kpath o) ≡ desired o) kp × + Σ FS (λ fs″ → (kapply kp fs′ ≡ just fs″) × (fs″ ≗ fs′)) + kapply-idem kp fn fs {fs′} e with kapply-refines kp fs e + ... | _ , refl = + done , + apply (desired-plan kp) fs′ , + decide-accepts kp fs′ (every-ready? fs′ kp) (every-map kp (every-intro kp (λ o d → inj₁ d)) done) , + apply-idem (desired-plan kp) fs + where + done : Every (λ o → apply (desired-plan kp) fs (kpath o) ≡ desired o) kp + done = every-map kp (every-intro kp (λ o l → apply-establishes (desired-plan kp) fs l)) fn diff --git a/verification/proofs/agda/PlanLaws/Plan.agda b/verification/proofs/agda/PlanLaws/Plan.agda new file mode 100644 index 0000000..2f454d1 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Plan.agda @@ -0,0 +1,161 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Plan: the model of a plan (ADR-0003; plan format v0.1). +-- +-- Defines desired states, plans, lookup, the domain of a plan and the +-- equality used for plans, and proves the facts about them that the laws +-- use: the domain is exactly the paths lookup finds (keys-lookup, +-- lookup-keys), lookup distributes over union (lookup-∪), and the plan +-- equality is an equivalence relation. +-- +-- Model. +-- * Path and Content are abstract, each with decidable equality (module +-- parameters). Content stands for everything a write fixes: the blob +-- hash and the mode in plan format v0.1. +-- * A desired State is a file with some content, or absent (a delete). +-- * A Plan is a finite list of (path, state) entries, read through lookup, +-- which returns the first entry for a path. Plan format v0.1 forbids two +-- operations on one path (PATH_DUPLICATE); the laws do not need that, so +-- they hold for every list, and a duplicate-free plan is a special case. +-- * Preconditions (expect) and provenance (source) are left out: the laws +-- are about desired states. PlanLaws.Kernel states the refinement that +-- brings expect back in. +-- +-- Equality of plans. Function extensionality is not available under +-- --safe --without-K, so plans are never compared as functions. Two plans +-- are equal, p ≈ q, when lookup agrees at every path (pointwise, i.e. +-- extensional, equality of lookup). Every law about plans is stated up to ≈ +-- unless it says _≡_. + +open import PlanLaws.Prelude + +module PlanLaws.Plan + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + where + +------------------------------------------------------------------------ +-- Desired states + +data State : Set where + file : Content → State + absent : State + +private + content-or : Content → State → Content + content-or c (file d) = d + content-or c absent = c + +file-injective : {c d : Content} → file c ≡ file d → c ≡ d +file-injective {c = c} e = cong (content-or c) e + +file≢absent : {c : Content} → ¬ (file c ≡ absent) +file≢absent () + +_≟S_ : (s t : State) → Dec (s ≡ t) +file c ≟S file d with c ≟C d +... | yes e = yes (cong file e) +... | no ne = no (λ e → ne (file-injective e)) +file c ≟S absent = no file≢absent +absent ≟S file d = no (λ e → file≢absent (sym e)) +absent ≟S absent = yes refl + +------------------------------------------------------------------------ +-- Plans + +Plan : Set +Plan = List (Path × State) + +lookup : Plan → Path → Maybe State +lookup [] x = nothing +lookup ((y , s) ∷ p) x with x ≟P y +... | yes _ = just s +... | no _ = lookup p x + +-- The paths a plan mentions, in order (with any duplicates). +keys : Plan → List Path +keys = map proj₁ + +-- Union of plans: the entries of p, then those of q. As a map it is +-- left-biased (lookup-∪); the join (PlanLaws.Join) only forms it for +-- compatible plans, where the bias is never visible. +_∪_ : Plan → Plan → Plan +p ∪ q = p ++ q + +infixr 5 _∪_ +infix 4 _≈_ + +------------------------------------------------------------------------ +-- The domain of a plan is exactly where lookup finds a state + +lookup-keys : (p : Plan) {x : Path} {s : State} → lookup p x ≡ just s → x ∈ keys p +lookup-keys [] e = ⊥-elim (nothing≢just e) +lookup-keys ((y , t) ∷ p) {x} e with x ≟P y +... | yes x≡y = inj₁ x≡y +... | no _ = inj₂ (lookup-keys p e) + +keys-lookup : (p : Plan) {x : Path} → x ∈ keys p → Σ State (λ s → lookup p x ≡ just s) +keys-lookup [] () +keys-lookup ((y , t) ∷ p) {x} m with x ≟P y +... | yes _ = t , refl +keys-lookup ((y , t) ∷ p) {x} (inj₁ x≡y) | no ne = ⊥-elim (ne x≡y) +keys-lookup ((y , t) ∷ p) {x} (inj₂ m) | no ne = keys-lookup p m + +keys-∪ : (p q : Plan) → keys (p ∪ q) ≡ keys p ++ keys q +keys-∪ p q = map-++ proj₁ p q + +------------------------------------------------------------------------ +-- Lookup in a union + +lookup-∪ : (p q : Plan) (x : Path) → lookup (p ∪ q) x ≡ (lookup p x <|> lookup q x) +lookup-∪ [] q x = refl +lookup-∪ ((y , s) ∷ p) q x with x ≟P y +... | yes _ = refl +... | no _ = lookup-∪ p q x + +∪-just : (p q : Plan) {x : Path} {a : State} → + lookup p x ≡ just a → lookup (p ∪ q) x ≡ just a +∪-just p q {x} e = trans (lookup-∪ p q x) (cong (_<|> lookup q x) e) + +∪-nothing : (p q : Plan) {x : Path} → + lookup p x ≡ nothing → lookup (p ∪ q) x ≡ lookup q x +∪-nothing p q {x} e = trans (lookup-∪ p q x) (cong (_<|> lookup q x) e) + +-- A path found in a union was found in the left plan, or only in the right. +∪-inv : (p q : Plan) {x : Path} {a : State} → lookup (p ∪ q) x ≡ just a → + (lookup p x ≡ just a) ⊎ (lookup p x ≡ nothing × lookup q x ≡ just a) +∪-inv p q {x} e with maybe-cases (lookup p x) +... | inj₁ (b , eb) = inj₁ (trans eb (cong just (just-injective (trans (sym (∪-just p q eb)) e)))) +... | inj₂ en = inj₂ (en , trans (sym (∪-nothing p q en)) e) + +------------------------------------------------------------------------ +-- Equality of plans: pointwise equality of lookup + +-- A record rather than a bare function type, so that p and q can be +-- inferred from a proof of p ≈ q (lookup is not injective). +record _≈_ (p q : Plan) : Set where + constructor ≈-intro + field + ≈-at : (x : Path) → lookup p x ≡ lookup q x +open _≈_ public + +≈-refl : {p : Plan} → p ≈ p +≈-refl = ≈-intro (λ x → refl) + +≈-sym : {p q : Plan} → p ≈ q → q ≈ p +≈-sym e = ≈-intro (λ x → sym (≈-at e x)) + +≈-trans : {p q r : Plan} → p ≈ q → q ≈ r → p ≈ r +≈-trans e f = ≈-intro (λ x → trans (≈-at e x) (≈-at f x)) + +-- Union respects ≈ on both sides. +∪-cong : {p p′ q q′ : Plan} → p ≈ p′ → q ≈ q′ → (p ∪ q) ≈ (p′ ∪ q′) +∪-cong {p} {p′} {q} {q′} ep eq = ≈-intro λ x → + trans (lookup-∪ p q x) + (trans (cong₂ _<|>_ (≈-at ep x) (≈-at eq x)) (sym (lookup-∪ p′ q′ x))) + +-- Union is associative on the nose (it is list append). +∪-assoc : (p q r : Plan) → (p ∪ q) ∪ r ≡ p ∪ (q ∪ r) +∪-assoc = ++-assoc diff --git a/verification/proofs/agda/PlanLaws/Prelude.agda b/verification/proofs/agda/PlanLaws/Prelude.agda new file mode 100644 index 0000000..520b1f7 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Prelude.agda @@ -0,0 +1,163 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Prelude: the small logic the plan laws are stated in. +-- +-- Proves nothing about plans. It defines propositional equality, the empty +-- and unit types, decidability, Maybe, lists with membership, Σ, products, +-- sums and logical equivalence, with the elementary lemmas the other modules +-- use. It imports no library (not the Agda standard library), so the import +-- cone of every PlanLaws module is this directory plus Agda.Primitive, which +-- Agda loads for every module. + +module PlanLaws.Prelude where + +infix 4 _≡_ _∈_ +infix 0 _⇔_ +infixr 5 _∷_ _++_ +infixr 4 _,_ +infixr 2 _×_ +infixr 1 _⊎_ +infix 3 ¬_ + +------------------------------------------------------------------------ +-- Equality + +data _≡_ {A : Set} (x : A) : A → Set where + refl : x ≡ x + +sym : {A : Set} {x y : A} → x ≡ y → y ≡ x +sym refl = refl + +trans : {A : Set} {x y z : A} → x ≡ y → y ≡ z → x ≡ z +trans refl e = e + +cong : {A B : Set} (f : A → B) {x y : A} → x ≡ y → f x ≡ f y +cong f refl = refl + +cong₂ : {A B C : Set} (f : A → B → C) {x y : A} {u v : B} → + x ≡ y → u ≡ v → f x u ≡ f y v +cong₂ f refl refl = refl + +subst : {A : Set} (P : A → Set) {x y : A} → x ≡ y → P x → P y +subst P refl px = px + +------------------------------------------------------------------------ +-- Empty, unit, negation, decidability + +data ⊥ : Set where + +⊥-elim : {A : Set} → ⊥ → A +⊥-elim () + +¬_ : Set → Set +¬ A = A → ⊥ + +record ⊤ : Set where + constructor tt + +data Dec (A : Set) : Set where + yes : A → Dec A + no : ¬ A → Dec A + +------------------------------------------------------------------------ +-- Σ, products, sums, logical equivalence + +record Σ (A : Set) (B : A → Set) : Set where + constructor _,_ + field + proj₁ : A + proj₂ : B proj₁ +open Σ public + +_×_ : Set → Set → Set +A × B = Σ A (λ _ → B) + +data _⊎_ (A B : Set) : Set where + inj₁ : A → A ⊎ B + inj₂ : B → A ⊎ B + +record _⇔_ (A B : Set) : Set where + constructor mk⇔ + field + to : A → B + from : B → A +open _⇔_ public + +------------------------------------------------------------------------ +-- Maybe + +data Maybe (A : Set) : Set where + nothing : Maybe A + just : A → Maybe A + +-- The value under just, or the default d. just-injective goes through it +-- rather than matching on refl, which --cubical-compatible warns about. +from-just : {A : Set} → A → Maybe A → A +from-just d nothing = d +from-just d (just a) = a + +just-injective : {A : Set} {a b : A} → just a ≡ just b → a ≡ b +just-injective {a = a} e = cong (from-just a) e + +nothing≢just : {A : Set} {a : A} → ¬ (nothing ≡ just a) +nothing≢just () + +-- Every Maybe value is one of the two shapes, with the equation recorded. +maybe-cases : {A : Set} (m : Maybe A) → Σ A (λ a → m ≡ just a) ⊎ (m ≡ nothing) +maybe-cases nothing = inj₂ refl +maybe-cases (just a) = inj₁ (a , refl) + +-- Left-biased choice: the first value present. +_<|>_ : {A : Set} → Maybe A → Maybe A → Maybe A +nothing <|> n = n +just a <|> n = just a + +------------------------------------------------------------------------ +-- Lists and membership + +data List (A : Set) : Set where + [] : List A + _∷_ : A → List A → List A + +_++_ : {A : Set} → List A → List A → List A +[] ++ ys = ys +(x ∷ xs) ++ ys = x ∷ (xs ++ ys) + +map : {A B : Set} → (A → B) → List A → List B +map f [] = [] +map f (x ∷ xs) = f x ∷ map f xs + +++-assoc : {A : Set} (xs ys zs : List A) → (xs ++ ys) ++ zs ≡ xs ++ (ys ++ zs) +++-assoc [] ys zs = refl +++-assoc (x ∷ xs) ys zs = cong (x ∷_) (++-assoc xs ys zs) + +map-++ : {A B : Set} (f : A → B) (xs ys : List A) → + map f (xs ++ ys) ≡ map f xs ++ map f ys +map-++ f [] ys = refl +map-++ f (x ∷ xs) ys = cong (f x ∷_) (map-++ f xs ys) + +-- Membership, by recursion on the list (not an indexed family, so no +-- pattern match below needs injectivity of _∷_, which --cubical-compatible +-- warns about). +_∈_ : {A : Set} → A → List A → Set +x ∈ [] = ⊥ +x ∈ (y ∷ ys) = (x ≡ y) ⊎ (x ∈ ys) + +∈-++ˡ : {A : Set} {x : A} (xs ys : List A) → x ∈ xs → x ∈ (xs ++ ys) +∈-++ˡ [] ys () +∈-++ˡ (y ∷ xs) ys (inj₁ e) = inj₁ e +∈-++ˡ (y ∷ xs) ys (inj₂ m) = inj₂ (∈-++ˡ xs ys m) + +∈-++ʳ : {A : Set} {x : A} (xs ys : List A) → x ∈ ys → x ∈ (xs ++ ys) +∈-++ʳ [] ys m = m +∈-++ʳ (y ∷ xs) ys m = inj₂ (∈-++ʳ xs ys m) + +∈-++⁻ : {A : Set} {x : A} (xs ys : List A) → + x ∈ (xs ++ ys) → (x ∈ xs) ⊎ (x ∈ ys) +∈-++⁻ [] ys m = inj₂ m +∈-++⁻ (y ∷ xs) ys (inj₁ e) = inj₁ (inj₁ e) +∈-++⁻ (y ∷ xs) ys (inj₂ m) with ∈-++⁻ xs ys m +... | inj₁ m′ = inj₁ (inj₂ m′) +... | inj₂ m′ = inj₂ m′ diff --git a/verification/proofs/agda/PlanLaws/Safety.agda b/verification/proofs/agda/PlanLaws/Safety.agda new file mode 100644 index 0000000..3b5a848 --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Safety.agda @@ -0,0 +1,171 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Safety: what "a join of safe plans is safe" (ADR-0003 law 2) +-- does and does not mean. +-- +-- Plan format v0.1 has two kinds of safety condition. +-- * Per path: a path is safe (relative, no `..`, NFC, not under .git, ...). +-- Modelled by an arbitrary predicate Safe on paths. +-- * Per plan: no two paths are equal after case folding, and no path is a +-- proper directory prefix of another. Modelled by an arbitrary relation +-- Clash on paths, assumed symmetric and irreflexive (both real conditions +-- are: each relates two different paths, in either order). +-- +-- Proves: +-- safe-join per-path safety is preserved by union, hence by the +-- join (safe-join-ok), with the converse (safe-∪-iff); +-- plan-safe-∪-iff the union is plan-safe iff both parts are plan-safe +-- and no path of one clashes with a path of the other; +-- plan-safe-join for a defined join of plan-safe plans, the result is +-- plan-safe iff there is no cross clash; +-- plan-safety-not-preserved +-- two plan-safe, compatible plans whose paths clash have +-- a defined join that is not plan-safe. +-- So ADR-0003 law 2 holds as stated for per-path safety only. For the +-- plan-level conditions it is false: a kernel must re-check case-fold and +-- prefix clashes on the composed plan; a composed plan is not safe merely +-- because its parts were. + +open import PlanLaws.Prelude + +module PlanLaws.Safety + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + (Safe : Path → Set) + (Clash : Path → Path → Set) + (clash-sym : {x y : Path} → Clash x y → Clash y x) + (clash-irrefl : {x : Path} → ¬ Clash x x) + where + +open import PlanLaws.Plan Path _≟P_ Content _≟C_ +open import PlanLaws.Join Path _≟P_ Content _≟C_ + +private + -- Membership in the keys of a union. + ∈-∪⁻ : (p q : Plan) {x : Path} → x ∈ keys (p ∪ q) → (x ∈ keys p) ⊎ (x ∈ keys q) + ∈-∪⁻ p q m = ∈-++⁻ (keys p) (keys q) (subst (_ ∈_) (keys-∪ p q) m) + + ∈-∪ˡ : (p q : Plan) {x : Path} → x ∈ keys p → x ∈ keys (p ∪ q) + ∈-∪ˡ p q m = subst (_ ∈_) (sym (keys-∪ p q)) (∈-++ˡ (keys p) (keys q) m) + + ∈-∪ʳ : (p q : Plan) {x : Path} → x ∈ keys q → x ∈ keys (p ∪ q) + ∈-∪ʳ p q m = subst (_ ∈_) (sym (keys-∪ p q)) (∈-++ʳ (keys p) (keys q) m) + +------------------------------------------------------------------------ +-- Per-path safety + +record AllSafe (p : Plan) : Set where + constructor all-safe + field + safe-at : (x : Path) → x ∈ keys p → Safe x +open AllSafe public + +safe-join : (p q : Plan) → AllSafe p → AllSafe q → AllSafe (p ∪ q) +safe-join p q sp sq = all-safe at + where + at : (x : Path) → x ∈ keys (p ∪ q) → Safe x + at x m with ∈-∪⁻ p q m + ... | inj₁ mp = safe-at sp x mp + ... | inj₂ mq = safe-at sq x mq + +safe-∪-iff : (p q : Plan) → AllSafe (p ∪ q) ⇔ (AllSafe p × AllSafe q) +safe-∪-iff p q = mk⇔ + (λ s → all-safe (λ x m → safe-at s x (∈-∪ˡ p q m)) , all-safe (λ x m → safe-at s x (∈-∪ʳ p q m))) + (λ { (sp , sq) → safe-join p q sp sq }) + +-- ADR-0003 law 2, for per-path safety: a defined join of safe plans is safe. +safe-join-ok : (p q : Plan) {r : Plan} → p ⊔ q ≡ ok r → AllSafe p → AllSafe q → AllSafe r +safe-join-ok p q e sp sq with ok-sound p q e +... | _ , refl = safe-join p q sp sq + +------------------------------------------------------------------------ +-- Plan-level safety + +-- No two paths of p clash. +record NoClash (p : Plan) : Set where + constructor no-clash + field + apart : (x y : Path) → x ∈ keys p → y ∈ keys p → ¬ Clash x y +open NoClash public + +-- No path of p clashes with a path of q. +record Cross (p q : Plan) : Set where + constructor cross + field + apart-across : (x y : Path) → x ∈ keys p → y ∈ keys q → ¬ Clash x y +open Cross public + +PlanSafe : Plan → Set +PlanSafe p = AllSafe p × NoClash p + +plan-safe-∪-iff : (p q : Plan) → PlanSafe (p ∪ q) ⇔ (PlanSafe p × PlanSafe q × Cross p q) +plan-safe-∪-iff p q = mk⇔ to′ from′ + where + to′ : PlanSafe (p ∪ q) → PlanSafe p × PlanSafe q × Cross p q + to′ (s , n) = + ( (proj₁ (to (safe-∪-iff p q) s) + , no-clash (λ x y mx my → apart n x y (∈-∪ˡ p q mx) (∈-∪ˡ p q my))) + , (proj₂ (to (safe-∪-iff p q) s) + , no-clash (λ x y mx my → apart n x y (∈-∪ʳ p q mx) (∈-∪ʳ p q my))) + , cross (λ x y mx my → apart n x y (∈-∪ˡ p q mx) (∈-∪ʳ p q my)) ) + + from′ : PlanSafe p × PlanSafe q × Cross p q → PlanSafe (p ∪ q) + from′ ((sp , np) , (sq , nq) , c) = safe-join p q sp sq , no-clash at + where + at : (x y : Path) → x ∈ keys (p ∪ q) → y ∈ keys (p ∪ q) → ¬ Clash x y + at x y mx my with ∈-∪⁻ p q mx | ∈-∪⁻ p q my + ... | inj₁ mxp | inj₁ myp = apart np x y mxp myp + ... | inj₂ mxq | inj₂ myq = apart nq x y mxq myq + ... | inj₁ mxp | inj₂ myq = apart-across c x y mxp myq + ... | inj₂ mxq | inj₁ myp = λ k → apart-across c y x myp mxq (clash-sym k) + +-- For a defined join of plan-safe plans: the result is plan-safe exactly +-- when no path of one clashes with a path of the other. +plan-safe-join : (p q : Plan) {r : Plan} → p ⊔ q ≡ ok r → + PlanSafe p → PlanSafe q → PlanSafe r ⇔ Cross p q +plan-safe-join p q e sp sq with ok-sound p q e +... | _ , refl = mk⇔ (λ s → proj₂ (proj₂ (to (plan-safe-∪-iff p q) s))) + (λ c → from (plan-safe-∪-iff p q) (sp , sq , c)) + +------------------------------------------------------------------------ +-- The counterexample: law 2 is false for plan-level safety + +private + singleton-keys : (x : Path) (s : State) {z : Path} → z ∈ keys ((x , s) ∷ []) → z ≡ x + singleton-keys x s (inj₁ e) = e + singleton-keys x s (inj₂ ()) + + singleton-safe : (x : Path) (s : State) → Safe x → PlanSafe ((x , s) ∷ []) + singleton-safe x s sx = + all-safe (λ z m → subst Safe (sym (singleton-keys x s m)) sx) , + no-clash (λ z w mz mw k → + clash-irrefl (subst (λ v → Clash v x) (singleton-keys x s mz) + (subst (Clash z) (singleton-keys x s mw) k))) + +-- Two individually plan-safe plans whose paths clash (for example +-- README.adoc and readme.adoc, or a and a/b) are compatible, so their join +-- is defined; the joined plan is not plan-safe. +plan-safety-not-preserved : + (x y : Path) → Safe x → Safe y → Clash x y → (s t : State) → + PlanSafe ((x , s) ∷ []) × PlanSafe ((y , t) ∷ []) × + Σ Plan (λ r → ((x , s) ∷ []) ⊔ ((y , t) ∷ []) ≡ ok r × ¬ PlanSafe r) +plan-safety-not-preserved x y sx sy k s t = + singleton-safe x s sx , singleton-safe y t sy , + (p ∪ q , join-ok p q compat , not-safe) + where + p q : Plan + p = (x , s) ∷ [] + q = (y , t) ∷ [] + + x≢y : ¬ (x ≡ y) + x≢y e = clash-irrefl (subst (Clash x) (sym e) k) + + compat : Compatible p q + compat = compatible (λ z ea eb → + ⊥-elim (x≢y (trans (sym (singleton-keys x s (lookup-keys p ea))) + (singleton-keys y t (lookup-keys q eb))))) + + not-safe : ¬ PlanSafe (p ∪ q) + not-safe (_ , n) = apart n x y (inj₁ refl) (inj₂ (inj₁ refl)) k diff --git a/verification/proofs/agda/PlanLaws/Semilattice.agda b/verification/proofs/agda/PlanLaws/Semilattice.agda new file mode 100644 index 0000000..b4dc8dc --- /dev/null +++ b/verification/proofs/agda/PlanLaws/Semilattice.agda @@ -0,0 +1,73 @@ +{-# OPTIONS --safe --without-K --cubical-compatible #-} +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- +-- PlanLaws.Semilattice: the total form of law 1, in which "pack order +-- cannot matter" needs no definedness side condition. +-- +-- Outcome, under ~, is the quotient Plan/≈ with one adjoined element for +-- "conflict" (all conflicts are identified). The lifted join _⊔ᴼ_ +-- (PlanLaws.Join) is total on it. Proves that it is a join-semilattice +-- operation with a unit and an absorbing top: +-- ⊔ᴼ-cong it respects ~ in both arguments (so it is an operation on the +-- quotient); +-- ⊔ᴼ-comm o ⊔ᴼ o′ ~ o′ ⊔ᴼ o; +-- ⊔ᴼ-assoc (o ⊔ᴼ o′) ⊔ᴼ o″ ~ o ⊔ᴼ (o′ ⊔ᴼ o″); +-- ⊔ᴼ-idem o ⊔ᴼ o ~ o; +-- ⊔ᴼ-unit the empty plan is a unit: ok [] ⊔ᴼ o ~ o; +-- ⊔ᴼ-top a conflict absorbs: conflict x ⊔ᴼ o ~ conflict x, and +-- o ⊔ᴼ conflict x ~ conflict x. +-- Consequently any bracketing and any order of joining a finite collection +-- of packs gives ~-equal outcomes: the same plan up to ≈, or a conflict. + +open import PlanLaws.Prelude + +module PlanLaws.Semilattice + (Path : Set) (_≟P_ : (x y : Path) → Dec (x ≡ y)) + (Content : Set) (_≟C_ : (c d : Content) → Dec (c ≡ d)) + where + +open import PlanLaws.Plan Path _≟P_ Content _≟C_ +open import PlanLaws.Join Path _≟P_ Content _≟C_ + +⊔ᴼ-topˡ : (x : Path) (o : Outcome) → conflict x ⊔ᴼ o ~ conflict x +⊔ᴼ-topˡ x o = conflict~ + +⊔ᴼ-topʳ : (o : Outcome) (x : Path) → o ⊔ᴼ conflict x ~ conflict x +⊔ᴼ-topʳ (conflict y) x = conflict~ +⊔ᴼ-topʳ (ok r) x = conflict~ + +⊔ᴼ-cong : {o₁ o₁′ o₂ o₂′ : Outcome} → o₁ ~ o₁′ → o₂ ~ o₂′ → o₁ ⊔ᴼ o₂ ~ o₁′ ⊔ᴼ o₂′ +⊔ᴼ-cong {conflict x} {conflict x′} _ _ = conflict~ +⊔ᴼ-cong {conflict x} {ok r′} (~-by ()) _ +⊔ᴼ-cong {ok r} {conflict x′} (~-by ()) _ +⊔ᴼ-cong {ok r} {ok r′} {conflict y} {conflict y′} _ _ = conflict~ +⊔ᴼ-cong {ok r} {ok r′} {conflict y} {ok s′} _ (~-by ()) +⊔ᴼ-cong {ok r} {ok r′} {ok s} {conflict y′} _ (~-by ()) +⊔ᴼ-cong {ok r} {ok r′} {ok s} {ok s′} (~-by e) (~-by f) = join-cong e f + +⊔ᴼ-comm : (o o′ : Outcome) → o ⊔ᴼ o′ ~ o′ ⊔ᴼ o +⊔ᴼ-comm (conflict x) (conflict y) = conflict~ +⊔ᴼ-comm (conflict x) (ok s) = conflict~ +⊔ᴼ-comm (ok r) (conflict y) = conflict~ +⊔ᴼ-comm (ok r) (ok s) = join-comm r s + +⊔ᴼ-assoc : (o o′ o″ : Outcome) → (o ⊔ᴼ o′) ⊔ᴼ o″ ~ o ⊔ᴼ (o′ ⊔ᴼ o″) +⊔ᴼ-assoc (conflict x) o′ o″ = conflict~ +⊔ᴼ-assoc (ok r) (conflict y) o″ = conflict~ +⊔ᴼ-assoc (ok r) (ok s) (conflict z) = ⊔ᴼ-topʳ (r ⊔ s) z +⊔ᴼ-assoc (ok r) (ok s) (ok t) = join-assoc r s t + +⊔ᴼ-idem : (o : Outcome) → o ⊔ᴼ o ~ o +⊔ᴼ-idem (conflict x) = conflict~ +⊔ᴼ-idem (ok r) = join-idem r + +-- The empty plan mentions no path, so it is compatible with every plan and +-- its union with q is q itself. +⊔ᴼ-unit : (o : Outcome) → ok [] ⊔ᴼ o ~ o +⊔ᴼ-unit (conflict y) = conflict~ +⊔ᴼ-unit (ok q) = + subst (λ o → o ~ ok q) (sym (join-ok [] q empty-compatible)) ~-refl + where + empty-compatible : Compatible [] q + empty-compatible = compatible (λ x ea eb → ⊥-elim (nothing≢just ea))