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.
• Prose output fields, counters, severity labels, and issue-code names are current CLI vocabulary, not a stable machine-readable schema. prikk verify --format json emits the versioned verify-report-v1 document (args.rs:147; output/verification.rs:124); doctor has no JSON output.

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;
• active WAL replay, including trailing partial WAL byte reporting;
• object-index and pointer-index trailing-partial and interior-damage reporting (the object index is a pure cache — a reader scans the containers in memory when it is damaged, rather than refusing — so this is never a failure by itself; see durability and crash recovery);
• connectivity: every object a sealed Block’s state, a queued Patch in any active session’s WAL, or a ref tip references must exist and be readable;
• received (remotes/*) pointers: each pointer’s RefState, target, required attestations, and previous state (the ReceivedRefs stage, verify.rs:1484-1489, verify.rs:1916-1960);
• the active session’s commit witness (acknowledged queued commits) against its WAL (the CommitWitness stage);
• 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;
• whether .prikk/current-branch resolves (0.50.0 step 1 A4) — a warning, never a failure: the pointer is a default --ref given explicitly always overrides, not an authority anything above checks.

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 and recognized ref-publication state issues are collected separately from hard structural verification errors. This lets the command return 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 reads the received-ref index. Ref pointers imported by prikk bundle import live in refs/containers/received-index-{a,b}.container. The ReceivedRefs stage checks each pointer’s RefState, target, required attestations, and previous state (verify.rs:1916-1960), and the index file’s own tail and interior damage are reported with the other appended files (verify.rs:1273). What verify cannot see is a pointer that is absent from the index: it checks the entries the index names, and no doctor verb rebuilds this index.

Verify Output and Exit Behavior

The current CLI prints, among other lines: stage outcomes; object, block-state, ref-file, and ref item counts; checked objects, Blocks, rollback Blocks, sealed rollback Patches, refs, ref-log records, WAL records, persisted WAL Patches, and rollback draft WAL records; ref-publication issues; publication trust records and issues; sealed Blocks; object temp warnings; connectivity issues; interrupted appends; unreferenced remnants; trailing partial WAL, object-index, and pointer-index bytes; one line per appended file and per object container tail; the active WAL metadata state; the acknowledged-commit (commit witness) verdict; and commit-index, lifecycle-cache, and merge-baseline divergence counts. 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.

The command exits with failure, and --format json reports ok: false, when any of these conditions holds (crates/prikk-cli/src/verify_verdict.rs, VERDICT_CONDITIONS):

• stage-failure: a verification stage failed or did not complete;
• item-failure: an object, Block state, ref file or ref item, WAL record, or received ref failed; or a connectivity issue is present; or an appended file has interior damage. A connectivity issue is an object a sealed Block’s state, a queued Patch, or a ref tip references that cannot be read. prikk doctor fails on the same condition (PRIKK-DOCTOR-OBJECT-CONNECTIVITY), scoped to the active session whose queued Patch references it when that is the source;
• active-wal-metadata-integrity: a non-empty active WAL has missing or malformed active ref metadata;
• commit-witness-integrity: an acknowledged queued commit disagrees with the WAL in a way the WAL’s sound prefix cannot explain;
• commit-witness-substituted-earlier-record: the acknowledgment history disagrees with the WAL’s running hash at a record before the last acknowledged one;
• blocking-ref-publication: a one-transition pointer lead, matching active state retained after completed publication, or an unproved pointer/log divergence;
• publication-trust: publication-trust issues are present;
• commit-index-divergence, lifecycle-cache-divergence, merge-baseline-divergence, or active-wal-ordering: the named check fails.

A structural verification error before a report can be produced also fails the command.

Trailing partial WAL bytes, trailing partial object-index bytes, object-index interior damage, trailing partial pointer-index bytes, object container tails, interrupted appends, unreferenced remnants, object temp files, and an unresolved current-branch pointer are printed as warnings. None of them fails verify by itself; an appended file’s interior damage does. The object and pointer indexes are caches or repairable tails, so their damage is never a failure — including when the torn entry is the one most recently written, which a reader now rescans the containers for rather than reporting as a missing object (0.50.0 step 1 A5) — but it is never silent either. current-branch is a default, never an authority (RFC 151 §2.1): nothing above reads it, and an explicit --ref always works regardless of whether it resolves. An absent pointer is not a warning (every repository initialized before RFC 151, and every one of this repository’s own fresh inits before the file was first written) — a normal, unaffected state, reported as an informational line instead (0.50.0 step 1 Part D1): current-branch: not set; commands without --ref use heads/main. 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, retained active cleanup, and unproved divergence are errors; candidate debris is a warning.

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

Doctor Repair Boundary

Doctor repairs are opt-in: a plain prikk doctor only diagnoses. The switches, all parsed in crates/prikk-cli/src/args.rs:478-531, are:

• --repair-wal-tail: truncates an incomplete final record from the default session’s WAL and, for each non-default active session, that session’s WAL (doctor.rs:1258).
• --repair-tails [--plan-only]: truncates the incomplete final bytes of the WAL, the pointer index, and the eight appended files, ten files in all (doctor/repair_tails.rs:76). It refuses interior damage in any of them, the identical way with or without --plan-only (0.50.0 step 1 A6 item 4) – the one repair that may cut across ten files in one run, and the last of the five recovery verbs to gain a preview.
• --repair-index: rebuilds the object index from the containers.
• --repair-pointer-index-tail: truncates an incomplete final pointer-index record.
• --rebuild-pointer-index [--plan-only]: re-derives the ref-pointer index from the ref log (RFC 165 R5, pointer_rebuild.rs). Before flipping away from the live slot, a real run saves a full copy of it, of the rebuilt slot’s own pre-rebuild bytes, and of the generation log’s own before/after bytes, to the recovery log under one run (0.50.0 step 1 Parts F/F2) – --recovery-restore <id> undoes the whole switch byte for byte: both slots and the generation record all go back to what they were, naming the old slot live again. A restore refuses, and writes nothing, if an ordinary write has landed in the rebuilt slot since (a new branch, a publication).
• --discard-damaged-commits [--plan-only]: removes an acknowledged queued commit that the commit witness names and the WAL no longer holds soundly (RFC 166 D5, doctor/discard_damaged_commits.rs).
• --restore-queue-target --ref <ref> [--not-current-branch] [--plan-only]: gives an active queue back its owner when its ref metadata is missing or does not match.
• --recovery-list, --recovery-restore <id>, and --recovery-clear: work with the recovery log.
• --repair-main-ref: a recognized input that performs no repair and is always refused (doctor.rs:1263-1269).

prikk ref complete <ref> [--plan-only] is a separate command, not a doctor switch. It completes an interrupted publication that is a completable pointer lead (RFC 165 R4, ref_completion.rs).

Each repair that removes bytes saves them to the recovery log, .prikk/recovery/log (see durability and crash recovery). --repair-index saves the ids it cannot re-derive, when any, the same way.

--repair-pointer-index-tail

Truncates an incomplete trailing pointer-index record — a torn tail, positionally: the last record ends past the file’s own length, and nothing sound follows it. Mirrors --repair-wal-tail exactly in shape and contract, including saving the removed bytes first. Refuses, unchanged, on a genuinely damaged entry (not merely a trailing partial). That entry is not recovered by truncation. prikk doctor --rebuild-pointer-index re-derives the pointer index from the ref log, and it refuses while a pointer lead is still completable, so prikk ref complete <ref> runs first (pointer_rebuild.rs:148-192). Holds the pointer-index lock for its whole run, matching --repair-index’s own discipline.

--repair-index

Rebuilds containers/index.container by scanning the object containers themselves. Use it when verify reports

error: integrity error: index entry for <id> resolves to an envelope with computed id <other>

which means an index entry points at a different record’s bytes. The containers are self-describing — each record carries its own magic, framed length, and checksum — so everything needed to rebuild is still on disk, and a rebuild is a recovery rather than a reconstruction.

The repair reads and writes the index only; container bytes are never touched. It is idempotent: on a healthy repository it reports object index: nothing to repair and writes nothing. The new index is installed atomically — written to a temporary file, fsynced, renamed over the old one — so an interruption leaves one whole index, never a mix.

The repair holds the object-store lock for its whole run — it is a writer to the index like any other, and it takes the same lock every other writer takes. Three consequences, all ordinary lock behaviour:

• a writer (commit, seal, tag create, …) that arrives while a repair is running is refused with lock conflict, and retrying after the repair finishes succeeds;
• a repair that arrives while a write is running is refused the same way;
• a stale objects.lock, left behind by a failed acquisition, refuses the repair with the message naming prikk unlock — the one case where an operator must act before the repair can run at all.

Acquiring the lock only around the final install would not be enough: the repair scans the containers first, and a writer appending between the scan and the install would have its object discarded by an index rebuilt from the older state. The lock covers the scan and the install together.

This state was reachable before prikk 0.40 by running two object-writing commands concurrently; the object-store lock now prevents it (see concurrency and locking). This verb exists for repositories damaged before that lock existed.

Refusals differ by verb. --repair-wal-tail refuses while a repository-wide error exists, and skips an active session that has its own error (doctor.rs:1258, 1275). --repair-tails refuses interior damage in any file it covers. --rebuild-pointer-index refuses ref-log damage and any completable lead. --repair-index checks neither; it rebuilds the index from the containers under the object-store lock. 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, or recover key material. Stale-lock cleanup is prikk unlock. An interrupted publication is completed by prikk ref complete <ref> under RFC 165 R4’s rule (ref_completion.rs); doctor itself does not sign or append a ref state (doctor.rs:1117).

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, doctor JSON output, stable diagnostic schema, stable repository-format migration, multi-ref backup export, a rehearsed repository-format-migration restore, and production readiness. (MAINTAINER key revocation is no longer deferred — prikk trust maintainer remove. Single-ref backup/restore tooling is no longer deferred either — prikk bundle export/verify/import, see Backup and Restore.)

Claim-to-Source Anchors

Provenance

This reference consolidates behavior through RFC 103, which retired format-1 support entirely (see Doctor Repair Boundary above). 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 added strict new-envelope admission and, before RFC 103, format-1 signature diagnostics.