Integrity and Recovery Diagnostics

This page is the authoritative current-state reference for Prikk’s repository verification and doctor diagnostics. It describes what prikk verify checks, what it does not prove, how prikk doctor interprets verification results, and which repair boundaries are intentionally narrow.

For the storage recovery mechanics behind WAL-tail truncation and signer-backed ref completion, see the durability and crash recovery reference. For trust scope, see the trust and threat model. For operator key input and local maintainer trust setup, see the security and signing setup guide.

Core Caveats

• Prikk is early implementation software and is not a production Git replacement.
• prikk verify is read-only.
• verify checks structural integrity and current repository-local publication trust for publication objects; it is not a global trust proof.
• There is no repository-wide AUTHOR trust enforcement.
• MAINTAINER key revocation exists (prikk trust maintainer remove), but there is no historical PKI (temporal/point-in-time revocation semantics), key rotation, hardware signing, remote trust, sync trust, or stable migration policy yet.
• prikk doctor repairs are opt-in and narrow.
• Doctor recommendations are human guidance, not an automated recovery policy.
• Output fields, counters, severity labels, and issue-code names are current CLI vocabulary, not a stable machine-readable schema.

Verify Scope

prikk verify calls the repository verification layer and prints a read-only report. Current verification covers:

• persisted object placement by object type directory and canonical object path;
• object envelope decoding and recomputed object identity;
• Block payload decoding and references to parent Blocks, Patch objects, and optional snapshot Blobs;
• joint ref pointer, RefState-chain, and ref-log-chain consistency;
• signed RefUpdate log record decoding;
• warning-level format-1 signature-envelope diagnosis for malformed Ed25519 shape, duplicate tuples, and non-canonical order;
• active WAL replay, including trailing partial WAL byte reporting;
• whether active WAL Patch records already exist as persisted Patch objects;
• active WAL ref metadata health;
• active rollback-draft WAL record classification;
• sealed rollback Block and sealed rollback Patch classification;
• repository-local publication trust for Block, RefState, and RefUpdate envelopes.

Object enumeration, Block/RefState reads, active-WAL replay, active metadata, ref pointers, and ref logs all use the same retained repository-root authority. Publication trust consumes the exact Block, RefState, and RefUpdate envelopes returned by those anchored structural scans; it does not reopen publication paths in a separate trust phase.

Publication trust, format-1 signature-envelope warnings, and recognized ref-publication state issues are collected separately from hard structural verification errors. This lets the command preserve and diagnose legacy bytes while still returning command failure when trust is invalid or a blocking interrupted-publication state exists.

What Verify Does Not Prove

verify does not prove that a repository is globally trustworthy. It does not enforce repository-wide AUTHOR trust, historical PKI semantics (temporal/point-in-time revocation tracking – verify only ever checks against the current adopted-key snapshot), key rotation, remote identity, remote trust, hosted forge policy, or thresholds beyond the current repository-local required = 1 maintainer policy.

verify also does not prove production readiness, stable repository-format migration, complete cross-platform filesystem behavior, merge execution safety, semantic conflict resolution, backup coverage, or successful recovery from every crash shape.

verify does not read the received-ref index. Ref pointers imported by prikk bundle import live in refs/containers/received-index-{a,b}.container and are outside the verification surface entirely. They are also not rebuildable: the origin ref name exists only inside the imported bundle, which may be gone. So nothing detects their loss or corruption — a gap in verify’s own scope, independent of platform.

Verify Output and Exit Behavior

The current CLI prints counters for checked objects, Blocks, rollback Blocks, sealed rollback Patches, WAL records, persisted WAL Patches, refs, ref-log records, rollback draft WAL records, publication trust records, publication trust issues, ref-publication issues, and trailing partial WAL bytes. It also prints signature-envelope warnings and the active WAL metadata state.

Signature-envelope warnings use at most one issue per code per envelope, in malformed, duplicate, then non-canonical-order sequence. Object findings are ordered by numeric object type and raw ObjectId bytes, followed by active WAL sequence, then unsigned UTF-8 ref-name bytes and ref-log sequence. These warnings do not independently make verify fail and never authorize normalization or mutation of the legacy envelope.

The command exits with failure when:

• structural verification returns an error before a report can be produced;
• the report has a non-empty active WAL with missing or malformed active ref metadata; or
• the report has publication-trust issues; or
• the report has a blocking ref-publication issue such as a one-transition pointer lead, a bounded format-1 log lead, matching active state retained after completed publication, a missing format-1 pointer with log history, or an unproved pointer/log divergence.

Trailing partial WAL bytes are printed as a warning in the report. The recovery mechanics and safe truncation boundary are covered by the durability and crash recovery reference.

Active WAL Metadata States

ActiveWalMetadataStatus currently has six states:

Only the non-empty missing/malformed states are active-session integrity issues. Empty-WAL metadata states are local debris warnings because no WAL records need ownership for publication.

Doctor Scope

prikk doctor is an actionable diagnostic layer over repository verification. When verification completes, doctor prints the verification report, emits issue lines with severity, code, message, and recommendation, then prints an issue summary.

When verification fails before a report can be produced, doctor emits a verification-error issue and recommends preserving the repository before attempting repair.

Doctor output is intended for human diagnostics. The issue-code strings and severity labels are current CLI vocabulary, not a stable JSON/API contract.

Doctor Issue Catalog

Current doctor severities are info, warning, and error.

Publication-trust issues can also appear in doctor output as error-severity diagnostics using the trust issue code and message from publication-trust verification. Ref-publication diagnostics use their verification codes: pointer lead, legacy log lead, retained active cleanup, missing pointer, and unproved divergence are errors; candidate debris and non-canonical legacy timestamps are warnings. Signature-envelope diagnostics appear as warnings using PRIKK-VERIFY-SIGNATURE-MALFORMED, PRIKK-VERIFY-SIGNATURE-DUPLICATE, and PRIKK-VERIFY-SIGNATURE-NONCANONICAL-ORDER. Doctor does not rewrite those envelopes.

MissingForEmptyWal and ValidForNonEmptyWal are healthy metadata states and do not produce doctor issues by themselves.

Doctor Repair Boundary

Doctor’s supported repair switch is --repair-wal-tail. The former --repair-main-ref input is retained only to return an explicit format-1 compatibility refusal in 0.18.0; it performs no repair.

Repair refuses to run when repository health has error-severity issues. The detailed recovery mechanics and safety preconditions for those repairs live in the durability and crash recovery reference. Local lock conflicts, stale-lock limits, and ref compare-and-swap conflicts are covered by the concurrency and locking reference.

Doctor does not synthesize missing objects, repair malformed ref logs, repair checksum mismatches, repair signatures, auto-trust keys, reconstruct trust policy, recover key material, reconstruct ref pointers, clear unsafe active sessions, or define stale-lock cleanup. Exact interrupted-publication completion requires signer-backed seal with matching retained active state.

Relationship to Rollback Verification

Repository verify counts active rollback-draft WAL records after classifying and decoding rollback-marked Patch payloads under the supported replay subset. It also counts sealed rollback Blocks and sealed rollback Patch references.

prikk rollback-draft-verify is a stronger selected-ref pre-seal check for one active rollback draft. It verifies that the active WAL contains exactly one rollback draft and that the draft payload matches the inverse Patch derived from the selected ref. See the rollback draft verification guide for the command-level boundary.

Deferred Work

Still deferred: broader repair policy, stale-lock policy, missing-object recovery, malformed-log repair, checksum-mismatch repair, object quarantine and garbage collection, repository-wide AUTHOR trust policy, key rotation, hardware signing, remote trust, hosted identity, JSON output, stable diagnostic schema, backup/restore tooling, stable repository-format migration, and production readiness. (MAINTAINER key revocation is no longer deferred — prikk trust maintainer remove.)

Claim-to-Source Anchors

Provenance

This reference consolidates current behavior through the DC-39 implementation candidate. It follows the DC-26 documentation-home model: current-state references live in the published mdBook, not under rfcs/fdds/. DC-38 documents pointer-first publication diagnostics and the narrower doctor boundary; DC-39 adds strict new-envelope admission and byte-preserving format-1 signature diagnostics.