@marinjursic/prc-linux-arm64 0.1.0

package/bin/docs/scanner/remediation.md

@@ -0,0 +1,273 @@
+# Bounded isolated remediation
+
+The experimental `remediate` command supports two deterministic fixers:
+
+- `PRC-A-CORE-014` appends one line-feed byte to each recognized source file
+  that lacks one; and
+- `PRC-A-CORE-022` clears group-write and other-write permission bits while
+  preserving every file byte and all other permission bits.
+
+Neither fixer executes target code, calls a model, uses the network, edits the
+original workspace, or performs version-control operations.
+
+The README-presence assertion is deliberately R2. Writing useful project
+documentation requires project-specific judgment, so the scanner does not create
+a placeholder README and claim the finding is fixed.
+
+## Create an isolated candidate
+
+Choose a new destination outside the target tree. Its parent must already exist,
+and the destination itself must not exist.
+
+```bash
+./prc remediate \
+  --catalog-root /path/to/production-readiness-checklist \
+  --target /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  --assertion PRC-A-CORE-014 \
+  --candidate-dir /safe/path/prc-candidate \
+  --max-files 20 \
+  --max-changed-lines 20
+```
+
+The command exits `0` only when the candidate passes every acceptance check. A
+validated but rejected candidate is still printed and exits `8`. Invalid input
+exits `3`; a policy-denied remediation exits `5`. Use
+`--format json` for the versioned `prc.remediation-candidate/v0.4` record.
+
+With `--config`, the exact canonical configuration digest and project identity
+are recorded in the fix contract. The configured profile is mandatory,
+`remediation.enabled` must be true, and command-line file or line limits cannot
+raise the configured ceilings. The configured attempt ceiling is recorded even
+though this command performs exactly one attempt. Scanner defaults, configured
+protected paths, and the configuration file itself are unioned into the guard
+set. Baseline, candidate, and final source-integrity scans all rebind the same
+configuration.
+
+## What acceptance verifies
+
+The scanner creates a content-addressed fix contract with the baseline run,
+inventory, exact canonical finding ID and stable finding fingerprint, allowed
+paths, protected paths, network denial, one-attempt limit, and file and line
+budgets. After applying the fix in the copy, it:
+
+1. inventories the candidate from fresh bytes;
+2. walks the raw candidate tree so excluded directories cannot hide additions;
+3. rejects additions, deletions, symlinks, non-regular entries,
+   protected-path changes, and any change outside the allowlist;
+4. verifies the fixer's exact byte-and-mode postcondition: one appended
+   line-feed with the mode unchanged, or bytes unchanged with only group-write
+   and other-write bits cleared;
+5. rescans the candidate and requires the target assertion to pass; and
+6. requires every assertion that passed in the baseline to remain passing; and
+7. re-inventories the original target and requires it to remain byte-for-byte
+   and mode-for-mode identical to the baseline.
+
+The candidate directory is preserved for review. Acceptance is permission to
+inspect or continue testing that isolated candidate; it is not authorization to
+merge, deploy, release, accept risk, or claim that the full profile is satisfied.
+
+## Run the bounded remediation loop
+
+Without a provider, `prc fix` repeatedly applies only the registered R1 fixers.
+Each accepted candidate becomes the source of a new sibling candidate, so fixes
+compose without changing the original project. The candidate root must be a new
+path outside the target tree. The scanner validates that destination first but
+does not create it until an eligible attempt has passed task, source, policy,
+and budget preflight.
+
+```bash
+export OPENAI_API_KEY='your-provider-key'
+./prc fix \
+  --catalog-root /path/to/production-readiness-checklist \
+  --target /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  --candidate-root /safe/path/prc-remediation-run \
+  --max-attempts 3 \
+  --max-files 20 \
+  --max-changed-lines 200 \
+  --max-duration-seconds 1800 \
+  --format json > remediation-run.json
+```
+
+The loop evaluates findings in profile order and stops predictably when it has
+closed all eligible findings, a cumulative budget is exhausted, a provider
+cannot return a candidate, or an independently checked candidate is rejected.
+File and changed-line usage accumulates across accepted candidates. One
+wall-clock budget spans planning, provider execution, candidate generation, and
+verification. It is propagated as a hard deadline to provider and verifier
+child processes and checked at scanner phase boundaries; a synchronous
+candidate operation that returns after the deadline is preserved but rejected,
+never accepted. Command-line values cannot raise limits declared in project
+configuration. Go contexts propagate deadline cancellation, and commands
+started with `CommandContext` are interrupted when that context completes
+([context package](https://pkg.go.dev/context),
+[os/exec package](https://pkg.go.dev/os/exec)).
+
+The `prc.remediation-run/v0.9` report records every actual attempt, including
+proposals rejected before candidate creation. Each attempt binds its sequence,
+mode, exact finding and fingerprint, scanner-owned task, before and after
+inventory digests, provider execution or failure and candidate when present, timestamps,
+outcome, machine-readable reason code, and exact scanner rejection reason. The
+scanner verifies this linkage before computing the run content ID. The report
+also preserves every candidate, provider transcript digest, cumulative budget
+usage, final fresh assessment, final isolated workspace, and a reason code for
+every unresolved result. Its embedded v0.9 scan result preserves adapter
+resolution provenance; frozen v0.3 through v0.7 remediation schemas retain their
+version-pinned dependency graphs. Every unresolved failure includes its
+canonical finding ID and stable fingerprint. Its terminal states are:
+
+- `profile_satisfied`: every required result in the selected profile passed;
+- `machine_work_complete`: no registered deterministic R1 failure remains, but
+  manual evidence, blocked checks, or higher-risk work can still remain;
+- `stopped_by_policy_or_budget`: an eligible fix could not run within policy;
+- `candidate_rejected`: independent acceptance rejected an attempted fix;
+- `provider_stopped`: the provider returned `unable` or `needs_escalation`
+  without a patch; or
+- `provider_failed`: scanner preflight, transcript persistence, process,
+  timeout, output-bound, postflight-integrity, or output-protocol validation
+  failed and the loop did not retry.
+
+Exit status `0` is reserved for `profile_satisfied`. A no-go gate exits `1`,
+incomplete or blocked assessment work and `provider_stopped` exit `2`, a policy
+or budget stop exits `5`, provider failure exits `4`, and candidate rejection
+exits `8`. Caller cancellation retains exit `7` while preserving its failure
+record.
+`machine_work_complete` is not a production-readiness claim. The default loop
+does not invoke an agent. No loop mode runs project commands, deploys, merges,
+or performs version-control operations.
+
+## Opt in to one scanner-planned R2 task
+
+`prc fix --provider` connects the bounded loop to the read-only Codex or Claude
+Code provider adapter. This is not general repository autonomy. The current
+task planner supports only a failing `PRC-A-CORE-010` test-discovery assertion:
+it selects one bounded source file, derives a small allowlist of new test paths,
+binds the exact triggering finding into the sealed task, and asks for exactly
+one non-vacuous test file. Every other R2 finding remains
+`no_safe_agent_task` until it has a dedicated planner and sufficiently strong
+verification.
+
+```bash
+./prc fix \
+  --catalog-root /path/to/production-readiness-checklist \
+  --target /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  --candidate-root /safe/path/prc-remediation-run \
+  --provider codex \
+  --allow-remote-source-processing \
+  --verifier-runtime docker \
+  --verifier-image registry.example/prc/python-verifier@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
+  --max-attempts 3 \
+  --max-duration-seconds 1800 \
+  --format json > remediation-run.json
+```
+
+The remote-processing flag is mandatory because the sealed prompt contains the
+selected source file. High-confidence secret-like material in that input causes
+a policy stop before the candidate root or provider output directory is created;
+the error identifies only the source path and detector family. The provider
+receives no source-workspace access, shell, network tool, MCP server, secret,
+edit tool, or candidate workspace. Its output
+directory is private and separate from both source and candidate. Each provider
+attempt preserves `agent-task.json`, bounded stdout/stderr transcripts, their
+digests, the executable digest, and the schema digest. A proposal is parsed and
+applied by the scanner exactly once in a fresh candidate, then passes the same
+structural, anti-gaming, target-assertion, regression, and source-integrity
+checks as `remediate-proposal`.
+
+`--verifier-image` is mandatory with `--provider`. The reference must include an
+explicit registry and immutable SHA-256 digest, and the image must already be
+present because the runner passes `--pull=never`. The provider and repository
+cannot choose or alter the image, command, or limits. The scanner infers one
+supported command solely from the sealed source path: `go test ./...` for Go,
+`python -m pytest -q` for Python, or `node --test` for plain JavaScript. The
+scanner never invokes package scripts. TypeScript proposal planning remains
+fail-closed because no scanner-owned verifier is registered for that ecosystem.
+Because verification is network-denied and starts with empty scratch caches, the
+selected image must already contain the required toolchain and test runner, and
+the candidate must vendor or otherwise carry every dependency it needs. The
+project does not yet publish a canonical verifier image; operators are
+responsible for reviewing and pinning one for each supported ecosystem.
+
+The candidate is mounted read-only into a read-only container with no network,
+all Linux capabilities dropped, `no-new-privileges`, the caller's non-root
+numeric user, bounded CPU, memory and swap, processes, file descriptors,
+scratch space, time, stdout, and stderr. These flags implement documented
+[Docker runtime isolation and resource controls](https://docs.docker.com/engine/containers/run/).
+The output record contains hashes and byte counts rather than raw test output,
+binds the configured candidate identity separately from its raw workspace-byte
+inventory, and verifies that the candidate bytes did not change during the
+run. A test failure, timeout, output limit, unavailable runtime or image, or
+integrity change rejects the candidate; none is converted to a pass.
+
+If invocation fails before a valid provider output exists, the scanner writes a
+content-addressed `prc.agent-failure/v0.1` record. It uses a scanner-authored
+safe reason, links the sealed task and provider identities, distinguishes the
+failure stage and reason code, and records whichever bounded transcripts were
+successfully persisted. The failed attempt consumes one attempt, is terminal,
+and is never retried automatically.
+
+Current acceptance reconstructs the proposed test before candidate creation,
+requires a conventionally collectable declaration and a recognized behavioral
+failure check, and establishes that the test was added without weakening
+existing tests or regressing prior scanner passes. It then runs the supported
+scanner-owned test command in the isolated verifier and requires exit status
+zero. Go documents `go test ./...` as package-list mode over packages below the
+current directory, and a failing Go test returns a nonzero status
+([Go command reference](https://go.dev/cmd/go/)). Passing the suite proves only
+that the configured command passed in that image; it does not prove complete
+behavioral coverage. Broader R2 autonomy stays disabled until each task has an
+assertion-specific behavioral contract and verifier.
+
+## Apply one validated R2 proposal
+
+`remediate-proposal` is the scanner-owned bridge from a validated Codex or
+Claude Code `suggest` result to an isolated candidate. It never asks the provider
+to edit files and never executes provider-authored commands. The source task must
+still match the current workspace inventory, the assertion must be classified
+R2, its exact finding ID and stable fingerprint must still match a freshly
+reproduced failure, and the candidate destination must be new and outside the
+source tree. The v0.3 fix contract records both the task's triggering finding
+ID and the freshly verified baseline finding ID so the provider handoff remains
+auditable end to end.
+
+```bash
+./prc remediate-proposal \
+  --catalog-root /path/to/production-readiness-checklist \
+  --target /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  --provider codex \
+  --task /safe/path/task.json \
+  --output /safe/path/validated-provider-output.json \
+  --candidate-dir /safe/path/prc-r2-candidate \
+  --verifier-runtime docker \
+  --verifier-image registry.example/prc/python-verifier@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
+  --max-files 20 \
+  --max-changed-lines 200
+```
+
+The strict internal unified-diff parser supports exact-context modification and
+mode-`0644` text-file addition. It rejects deletions, renames, copies, binary or
+mode changes, CRLF patch encoding, non-newline markers, malformed coordinates,
+context mismatches, unlisted or protected paths, and budget overruns before
+acceptance. A conservative anti-gaming pass also rejects changes to existing test
+or specification files, newly introduced suppression or skip directives,
+constant assertions, empty Go tests, test-shaped files without a collectable
+declaration, and invocation-only tests without a recognized behavioral failure
+check. Language-aware payload rules also reject generated tests that request
+process or shell execution, network clients, environment or secret access,
+filesystem mutation or absolute-path reads, dynamic evaluation, deserialization
+execution, or long encoded payloads before creating a candidate. New focused
+local assertions remain permitted. The payload audit is deliberately
+conservative and syntactic; the independent sandbox remains the containment
+boundary for obfuscation or parser gaps. The raw-tree, byte, mode, target assertion, baseline
+regression, and source-integrity audits then run from fresh inventories.
+
+Current R2 acceptance proves the declared deterministic scanner postcondition,
+structural anti-gaming checks, scanner non-regression envelope, and successful
+execution of the registered sandbox command. The anti-gaming checks catch known
+unsafe patch shapes, and the test execution proves the suite passed; neither
+alone proves that a new test is behaviorally sufficient. Broader code-changing
+autonomy still requires task-specific verification and stronger behavioral
+assertions before it can be enabled by policy.

package/bin/docs/scanner/risk-exceptions.md

@@ -0,0 +1,52 @@
+# Signed risk exceptions
+
+A risk exception is an accountable human decision about one exact failed
+finding. It is not a scanner result, cannot turn a failure into a pass, and
+does not change the run's terminal state. The scanner has no command that
+creates, approves, or signs an exception.
+
+The `prc.risk-exception/v0.1` record binds:
+
+- the immutable run, inventory, profile, project, commit, artifact, and
+  environment scope;
+- the exact finding ID, stable fingerprint, assertion, and controls;
+- distinct requester, risk owner, and independent reviewer identities;
+- likelihood, impact, rationale, and worst credible outcome;
+- compensating controls with content-addressed evidence references;
+- monitoring, containment response, remediation owner, plan, and due date; and
+- UTC approval and automatic expiry no more than 366 days apart.
+
+Verification rejects a missing or non-failing finding, scope drift,
+self-approval, duplicate reviewers, future approval, expired decision,
+unbounded duration, unsigned edits, revoked keys, or a key without the
+`risk-exception` scope. The signature must have been issued after approval and
+before verification.
+
+## Verify against immutable history
+
+The bound run must already exist in the private scanner state store. Loading it
+through the history store revalidates its nested plan, inventory, findings,
+evidence, adapter executions, and content identities before exception
+verification:
+
+```bash
+prc exception verify \
+  --file /path/to/PRC-EXC-001.yaml \
+  --state-dir /path/to/private-state \
+  --trust-store /path/to/risk-owner-keys.yaml \
+  --signature /path/to/PRC-EXC-001.signature.yaml \
+  --verified-at 2026-08-23T13:00:00Z \
+  --format json
+```
+
+The output disposition is `accepted_risk_exception`, but its `gate_effect`
+always states that the finding remains failed and the scanner terminal state
+is unchanged. A release process may present that signed decision to accountable
+people; general agent remediation and scanner policy cannot consume it as a
+Pass or silently suppress the finding.
+
+The machine contracts are `risk-exception.schema.json` and
+`risk-exception-verification.schema.json`. Compensating evidence references
+are digests, not proof by themselves; the approving workflow remains
+responsible for retaining and independently authenticating the referenced
+evidence.

package/bin/docs/scanner/security-walkthrough.md

@@ -0,0 +1,236 @@
+# Safe start-to-finish scanner walkthrough
+
+This page explains what happens from installation through a finished report,
+what can go wrong at each step, and what the scanner does about it. Safe
+behavior should not depend on knowing security jargon.
+
+## 1. Choose one exact release
+
+Find a `scanner-vX.Y.Z` release in this repository and use that exact version.
+Do not copy a similar package name from a search result.
+
+For a Node project:
+
+```bash
+npm install --save-dev --save-exact --ignore-scripts --no-audit --no-fund @marinjursic/prc@X.Y.Z
+```
+
+What this changes:
+
+- npm adds the exact scanner version to `devDependencies`;
+- npm installs the small launcher and one matching native package;
+- npm writes or updates `package-lock.json`; and
+- npm does not run package install hooks because `--ignore-scripts` is present.
+
+What could be attacked:
+
+- A misspelled name could install somebody else's package. Use the exact scoped
+  name `@marinjursic/prc` from this repository.
+- A floating version such as `latest` can change between machines. Use the exact
+  release number and commit the lock file.
+- Any package manager or registry can be compromised. Check the release's npm
+  provenance and compare the version with the GitHub release before trusting
+  it. The first npm publication also needs a one-time human bootstrap, which is
+  clearly documented rather than hidden in automation.
+- Install hooks are a common place for unwanted code. The scanner packages have
+  no hooks, no third-party JavaScript runtime dependencies, and the command
+  disables hooks anyway.
+
+The npm launcher never downloads a binary. It reads the exact platform manifest,
+checks the packaged native binary's SHA-256, and starts that file directly
+without a shell. It does not fall back to a program named `prc` on `PATH`.
+
+## 2. Add the easy command
+
+Add this one line to the existing `scripts` object in `package.json`:
+
+```json
+{
+  "scripts": {
+    "scan": "prc scan"
+  }
+}
+```
+
+The shortest repeatable command is:
+
+```bash
+npm run scan
+```
+
+For the stricter run, use `npm run --ignore-scripts scan`; the named `scan`
+script runs, but local `prescan` and `postscan` hooks do not. If you do not want
+to edit `package.json`, use this after the exact package is already installed:
+
+```bash
+npm exec --offline --no -- prc scan
+```
+
+`--offline --no` makes a missing local command fail instead of asking to fetch
+something from the registry. `npm scan` is not valid npm syntax for a custom
+command.
+
+## 3. Build a safe inventory
+
+The scanner reads the target tree and records file paths, sizes, modes, hashes,
+recognized project facts, exclusions, and Git identity. It does not run the
+project's package manager, build, tests, scripts, hooks, containers, or code.
+
+A hostile repository might contain links that point outside the project, huge
+files, changing files, strange Git configuration, invalid text, or generated
+trees designed to waste time. The inventory therefore:
+
+- never follows repository symlinks;
+- uses entry-count, per-file, and total-byte limits;
+- checks a file again after reading it;
+- runs Git with a small scanner-owned configuration and scopes status to the
+  target worktree;
+- excludes only clear caches, generated output, scanner state, and Git internals;
+- records every exclusion and limit instead of silently calling the scan
+  complete; and
+- stops on unsafe or changing input instead of guessing.
+
+## 4. Run the local checks
+
+The normal profile currently has 40 narrow checks. They cover exact repository
+facts such as a usable lock file, workflow parsing, pinned action references,
+private-key armor, selected Kubernetes fields, OpenAPI structure, and direct Go
+HTTP helper calls.
+
+Parsers can have bugs, and one file pattern does not prove a broad engineering
+promise. Each parser has input limits and returns an error or incomplete result
+when it cannot safely decide. A narrow passing check produces only its narrow
+evidence. It does not turn a large linked control into a complete Pass.
+
+For example, finding `README.md` proves only that a nonempty root README exists.
+It does not prove the instructions are correct. Detecting
+`pull_request_target` asks for security review; trigger presence alone is not
+reported as proof of a vulnerability. The six-hour workflow timeout is a named
+value in the selected core profile, not a claim that every project must use the
+same limit.
+
+## 5. Include all 10,042 controls honestly
+
+Every complete report contains every registered control and its exact control
+contract. The generated contracts say what kind of evidence appears necessary,
+whether complete inventory or a project threshold is needed, whether the rule
+looks compound or negative, and what must be shown for Not Applicable.
+
+All generated contracts are marked `generated_unreviewed`. They route future
+work; they are not 10,042 approved automatic tests. Broad controls remain
+`needs_review`, `blocked`, or `partially_verified` until the right evidence
+exists. This is how the scanner uses every rule without inventing thousands of
+false passes.
+
+The full proposed acceptance review for every control is split into bounded
+parts under `research/control-acceptance-criteria/`. Its `README.md` is the
+index. A control owner must still approve and test a contract before it can
+become a trusted automatic check.
+
+## 6. Write the report
+
+By default the scanner writes one private HTML file outside the target project
+and prints its exact path. It creates a new file and never overwrites an old
+one. The target bytes and file modes are checked before and after the scan in
+the test suite.
+
+The terminal uses green for Pass, red for Fail, yellow for blocked or manual
+work, and plain text when output is redirected. The report separates:
+
+- the result of the 40-check local profile;
+- the state of the full 10,042-control catalog;
+- verified findings and exact evidence;
+- controls that still need proof; and
+- inventory limits and exclusions.
+
+Reports can contain project names, paths, evidence summaries, and optional AI
+review text. Treat them as project data. Store them in a private location and do
+not upload them automatically.
+
+## 7. Optional AI review
+
+A normal scan never contacts Codex, Claude, or another remote model. Sign in
+through the scanner once, then use the short AI option:
+
+```bash
+prc login codex
+prc full codex
+```
+
+Use `claude` in both commands for Claude Code. The login is kept in a private
+scanner-only directory; normal provider settings, sessions, instructions, plugins,
+hooks, and MCP servers are not loaded. `--ai` is also explicit permission to
+send bounded, screened source excerpts to the chosen provider. Supported
+temporary API-key environment variables and the longer
+`--review-provider`/`--allow-remote-source-processing` form remain available.
+`prc full codex` is the short spelling of `prc scan --ai codex`.
+
+Before the provider starts, the scanner makes a private snapshot of bounded text
+excerpts. It skips sensitive names and known key or token shapes, gives the
+provider no target path, and marks repository text as untrusted data. Output
+must cite a path and line that was actually shown. A valid location is recorded
+as `snapshot_location_validated`, while the claim remains
+`advisory_unverified`; a real line can still be irrelevant or misunderstood.
+Missing, omitted, runtime, legal, company, or human evidence stays a limitation.
+
+Prompt injection is still possible whenever untrusted text reaches a model.
+The provider gets no general shell, source-reading, write, browser, web, or MCP
+tool. Codex gets only subagent coordination for full review; Claude gets only
+its Agent tool. The coordinator is required to create one separate subagent per
+rule. The scanner checks the final schema, task ID, order, paths, lines, sizes,
+and completeness, but current provider output does not give it trustworthy
+proof that the provider really made every requested internal subagent call. A
+provider that ignores the task can therefore produce only rejected or untrusted
+advice, never verified evidence.
+
+The local provider program itself is a bigger trust boundary. A malicious
+`codex` or `claude` executable runs as your OS user and could ignore command
+flags. The scanner hashes it and isolates configuration and environment, but it
+cannot make a malicious executable safe. Install the official CLI, inspect its
+path with `prc doctor`, and use a separate OS account or stronger outer sandbox
+on a sensitive computer. The remote provider also receives the approved
+excerpts and may charge money. Start with one rule.
+
+AI output is advice only. It cannot change the local result, create a verified
+Pass, make the final Not Applicable decision, or fix a file.
+
+## 8. Optional fixes
+
+`prc scan` has no path to the fix code. Fixing starts only with the separate
+`prc fix` command.
+
+The fix system copies the target into a new private sibling candidate. It never
+edits the original project. Deterministic fixes are limited to scanner-owned
+changes with exact checks. The current AI path supports only one planned
+missing-test task; the provider returns an untrusted patch proposal and never
+edits a candidate itself.
+
+A proposed fix might try to escape its path list, weaken tests, add a skip or
+suppress a finding. The scanner rejects protected paths, unapproved files,
+change-size limits, known test weakening, constant or empty tests, command
+requests, policy changes, and capability expansion. It applies an accepted
+proposal once to a fresh candidate, rescans fresh bytes, and runs a pinned,
+network-denied verifier container for the supported test command.
+
+The container runtime and verifier image are also trusted dependencies. The
+image must already exist, use an immutable digest, and contain its dependencies;
+the scanner never pulls it during the fix. Even a successful candidate is not
+merged, committed, deployed, or called production ready. A person reviews the
+candidate and decides what to keep.
+
+## 9. Read the final state correctly
+
+`profile_satisfied` means the selected executable profile has current acceptable
+evidence. It does not mean all 10,042 broad controls passed or that no bug exists.
+`needs_review`, `environment_blocked`, `no_go`, `machine_work_complete`, and
+similar states keep the missing decision or evidence visible.
+
+The safe end of a normal run is therefore a report, not an automatic rewrite:
+
+```text
+Scan mode: report only; no fixes were applied.
+Detailed report: /private/path/example-api-91c2....html
+```
+
+Open that file, start with red failures and no-go findings, then review yellow
+blocked/manual items. Green means only the exact displayed check passed.

package/bin/docs/scanner/state-and-history.md

@@ -0,0 +1,113 @@
+# Durable state and run history
+
+When `--state-dir` is supplied, a scan writes immutable canonical JSON records
+and transactionally indexes their metadata in `state.sqlite`:
+
+```text
+prc-state/
+├── state.sqlite
+├── artifacts/
+│   └── sha256/ab/<artifact-sha256>
+├── evidence/
+│   └── ab/<evidence-id>.json
+└── runs/
+    └── <run-id>.json
+```
+
+Native artifacts are immutable raw bytes addressed by their declared SHA-256.
+Before writing a payload, the store verifies that the run declares the same
+digest and byte count, recomputes the digest, and refuses a different payload
+at an existing path. Generic adapter artifact descriptors and deliberately
+ephemeral sensitive reports do not authorize payload persistence.
+
+The JSON records are authoritative. SQLite is a query index that can be rebuilt
+from those content-addressed records; it never replaces evidence or changes an
+assessment. Indexing verifies every run and evidence identity against its
+canonical record before one transaction updates runs, results, fingerprinted
+findings, finding locations and evidence links, evidence metadata, inventory
+files, inventory facts, relationships, and the audit event.
+
+## Create private state
+
+Scanner evidence can contain sensitive paths and findings. Keep state outside
+the target repository on a local filesystem and restrict it to the current user:
+
+```bash
+mkdir -m 0700 /safe/local/path/prc-state
+
+./prc scan \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist \
+  --state-dir /safe/local/path/prc-state \
+  --format json \
+  --exit-policy never
+```
+
+The scanner creates a missing state root with mode `0700` and the database with
+mode `0600`. It rejects a pre-existing state root accessible by group or other
+users. Windows relies on platform access controls because POSIX mode bits are not
+available.
+
+The initial store uses a full-synchronous rollback journal, a five-second busy
+timeout, immediate write transactions, strict tables, and connection-level
+foreign-key enforcement. WAL is deliberately not enabled: SQLite documents that
+[WAL requires all users to be on one host and does not work on network
+filesystems](https://www.sqlite.org/wal.html). A remote or shared filesystem is
+not a supported state location even with the rollback journal.
+
+## List indexed runs
+
+```bash
+./prc history list \
+  --state-dir /safe/local/path/prc-state \
+  --limit 20
+```
+
+Exact filters are available for `--target-name`, `--profile`, and
+`--terminal-state`. JSON output conforms to `prc.history/v0.1`:
+
+```bash
+./prc history list \
+  --state-dir /safe/local/path/prc-state \
+  --target-name project \
+  --format json > history.json
+```
+
+Counts preserve distinct states: Pass, Fail, and unresolved/blocked results are
+never averaged into a score.
+
+## Load a canonical run
+
+```bash
+./prc history show \
+  --state-dir /safe/local/path/prc-state \
+  --format json \
+  <run-id>
+```
+
+`history show` obtains the record path from the index, rejects absolute,
+traversing, or symlink-escaping paths, loads the immutable JSON, and recomputes
+its run identity before returning it. A missing, modified, or mismatched record
+is an error; the database is never treated as sufficient proof by itself.
+
+The implementation enables foreign keys explicitly because SQLite does not
+guarantee they are enabled by default, and its integrity audit uses both
+[`PRAGMA integrity_check`](https://www.sqlite.org/pragma.html#pragma_integrity_check)
+and `PRAGMA foreign_key_check`.
+
+Run both checks and obtain indexed record counts with:
+
+```bash
+./prc history check \
+  --state-dir /safe/local/path/prc-state \
+  --format json
+```
+
+A successful JSON response conforms to `prc.state-check/v0.2`. It includes a
+separate finding count; the frozen v0.1 schema remains available for archived
+outputs. Corruption or a
+foreign-key violation is an error and never produces an `integrity: ok` report.
+
+Use [diff-aware evidence invalidation](diff-and-invalidation.md) to compare one
+of these canonical runs to a current target without treating the SQLite index
+as assessment authority.