Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

76 changes: 76 additions & 0 deletions docs/FORENSIC-REGRESSION-HANDOVER.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
= Plasma forensic regression test handover
// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:toc:

== Purpose and authority

* Baseline inspected: `hyperpolymath/plasma-parser-writer`, commit `d9998ab0d9b612c82ef782b75e0ea62703da1344` (2026-11-11).
* Canonical governance is maintained by `metadatastician/standards`: DEED v2.0 ABNF (`1-formats/deed/spec/abnf/deed.abnf`), K9 component Nickel contract (`1-formats/k9/spec/contract/k9_contract.ncl`), K9 coordination v1.2 ABNF (`2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.2.abnf`). No competing parser is introduced here.
* No production-source changes; no remote branch or PR created; no `.deed` or `.k9` files rewritten.

== File added

`tests/forensic_regression_contracts.rs` -- six default tests (three current correctness regressions expected red, three baseline positive controls expected green) and four explicitly ignored forensic-mode requirements.

== Running on an isolated branch or worktree

[source,shell]
----
git switch -c test/plasma-forensic-contracts
# apply plasma-regressions.patch using git apply --check && git apply
cargo test --test forensic_regression_contracts -- --nocapture
cargo test --test forensic_regression_contracts -- --ignored --nocapture
cargo test --workspace
----

The first test command should expose current strictness failures (red): unexpected punctuation, integer overflow, and unvalidated reserved-action positive assurance. The `--ignored` command exercises the four design-changing forensic assertions; failures on v0 are expected and do NOT establish that the existing narrower policy-mode collector violates its documented contract.

== Source findings underlying the negative controls

* Lexer: `plasma-parser/src/spdx/lexer.rs`, lines 118-122 silently skip unknown characters; line 149 maps parse failure to 0.
* Policy evaluator: `plasma-engine/src/eval.rs`, lines 344-349 maps `ConsistentWith` to a non-violation; `evaluate` accepts a raw Policy and schema validation is performed only through the loader.
* Facts: `plasma-engine/src/facts.rs`, lines 72-79 skip dot-prefixed directories, and lines 91-98 discard some walking errors; collection has no content hashes.
* Diff: `plasma-engine/src/diff.rs` compares file names, headers, metadata, and GitFacts but not content.
* Conditions: `plasma-engine/src/eval.rs` lines 170-181 treat absent content as false; negating that boolean can create a true condition.
* GitFacts: `plasma-engine/src/facts.rs` lines 169-185 preserve the symbolic HEAD ref but do not resolve its content hash.

== Decisions still pending (do not invent semantics)

* `Overlay.applies_to`: accepted by the schema, but unused by `effective_rules`. Its concrete selection semantics require an architecture decision before encoding a regression assertion.
* Filesystem error handling: a portable deterministic unreadable-directory fixture needs a testable traversal abstraction, because root users can bypass ordinary permission checks.
* Evidence-completeness / Unknown semantics: introduce a versioned forensic API rather than silently changing existing policy-mode truth tables.
* Creusot+Pearlite: these tests are not proofs. After correcting contracts and production behaviour, prove deontic evaluation, admission and aggregation; validate the CI prover with a deliberately false control.

== Sign-off rule

Nothing is signed off as executed unless a real Cargo transcript, exit status and tool versions are recorded. The execution results for 2026-11-16 are recorded below. Keep each expected red case until a reviewed fix changes it to green, then run the complete workspace suite.

== Execution receipts — 2026-11-16 (isolated WSL checkout)

* Host: The-Titanic (WSL2 Linux); rustc 1.99.1, cargo 1.99.1, rustfmt 1.10.0.
* Baseline: `d9998ab0d9b612c82ef782b75e0ea62703da1344`; local branch `test/plasma-forensic-contracts-20261116`.
* Run 1: `cargo test --test forensic_regression_contracts -- --nocapture` → exit 101: three passing positive controls, three failing strictness regressions, four ignored.
* Run 2: `cargo test --test forensic_regression_contracts -- --ignored --nocapture` → exit 101: four intentionally ignored forensic-mode targets each reproduced the current limitation.
* Run 3: `cargo test --workspace -- --skip rejects_unrecognised_spdx_punctuation_instead_of_dropping_it --skip rejects_overflowing_spdx_number_instead_of_substituting_zero --skip reserved_action_does_not_silently_produce_a_pass` → exit 0; all other executed tests passed, with four forensic-mode targets ignored.
* Logs stored on the same WSL host at `/tmp/plasma-regression-test-run-20261116.log`, `/tmp/plasma-regression-ignored-20261116.log`, and `/tmp/plasma-regression-workspace-20261116.log`.
* The test-only source was formatted with `rustfmt --edition 2021`; neither production code nor `main` was edited. This is expected-red evidence, not a successful compliance gate.

== Repair receipts — 2026-11-16 (persistent local branch)

* The baseline was preserved from the temporary checkout into `/home/hyperpolymath/repos/plasma-parser-writer`, branch `test/plasma-forensic-contracts-20261116`. GitHub main was not modified.
* `dccbc41` — regression tests and original observed-failure handover.
* `531077b` — correct overflow negative control to use `Apache-4294967296.9`, avoiding an innocent minor-version zero.
* `02e55d8` — reject unrecognised SPDX characters and numeric token overflow without silently changing the parsed expression.
* `76f1c36` — fail closed at direct `evaluate` admission for unvalidated raw policies, including reserved actions and unsupported release subjects. Two additional negative tests cover a false condition and an unsupported subject.
* Post-fix `cargo test --test forensic_regression_contracts -- --nocapture`: **8 passed, 0 failed, 4 ignored**.
* Post-fix `cargo test --workspace`: **exit 0**, all enabled workspace unit, integration and doc tests pass.
* `cargo fmt --all -- --check`: **exit 0**.
* `cargo clippy --workspace --all-targets -- -D warnings`: **exit 0**.
* The four ignored forensic-mode targets remain open and were previously executed with `--ignored`, reproducing the initial limitations. They require an explicitly versioned forensic contract and must not be marked green.
* Creusot/Pearlite proofs were **not run or added**; this phase supplies executable regression evidence, not formal verification.
* All local commits use SSH signatures from the loaded agent key. The local verifier reports a mathematically good signature but `No principal matched` in the user's current allowed-signers file; external GitHub signature-verification status is not established until publication. The configured signing requirement was not disabled.
* No `.deed` or `.k9` file was rewritten. Follow-up migration must use the canonical DEED grammar and K9/coordination validators in `metadatastician/standards`.
* No push, pull request, merge, licensing change or changes to remote branch rulesets were performed.

Next steps: decide and implement the independent forensic evidence schema for content hashes, Git commit resolution, coverage and Unknown status. Clarify `Overlay.applies_to` semantics before formally proving overlay applicability; then add Creusot+Pearlite proof obligations with independent negative-proof controls.
112 changes: 112 additions & 0 deletions docs/forensic-evidence-v0.1.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
= Plasma forensic evidence contract v0.1 (experimental)
:toc:

== Purpose

This opt-in evidence model is separate from v0 policy `FactSet`,
`plasma facts`, `plasma diff`, and the existing boolean policy evaluator.
Those contracts retain their current semantics and wire formats.

The model answers a narrower question: "what repository bytes and Git HEAD
identity were actually observed, and was the bounded observation complete?"
It does not claim that observing a tree means every governance rule passes.

== Seams and authorities

[cols="1,3,3",options="header"]
|===
| Seam | Authority | Evidence and guarantee
| S-01 Scope | Forensic scanner options | Dot-prefixed governance paths are included. `.git`, `target`, `node_modules`, `vendor`, `_build`, and `deps` are excluded *explicitly* as directory entries. Exclusions are reported, not silently erased.
| S-02 Content | SHA-256 over bytes of every in-scope regular file | Streaming hash and byte count. A same-path edit with unchanged SPDX header must change the observed digest, subject to SHA-256 collision assumptions and stable input during read.
| S-03 Git | `.git/HEAD` plus loose or packed ref resolution | Symbolic ref and resolved commit object ID recorded separately. Git object IDs are *identity*, not a substitute for SHA-256 content integrity. Unresolvable Git state remains unknown.
| S-04 Completeness | Typed observation status and issues | An unreadable path, traversal failure, invalid UTF-8 path, unsupported file type or detected concurrent write blocks a claim of complete in-scope observation. Intentional exclusions do not vanish; complete means only "for the declared scope."
| S-05 Epistemic status | Explicit three-valued evidence truth | True, False and Unknown; negating Unknown remains Unknown. This is NOT inserted into the legacy policy evaluator without an explicit version migration.
|===

== Boundary discipline

* `collect_forensic(root)` is read-only: no file writes, git commands,
process execution, network, signature checks or remediation.
* No timestamps or ambient randomness are serialized. BTree ordering is
canonical. `root` is informational and may differ between checkouts.
* Symlinks are recorded by their link target and never followed outside
the root. Unknown or non-UTF-8 targets are explicit issues.
* A path not safely representable as UTF-8 is not silently accepted under a
lossy identifier: observation is marked incomplete.
* SHA-256 records observations, not a transactional filesystem snapshot.
Concurrent writes cannot be completely ruled out without filesystem or
Git-object snapshot isolation. A detected metadata change during read
invalidates that file's observation.
* The format identifies a schema version. Consumers must reject unsupported
versions and must not interpret missing/unknown evidence as a clean pass.
* The existing `FactSet` and `FactsDiff` retain their legacy semantics:
this version does NOT change their JSON, CLI, or policy-mode behaviour.
* DEED and K9 syntax must be validated against the existing standards
conformance tools; this module must not implement competing grammars.

== Invariants and tests

. Full in-scope file-body mutations are visible even when paths, lengths, SPDX
headers and symbolic Git ref remain the same.
. `.github`, `.machine_readable` and other dot-prefixed governance paths
remain observable; `.git` internals remain explicitly out of scope.
. Missing or unreadable evidence cannot yield a complete in-scope verdict.
. Changes to a resolved Git HEAD object ID are visible even if the branch
name does not change; detached HEAD and packed refs have defined behaviour.
. Repeated scans over stable inputs produce byte-identical JSON; diffs are
ordered and root-location-independent.
. Symlinks are not dereferenced; changes to a link target path are visible.
. The three-valued algebra preserves Unknown under negation and propagates it
according to strong Kleene conjunction/disjunction.

== Non-goals and outstanding decisions

* No rewriting of the legacy `plasma diff` command.
* No global proof of all repository files if generated directories are
intentionally excluded; coverage must always be interpreted with scope.
* No guarantee against concurrently mutated files beyond observed metadata
stability; stronger consistency requires Git tree or filesystem snapshot
capture with a separate contract.
* No `Overlay.applies_to` semantics here; establish an ADR separately before
formalising an overlay theorem.
* No formal Creusot/Pearlite assurance yet; these are testable contracts
and proof candidates, not completed deductive proofs.

== Integration and release gate

This module is library-only in v0.1, with ordinary Rust unit tests. Before
exposing it to bots as a normative auditor, require:
* A versioned JSON schema / compatibility and negative fixture suite.
* A CLI with explicit `--forensic` mode and nonzero/Unknown exit semantics.
* A bounded scan of representative real repositories, including worktrees,
large files, governance files, symlinks and concurrency experiments.
* Independent review of error, exclusion, Git and SHA-256 handling.
* Creusot+Pearlite obligations on pure evidence comparisons and admission.
* No automatic repair and no change to production policy mode.

== Local implementation receipt — 2026-11-16

* Baseline: `879c813d3e3673a8183a0dfad4c767c651655863` on branch
`test/plasma-forensic-contracts-20261116`.
* Implementation: `plasma-engine/src/forensic.rs`; integration fixtures:
`plasma-engine/tests/forensic_evidence.rs`.
* New dependency: RustCrypto `sha2` 0.10.9, locked in `Cargo.lock`;
SHA-256 is used for byte observations. Git OIDs remain identity only.
* New APIs are library-only, separately versioned `0.1.0`. Legacy
`FactSet`, `FactsDiff`, `evaluate` and CLI semantics were not changed.
* `cargo test -p plasma-engine --test forensic_evidence --offline`:
14 passed, 0 failed; hidden governance paths, binary bytes, same-length
source mutations, normal/detached/packed Git HEAD, external Gitdir refusal,
symlink refusal, unknown paths/types and three-valued evidence.
* `cargo test --workspace --offline`: exit 0. Existing forensic-mode
legacy assertions remain 4 ignored, pending a versioned CLI integration.
* `cargo fmt --all -- --check`: exit 0.
* `cargo clippy --workspace --all-targets --offline -- -D warnings`:
exit 0.
* Explicit limitations: Git worktree external pointer files result in
`Unknown` rather than dereferencing external paths; filesystem reads
are not atomic; excluded paths appear in `excluded_paths`; an
in-scope complete scan does not imply that the Git identity was resolved.
* No remote push, PR, production deployment, trust-policy bypass, DEED/K9
migration, or formal deductive-proof execution was performed.
4 changes: 4 additions & 0 deletions plasma-engine/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,11 @@ toml = "0.8"
walkdir = "2"
glob = "0.3"
regex = "1"
sha2 = "0.10"
thiserror = "2"

[target.'cfg(unix)'.dependencies]
rustix = { version = "1", features = ["fs"] }

[dev-dependencies]
tempfile = "3"
Loading
Loading