Crate prikk_store

Expand description

Storage crate for Prikk repositories.

This crate provides persistent layout, object storage, WAL durability, deeper read-only repository verification, initial ref-state/ref-log publication primitives, a narrow active-session append API, opt-in safe doctor repairs, conservative snapshot materialization, read-only worktree status, minimal worktree-to-patch draft generation, supported patch replay planning and materialization, explicit opt-in deletion of patch-removed files, deterministic arbitrary-span text edit replay and generation from worktree changes, explicit unborn local branch genesis through active-WAL ref ownership, read-only inverse planning for the supported patch subset, non-mutating rollback preview, conservative rollback draft append to an empty active WAL, rollback draft verification, sealed rollback block classification, and an internal patch-algebra foundation. Production confluence, plugin execution, and remote sync remain separate increments.

Structs§

AcceptOptions: DC-86 resource bound for accept_exchange_artifact, checked before any decode or write – the same shape BundleImportOptions gives import_bundle.
AcceptReport: Summary of an exchange-artifact accept.
ActiveCommitResult: Result of appending a patch envelope to the active session.
ActiveLock: Active session lock acquired before mutating an active WAL tail.
ActiveSession: Default active-session handle.
ActiveWalOrderingIssue: One active-WAL record whose sequence did not strictly increase over the previous record.
AdoptedMaintainerKey: One adopted MAINTAINER key. DC-78 §D5’s full TOFU provenance (the block id a key was first accepted at, and the ref name it arrived under) is recorded only for keys adopted through exchange, which lands with the import path — a key declared locally via trust maintainer add has no such provenance to record.
BlockSealVerification: Which adopted MAINTAINER key sealed a given Block (DC-78 §D3). Reporting only: the sealer’s key id already lives, non-strippably, inside the block’s own signature.
BlockStateOutcome: One block’s resolved outcome from [verify_blocks_topological].
BundleExportReport: Summary of a bundle export.
BundleImportOptions: DC-86 resource bound for import_bundle, checked before any object is decoded or written — DC-57’s shape: a hard block ahead of any write, with a documented default the CLI may override.
BundleImportReport: Summary of a bundle import.
CheckoutPlan: Read-only plan for a future checkout/materialization operation.
CommitIndexDivergence: One path where the commit-index’s recorded content hash disagrees with the worktree’s actual current content, despite the entry’s stat still matching — the case the cache-validity specification’s §5/§6 exists to catch: a stat heuristic that was trusted but wrong (mtime granularity, clock skew, a misbehaving filesystem).
CompactionReport: Outcome of one compaction run: how many live records existed before and after reduction. This is the deduplication compaction performs on index/pointer records, not object deletion – nothing in this module ever deletes an object; entries_before - entries_after counts stale pointer/ snapshot records reclaimed, never data. plan_compact_* returns the same shape without writing anything – what a real run would report.
ContainerLockGuard: RAII guard for one or more container locks, acquired together by acquire_container_locks and released when dropped. Held for its Drop effect, not read from – the same shape ActiveLock/RefLock already use.
DoctorIssue: One doctor diagnostic.
DoctorRepairOptions: Opt-in repair switches for doctor.
DoctorRepairReport: Report returned by an opt-in doctor repair run.
DoctorReport: Doctor report.
Ed25519AuthorSigner: Production AUTHOR signer: a real Ed25519 keypair plus a caller-provided key id.
Ed25519MaintainerSigner: Ed25519-backed maintainer signer built from caller-supplied key material.
ExchangeExportReport: Summary of an exchange-artifact export.
FileObjectStore: File-backed object store.
HaveList: A decoded, self-consistency-checked PSYNCHV1 have-list.
HeldLock: One lock file found on disk, parsed from its own body (lock.rs::lock_body’s format: pid=<n>\nkind=<k>\nnote=...\n).
HistoryEntry: One published RefState and its target Block summary.
LifecycleCacheDivergence: One disagreement between the persisted incremental cache and an independent full replay of the block it currently claims to represent — the persistence-fault case the checksum and from_replay’s structural check do not, by themselves, catch (design document §6).
LocalTagCreation: A local tag freshly created by create_local_tag or adopt_tag.
MaintainerTrustPolicy: The repository-local set of adopted MAINTAINER keys (DC-78 §D2). A Block/RefState is trusted if any adopted key signed it — object trust, not ref authority; adopting a key never lets it move a ref (RefStore::publish still requires a signature from this operator’s own signer).
MemoryObjectStore: In-memory test object store for fixtures and early callers.
MergeEvidenceDisplay: Public display view for read-only merge/conflict evidence.
MergeEvidenceDisplayItem: Public display item for a merge-evidence report.
MergeEvidenceDisplayOperation: Public operation summary for merge-evidence display.
MergeEvidenceDisplaySelector: Submitted selector and resolved block identity for display.
MergeExecutionReport: Result of a completed merge execution.
MergePlanDisplay: Public display view for a read-only merge plan.
ObjectItemOutcome: One object record’s resolved outcome.
ObjectReadSnapshot: Read-only object access for one operation’s lifetime (RFC 111 §6.1). Takes one decoded index snapshot at construction and never re-decodes – correct because a reader never writes, so it can never observe its own write as missing the way a writer holding a stale snapshot could (RFC 111 Q3). A snapshot taken here may miss an object a concurrent writer appends after construction; that is verify’s own already-documented point-in-time semantics, unchanged by this type (RFC 111 Q4).
ObjectVerification: Verification summary for a single persisted object.
ObjectWriteSession: Read-write object access for one writing operation’s lifetime (RFC 111 §6.1). Holds the same kind of in-memory index snapshot ObjectReadSnapshot does, but every write decision first calls IndexSnapshot::ensure_current (see its own doc), and every successful write calls it again afterward instead of computing what changed itself (Stage 1 review v1, B1) – ensure_current’s own tail-decode is the only thing ever allowed to grow entries/known_length, whether what it finds is this session’s own write, a concurrent one, or both.
PatchDeletionConflict: A deletion candidate that cannot be safely removed.
PatchDeletionPlan: Read-only plan for explicit patch checkout deletions.
PatchInverseOperationSummary: Summary of one inverse operation.
PatchInversePlan: Read-only inverse plan for the supported patch-operation subset.
PatchMaterializationReport: Result of an opt-in patch replay materialization.
PatchReplayPlan: Read-only result of replaying supported patch operations to an in-memory snapshot.
PatchSetDigest: RFC 117 T1: the newtype itself now lives in prikk-object (TagPayload carries one, and prikk-object cannot depend on this crate) – re-exported here so every existing crate::patch_set_digest::PatchSetDigest / prikk_store::PatchSetDigest path keeps resolving to the same type, unchanged. Every function below that computes one stays here, matching MerkleRoot/compute_state_root’s own split. A 32-byte digest over a canonicalized set of patch ids (RFC 115 Stage 1 design D4). Not persisted as its own object – a pure comparison value, MerkleRoot’s own shape. Lives here rather than in prikk-store (where every value that computes one still does, compute_patch_set_digest and friends) because TagPayload (RFC 117 T1) carries one, and prikk-object cannot depend on prikk-store – the same crate-boundary reason state_root.rs’s compute_state_root stays in prikk-store while MerkleRoot itself lives here.
PublicationTrustIssue: One publication-trust issue found during repository verification.
ReceivedPointer: One received ref pointer.
ReceivedTagSummary: One received tag’s own name, signature outcome, and resolution state (prikk sync tags).
RefFileOutcome: One pointer or log entry’s resolved outcome.
RefHistory: Read-only history view for a single ref.
RefItemOutcome: One ref’s resolved outcome.
RefLock: Ref-specific lock acquired before publishing one ref pointer.
RefLogRecord: One decoded ref-log record, scoped to one ref’s own subsequence. Was refs/log.rs’s own type before RFC 102 Stage 4 retired that per-file codec; kept the exact same name and shape since RefStore::replay_log’s public return type (and every one of its 13 production callers) never changed.
RefLogReplay: One ref’s own log replay result – replay_ref_subsequence’s own return type.
RefPointerSummary: One enumerated ref pointer, for deterministic listing.
RefPublication: Inputs for a single ref publication primitive.
RefPublicationIssue: One recognized interrupted-publication or local-debris condition.
RefRecoveryCandidate: Diagnostic ref candidate derived from an append-only format-1 ref log.
RefStore: File-backed ref-state and ref-log store.
RepoPath: A validated repository-relative path.
RepositoryLayout: Repository layout paths.
RepositoryVerification: Repository verification summary.
RollbackDraftReport: Result of appending a supported inverse Patch draft to the active WAL.
RollbackDraftVerification: Verification result for one active rollback draft.
RollbackPreviewChange: One file-level change that rollback would make if later authorized and materialized.
RollbackPreviewPlan: Read-only preview of applying the supported inverse plan back to the latest snapshot baseline.
SignatureEnvelopeIssue: One warning-level non-canonical signature-envelope condition.
SnapshotCheckoutPlan: Read-only plan for validating a snapshot-backed checkout.
SnapshotEntry: A single file entry in a snapshot manifest.
SnapshotManifest: Decoded snapshot manifest.
SnapshotMaterializationReport: Result of an opt-in snapshot worktree materialization.
StageOutcome: One stage’s resolved outcome.
StateRootEntry: One canonical format-2 clean-state entry.
SyncArtifactBuildReport: Summary of a built PEXCH001, when the delta was non-empty.
SyncRefComparison: One ref’s own comparison result.
SyncSummaryRefEntry: One ref’s own entry in a decoded sync summary.
VerifyOptions: Options controlling how verify_repository walks its thirteen stages (DC-95 Stage 2 Level 1).
Wal: File-backed active-session WAL.
WalRecord: One durable WAL record.
WalRepair: Result of a safe WAL tail truncation.
WalReplay: WAL replay result.
WorktreeChange: A single worktree change detected by the read-only status scanner.
WorktreePatchCommitOptions: Options for authoring a node-addressed patch from worktree changes.
WorktreePatchCommitReport: Result of authoring and appending a node-addressed patch from worktree changes.
WorktreePatchOperationSummary: Summary of one generated patch operation.
WorktreeStatusReport: Read-only worktree status report against a snapshot baseline.

Enums§

ActiveRefMetadata: Active-WAL ref metadata read result.
ActiveWalMetadataStatus: Active-WAL ref metadata status derived during repository verification.
AuthorSignatureVerification: The result of checking one Patch’s AUTHOR signature (DC-53 Stage 1, D3’s first two rows – there is no Fails variant here because that outcome is a genuine item-level failure, propagated as an Err the same way every other authorship-integrity defect in this pipeline is, not a value this type carries).
BlockStateStatus: Outcome of attempting to verify one CurrentV6 Block’s state root during [verify_blocks_topological]’s whole-batch pass (DC-95 Stage 2 Level 2). Distinct from verify::StageOutcome/StageStatus (Level 1): there is no operator-requested halt at block granularity, so there is no Halted analogue — a block’s non-evaluation is always because its own state-derivation parent did not itself evaluate, never because an unrelated walk stopped.
CheckoutMaterialization: What blocks a checkout from becoming a real worktree materialization in this stage.
ClaimSignatureVerification: The outcome of checking one RecognitionClaim’s own MAINTAINER signature (Stage 3 handoff §4.2 item 8; reused by Stage 4 §3’s “report the outcome alongside the result”). Shaped identically to AuthorSignatureVerification and for the same reason: never gating (design D3) means a claim naming a key_id this repository has not adopted still accepts – it reads Unverifiable, never Sound, and does not by itself refuse. Only a signature that fails to verify against a key_id this repository has adopted refuses (a forged claim under a locally-trusted identity is an integrity failure, not a trust question). There is no Fails variant for the same reason AuthorSignatureVerification has none: that outcome is a genuine refusal, propagated as an Err, not a value this type carries.
ContainerSlot: One container’s pre-allocated alternate slot (RFC’s §3.2 compaction requirement: a fixed A/B pair of names, never a rotated/new name). Object and ref-log containers keep B reserved-but-unused forever, per design-v1.md §15.2 – object compaction has no data model to target and the ref log must never be compacted (DC-38/DC-69). The three genuine compaction targets (ref pointer index, received-ref index, trust policy container – design-v1.md §15.1) got their own A/B slots in Stage 6 Step 1; B is written only once Stage 6 Step 2’s compactor exists.
DoctorSeverity: Severity assigned to a doctor diagnostic issue.
LockableContainer: One of the four containers RFC 102 Stage 6 Step 2 locks against concurrent writer/compactor races (design-v1.md §15.8, ruled wide by the project owner over the developer’s own narrower lean): the three genuine compaction targets, plus the ref log, whose own tearing exposure predates RFC 102 and is not caused by compaction, but is fixed here because the exclusion machinery being built for compaction closes it for free. trust_key_container is deliberately absent – it never compacts, and stays protected by the unchanged, repository-wide ActiveLock alone, the same as before this stage.
MergeEvidenceTarget: Target selector for prikk merge-evidence.
ObjectItemStatus: Outcome of attempting to verify one persisted object record (DC-95 Stage 2 Level 2, Phase A). No NotEvaluated variant: Phase A’s per-object checks (decode, schema, signature, trust, reference existence) have no real dependency on any other object’s own outcome (Step 0 §1.1) – every object is independently attempted.
PatchInverseOperationKind: Supported inverse operation kind.
PatchSetResolution: RFC 117 T2: the outcome of resolve_patch_set_digest. NotHeld is not an error – the ordinary “you have not synced that far yet” case – and ambiguity is never a variant here: design T2 rules more-than-one-match a refusal, so a caller cannot accidentally proceed on an ambiguous answer by pattern-matching past it.
PidLiveness: Best-effort, advisory-only liveness of a lock’s recorded pid=. See the module doc for why a negative or unknown result must never be treated as authorization to clear the lock.
ReceivedTagResolution: The resolution half of ReceivedTagSummary – the same three states RFC 117 T2 already distinguishes, restated here because resolve_patch_set_digest reports ambiguity as an Err (a refusal to pick, appropriate for a caller about to act on it) where a listing command instead wants it as a value to display alongside every other row, not a reason to abort the whole list.
RecognitionClaimConsistency: The outcome of checking a RecognitionClaim against the receiver’s own store. Three states, not a bool and not a Result<()> that would flatten “absent” into “fine” — BlockAbsent is the expected case in real exchange and must not read as a degraded one.
RefFileStatus: Outcome of attempting to read one pointer or log entry (DC-95 Stage 2 Level 2). path is a display-only locator (the owning container’s own path, plus the specific record’s byte offset where one exists) – not a real per-ref filesystem path, the same repurposing Stage 3 already made for ObjectItemOutcome::path, since a container holds many refs’ records, not one file per ref.
RefItemStatus: Outcome of attempting to classify one ref by name (DC-95 Stage 2 Level 2), after its pointer and/or log file (whichever exist) were themselves read. No NotEvaluated distinct from Failed: unlike Level 1’s stages or Phase B’s blocks, a ref has no peer ref it depends on – its own pointer/log files are its own data, the same footing as an object’s own file in verify_objects Phase A – so a failure attributable to this ref, whether from its own file read or from classify_ref_state itself, is Failed, not a dependency-graph claim about another item.
RepositoryFormat: Repository format selected by the authoritative .prikk/FORMAT marker.
RollbackPreviewChangeKind: File-level rollback preview change kind.
SealFromAcceptedOutcome: The result of seal_from_accepted_claim.
SignatureEnvelopeSource: Persisted source of a signature-envelope diagnostic.
StageStatus: Outcome of attempting to evaluate one verification stage (DC-95 Stage 2 Level 1). No stage may be silently absent from a report. A stage’s own check raising an error is recorded as a blocking finding against its scope rather than aborting the rest of verification (Failed); a stage that could not run because a real dependency did not evaluate is itself blocking, not silently skipped (NotEvaluated); a stage that could have run on its own terms but was preempted by an operator- requested early stop is also blocking, but for a different reason it must not be confused with (Halted) — a repository whose verification is incomplete is not verified, regardless of which of the three non-Evaluated states explains the gap.
StateRootContent: Content identity committed by one canonical clean-state entry.
SyncArtifactOutcome: The result of build_sync_artifact.
SyncRefComparisonState: One ref’s own comparison state, from compare_sync_summary.
TagSignatureVerification: The outcome of checking one received Tag object’s own MAINTAINER signature. Shaped identically to ClaimSignatureVerification and for the same reason (design T6 point 3, T3): never gating. A tag naming a key_id this repository has not adopted still accepts – it reads Unverifiable, never Sound, and does not by itself refuse. Only a signature that fails to verify against a key_id this repository has adopted refuses (a forged tag under a locally-trusted identity is an integrity failure, not a trust question).
VerificationStage: One of the thirteen top-level scopes verify_repository’s pipeline is organized into (DC-95 Stage 2 Level 1: scope containment). Named in pipeline order; the order itself is load-bearing for NotEvaluated naming (StageStatus::NotEvaluated’s blocked_by is always an earlier stage).
WorktreeChangeKind: Worktree change kind.
WorktreePatchOperationKind: Generated operation kind for CLI/reporting.

Constants§

DEFAULT_ACTIVE_PATCH_LIMIT: DC-57 default hard block on active (queued, unsealed) patches — NFR-PERF-02’s default 1000, overridable per invocation via PRIKK_ACTIVE_PATCH_LIMIT at the CLI boundary, never persisted.
DEFAULT_BUNDLE_MAX_OBJECT_COUNT: DC-86 default hard block on a bundle’s declared object count, checked as early as the format allows — right after the count header field, before a single object is decoded. Not a claim about what any real bundle needs; a ceiling an operator can rely on existing at all.
DEFAULT_BUNDLE_MAX_TOTAL_BYTES: DC-86 default hard block on a bundle’s total encoded byte length, checked before any decoding begins. This length-prefixed format can never decode to more logical content than its encoded input size, so bounding the input bytes is a tight, cheap proxy for bounding decoded bytes — cheaper than decoding first only to discover the result should have been refused. 256 MiB.
DEFAULT_CHECKOUT_REF: Default ref used by checkout planning.
DEFAULT_EXCHANGE_ARTIFACT_MAX_OBJECT_COUNT: DC-86 default hard block on each of the artifact’s declared counts (five as of stage 3’s Tag section), checked as early as the format allows – mirroring DEFAULT_BUNDLE_MAX_OBJECT_COUNT’s reasoning exactly, restated here because this is a distinct format with its own ceiling, not a reuse of the bundle-specific one.
DEFAULT_EXCHANGE_ARTIFACT_MAX_TOTAL_BYTES: DC-86 default hard block on the artifact’s total encoded byte length, checked before any decoding begins – the same tight, cheap proxy DEFAULT_BUNDLE_MAX_TOTAL_BYTES uses, restated for this format. 256 MiB.
DEFAULT_HAVE_LIST_MAX_PATCH_COUNT: DC-86 bound on the have-list’s declared patch count, checked before the list is allocated.
DEFAULT_HAVE_LIST_MAX_TOTAL_BYTES: DC-86 bound on the have-list’s total encoded byte length, checked before decoding starts.
DEFAULT_HISTORY_LIMIT: Default number of history entries shown by the CLI.
DEFAULT_SYNC_SUMMARY_MAX_REF_COUNT: DC-86 bound on the summary’s declared ref count, checked before the section is allocated.
DEFAULT_SYNC_SUMMARY_MAX_TOTAL_BYTES: DC-86 bound on the summary’s total encoded byte length, checked before decoding starts.

Traits§

AuthorSigner: A provider that produces the detached signature bytes for an authored patch.
MaintainerSigner: A provider that produces detached signature bytes for a publication object.
ObjectReader: Read-only object access boundary.
ObjectWriter: Write object boundary.

Functions§

accept_exchange_artifact: Accept a PEXCH002 exchange artifact (handoff §4). Writes patches, blobs, recognition claims, and Tag objects (RFC 117 stage 3 §3) – and records AUTHOR key material – only once every fallible check has already passed. Never touches a ref, a Block, or the received namespace: this is patch-level exchange (§0’s “the unit is the patch”), and Stage 3 does not extend the accept path into sealing (§1’s scope cut) or into tag adoption (RFC 117 T4 – a received Tag is stored and reportable, never adopted; see tag_travel::adopt_tag for the separate, explicit act that does adopt one).
accepted_but_unsealed_patch_ids: D2’s derived query (design-v1.md §3, RFC 115 Stage 3 §5): no new container, no stored pending state. “Accepted but unsealed” is computed, every time it’s asked:
acquire_container_locks: Acquire every lock in containers, sorted into LockableContainer’s fixed Ord before any file is created (design-v1.md §15.7’s deadlock ruling: a single acquisition helper that sorts the caller’s requested set, not per-call-site ordering discipline) – so two call sites that each request {RefPointerIndex, RefLog} always acquire them in the same order regardless of which order their own arguments list them in.
add_trusted_maintainer: Adopt a MAINTAINER key (DC-78 §D2/§D5): add it if the key id is new; succeed idempotently, changing nothing, if it is already adopted with the same public key; refuse if it is already adopted with a different public key. This is DC-78’s TOFU enforcement — “a changed key for a known key id is refused, not re-prompted” — not just the create path for a fresh key id. TOFU history persists across removal: the key-material container is never pruned, so re-adopting a key id that was previously removed from the active policy with a different public key is still refused — the identity was seen once, and a changed key under a familiar id is exactly what TOFU exists to catch, active policy membership or not. Returns the adopted key and whether this call actually wrote anything.
adopt_tag: RFC 117 T4, the ruling this whole module exists to implement correctly: adoption is the receiver’s own signed act, never conjured from someone else’s assertion. Resolves the one received tag named requested_name (validate_local_tag_ref-canonicalized first, since a received tag’s own claimed name is untrusted) to a local block via stage 2’s resolve_patch_set_digest, then creates a local Tag naming that block, the identical patch_set_digest/patch_count, signed under signer’s own key via create_local_tag – the ordinary tag-creation path, not a parallel one.
append_rollback_draft: Append a signed inverse Patch draft to an empty active WAL.
author_signature: Build a role-bound AUTHOR Signature for the unsigned patch object_id using signer.
build_have_list: Build a PSYNCHV1 have-list for ref_name, from this repository’s own current state.
build_sync_artifact: Build the PEXCH002 exchange artifact that closes ref_name’s gap, from a have-list received from the other side. See the module doc for why claims are never trimmed to the delta.
build_sync_summary: Build a PSYNCSU1 sync summary covering every local heads/* ref, in RefStore::list_ref_pointers’s own sorted-by-name order. remotes/* and tags/* are excluded – see the module doc. A repository with no heads/* ref at all still encodes validly, as a summary declaring zero refs.
check_recognition_claim_consistency: Check claim against object_store. See the module doc for why sequence equality, not set equality, is the correct comparison under D6/N3’s verbatim-order contract, and for why Contradicted names the disagreeing field.
clear_lock: Clear one specific lock file by path. The caller (prikk unlock) is responsible for obtaining operator confirmation before calling this – this function performs no confirmation, no liveness check, and no safety gate of its own: by the time it is called, the decision has already been made by a human who read list_held_locks’s own advisory. Removing a lock that is still genuinely held lets two writers race the container it names – that is the whole risk this module exists to keep an operator, not a heuristic, deciding.
commit_worktree_changes_signed: Author a node-addressed patch from worktree changes against the replay-derived baseline, sign it with a real role-bound Ed25519 AUTHOR signature from the injected signer, and append it to the active WAL (DC-09 Phase 4.4a, R1). Existing paths resolve to their persisted node_id; fresh nodes are minted through the production [NodeIdGenerator]; text edits go through the shared text_span module. There is no placeholder signing path.
compact_received_index: Compact the received-index container: last entry per ref_name_key survives, matching lookup_received_index_entry’s own resolution exactly.
compact_ref_pointer_index: Compact the ref-pointer-index container: last entry per ref_name_key survives, matching lookup_ref_pointer’s own reverse-scan resolution exactly – compaction changes which bytes are on disk, never which pointer a lookup resolves to.
compact_trust_policy: Compact the trust-policy container: only the last complete snapshot survives – not a per-key reduction like the other two, because this container is snapshots, not an append log of individual adoptions (trust_index.rs’s own module doc). Every earlier snapshot is, by definition, entirely superseded.
compare_sync_summary: Compare this repository’s own heads/* refs against a remote summary’s entries (handoff §2). None of the four states is a refusal – an asymmetric ref set (one side names a ref the other does not hold) is ordinary, ruled by design §5 item 6 / N5 item 6 and carried forward through every stage since: a receiver-absent have-list is empty, not a refusal (stage 2/3); a sender-absent ref reports AlreadyInSync, not a refusal (stage 3). This function is the same principle applied to the summary’s own comparison, which stage 2’s review flagged as pinned by a passing test and by no control.
compute_patch_set_digest: Compute the patch-set digest over an already-sorted, deduplicated slice of patch ids. The count is hashed even when patch_ids is empty, so an empty set is distinguishable from a degenerate one (matching state_root.rs’s own empty-case discipline, compute_state_root).
compute_patch_set_digest_and_count_from_block: RFC 117 T7: the digest and the count together, over one traversal – patch_count is not new information (patch_set_digest_preimage already hashes it), so a caller populating both of a TagPayload’s field 6/7 should never pay for patch_ids_reachable_from_block’s own ancestors_inclusive walk twice.
compute_patch_set_digest_for_ref: The ref-rooted entry point, and the one two independent repositories can actually use: neither side can name the other’s Block id (that is the premise the digest exists to work around, RFC 115 design §7), so a Block-rooted call alone would not serve the digest’s own purpose.
compute_patch_set_digest_from_block: Compute the patch-set digest for the closure reachable from tip_block_id directly – the block-rooted core, ref-resolution-agnostic, so a caller that has already resolved a ref through any mechanism (RefStore, a received pointer, a future one) can reach the same computation without this module re-deriving how to resolve it.
compute_state_root: Compute the format-2 state root from entries in strict canonical path order.
compute_sync_delta: N4 (design-v1.md §4): the delta for the one ref have_list names – every patch id reachable from this repository’s own tip for that ref, minus what have_list says the other side already has. Returned sorted (§3’s own instruction), following naturally from patch_ids_reachable_from_block’s own BTreeSet-derived order. Does not build a PEXCH001 artifact – see build_sync_artifact for that – and constructs no RecognitionClaimPayload, only a Vec<ObjectId>.
create_local_tag: Create and publish a local, receiver-signed (or locally-signed) Tag at requested_ref_name, naming target_block_id with the given patch_set_digest/patch_count – the one place a Tag object and its tags/* ref are ever written, so both prikk tag create (prikk-cli) and adopt_tag go through this rather than each carrying its own copy of the write+publish shape. Validates requested_ref_name itself (validate_local_tag_ref) rather than trusting a caller to have already done so – one caller’s requested_ref_name is untrusted, attacker-controlled data (a received tag’s own claimed name), so this is the trust boundary, not a redundant re-check. Refuses if a ref of that name already exists, the same “create-once” rule prikk tag create already enforces.
decode_have_list: Decode and self-consistency-check a PSYNCHV1 have-list (§1.3). Bounds the total byte length before touching the bytes at all, then the declared patch count before allocating the list – the same DC-86 shape decode_exchange_artifact follows.
decode_sync_summary: Decode a PSYNCSU1 sync summary structurally. Bounds the total byte length before touching the bytes at all, then the declared ref count before allocating, the same DC-86 shape decode_exchange_artifact follows. Performs no cross-entry checks and no comparison against this repository’s own refs – see compare_sync_summary for that.
derive_next_state_root: Derive the state root for a proposed format-2 Block from its parent and ordered Patches.
doctor_repository: Run doctor diagnostics for a repository layout.
execute_merge: Execute a merge: seal from_ref’s patches since baseline_block_id verbatim onto into_ref.
export_bundle: Export a genesis-complete, verifiable subset of objects for ref_name (DC-78 §D4/§D6). Walks the full Block ancestor closure (all parents, not mainline-only — ruling 2’s “genesis-complete”) plus every Patch and Blob those blocks reference, plus the exported RefState’s own required attestations. Returns the report and the encoded bundle bytes; writing them to a file is a CLI concern, not this crate’s.
export_exchange_artifact: Export a PEXCH002 artifact carrying exactly patch_ids, in the given order (the sender’s application order, D1 – this function does not reorder them), plus every blob those patches’ operations reference, plus local AUTHOR key material for their signers, plus the already-persisted RecognitionClaim objects named by claim_ids, plus the already-persisted Tag objects named by tag_ids (RFC 117 stage 3 §2). patch_ids must not contain a duplicate; the caller decides the exact identity and order of what it sends, and a repeated id would make the declared count and the ordered list disagree about how many patches this artifact actually carries. Which tags belong in tag_ids is the caller’s decision (sender.rs’s own ancestry filter) – this function carries whatever it is given, the same separation it already keeps for claim_ids.
find_held_lock: Find the held lock naming the same file as target, resolving both sides through the filesystem before comparing. A path reached through a different-but-equivalent route – a symlinked temp directory (every macOS /tmp//var path), a symlinked home, a symlinked mount – must still match the lock list_held_locks itself reports; exact string equality alone silently misses these, telling an operator with a genuinely wedged repository and a genuinely correct path that “no held lock” exists (the CI run that found this: a real lock, a real matching path, reported absent, because HeldLock::path is built from an OS-resolved root while an independently-typed --lock argument is not).
finish_active_publication_cleanup: Drain a fully published active WAL and remove its ownership metadata under the active lock.
import_bundle: Import a bundle’s objects and record a received pointer for its ref (DC-78 §D4). Never touches refs/by-id/, never advances a local ref, and never adopts any MAINTAINER key into the local trust policy — the imported RefState/Blocks remain ordinary, structurally-checkable objects that verify will report as untrusted until the operator explicitly runs trust maintainer add for the key that sealed them. That is a deliberate choice, not an oversight: auto-adopting a key seen in imported history would be a new, unreviewed trust mechanism, exactly what §D6 rules out.
list_held_locks: Enumerate every lock file currently present: the active-session lock, every per-ref lock, and every one of the four container locks. Read-only – never clears anything, matching the module’s own “enumerate and report, never decide” split.
list_received_pointers: Enumerate every received ref pointer, sorted by name — the received-namespace counterpart of RefStore::list_ref_pointers.
list_received_tags: List every received tag (received_tag_ids) with its name, live signature outcome, and current resolution state – the read side of prikk sync tags.
load_maintainer_trust_policy: Load and validate the repository-local set of adopted MAINTAINER keys. Errors if no policy snapshot has ever been appended — a repository with no adopted maintainer is a trust failure for every publication, exactly as the old missing-policy.toml case was (PublicationTrustVerifier’s PRIKK-TRUST-POLICY-INVALID).
load_received_ref_history: Load history for a received ref (DC-78 ruling 4), newest first. Received refs have no ref-log chain of their own (received.rs’s single-overwrite pointer) — this walks the same RefState.previous_ref_state_id links as load_ref_history, starting from the received tip. Each RefState’s embedded name is checked against the origin’s own name (the remotes/ prefix is a local rename applied only to the received pointer, never written into the objects themselves — exactly why received refs cannot use refs/by-id/’s pointer format, whose consistency check requires the opposite: pointer name and embedded name to agree).
load_ref_history: Load history for a ref, newest first.
maintainer_signature: Build a role-bound MAINTAINER Signature for an unsigned publication object.
materialize_patch_checkout: Materialize the supported patch replay result into the repository worktree.
materialize_patch_checkout_with_deletions: Materialize the supported patch replay result and remove explicit patch-deleted files.
materialize_snapshot_checkout: Materialize a snapshot-backed checkout into the repository worktree.
order_claims_for_sealing: Order a batch of recognition claims for sealing (RFC 116 stage 5, N3’s field finally used): a claim’s block is sealed after every claim in the same batch whose block is one of its parents. Kahn’s algorithm over a graph built from each claim’s own block_id/ parent_block_ids – the same shape merge_evidence.rs’s own topological_order already uses for a different node type, restated here because that function is pub(crate) to a different graph (Block ids already held locally) and this one’s nodes are claim ids decoded from a batch that may include blocks this repository does not hold at all.
patch_ids_reachable_from_block: Every patch id reachable from tip_block_id’s ancestry, sorted and deduplicated – the same closure export_bundle walks (bundle.rs:189,208-209), narrowed to patch ids only (no blobs, no attestations: Stage 1’s scope is the patch set, nothing else, per the handoff’s §6).
patch_set_digest_preimage: Construct the exact preimage over an already-sorted, deduplicated, strictly-ascending slice of patch ids. Identity-bearing (documented in release-compatibility.md’s frozen list): two prikk versions must produce identical bytes over the same patch set, or the comparison this digest exists for means nothing across an upgrade.
plan_compact_received_index: Report what compact_received_index would reclaim, without writing anything.
plan_compact_ref_pointer_index: Report what compact_ref_pointer_index would reclaim, without writing anything.
plan_compact_trust_policy: Report what compact_trust_policy would reclaim, without writing anything.
plan_patch_checkout_deletions: Prepare a read-only deletion plan for explicit patch-deleted files.
prepare_checkout_plan: Prepare a checkout plan for a ref without modifying the worktree.
prepare_merge_evidence: Prepare a read-only merge evidence display report.
prepare_merge_plan: Prepare a read-only merge plan display report.
prepare_patch_inverse_plan: Prepare an unsigned inverse Patch payload for the supported patch-operation subset.
prepare_patch_replay_plan: Replay the supported operation subset for a ref without writing the worktree.
prepare_rollback_preview: Prepare a non-mutating rollback preview for the supported patch-operation subset.
prepare_snapshot_checkout_plan: Prepare and validate a snapshot-backed checkout plan without writing the worktree.
read_active_ref_metadata: Read active-WAL ref metadata without mutating it.
read_received_pointer: Read a received ref’s current pointer, if one has been imported.
received_tag_ids: Every Tag object present in this repository that no local tags/* ref currently targets – “received but not (yet) adopted,” computed fresh on every call. See the module doc for why this carries no new persisted state.
remove_active_ref_metadata: Clear active-WAL ref metadata and fsync the active-session directory. Returns whether there was non-empty content to clear (the pre-migration “did a file exist to remove” contract, now answered by content rather than presence – the file itself is permanent from init onward).
remove_trusted_maintainer: Revoke a MAINTAINER key id: remove it from the active policy by appending a new snapshot without it (design-v1.md §14.9 – the same operation add_trusted_maintainer already performs, just shorter; no tombstone record, no new format concept). The key’s own material is never removed from the key-material container – it stays as TOFU history, so a future re-add with a different public key under the same id is still refused. Returns whether the key was actually adopted (a no-op removal of an unadopted id returns false, matching add’s own idempotent-no-op shape). Refuses to remove the last adopted key: an explicitly-empty-but-present policy is a state the old TOML parser could never represent either (keys = [] was rejected as malformed), and introducing it now would be a new state verify’s trust classification does not account for.
repair_repository: Run an explicitly requested, narrow repair action.
require_active_ref_for_non_empty_wal: Validate active ref metadata for a non-empty active WAL.
resolve_patch_set_digest: RFC 117 T2: resolve a patch-set digest to the local block it names, among every block reachable from any local heads/*/tags/* ref (remotes/* excluded – unsealed received history the operator has not adopted, consistent with resolve_ref_to_tip_block’s own refusal of it).
seal_from_accepted_claim: Seal the patches named by the RecognitionClaim at claim_id into ref_name, under signer. See the module doc for the shape of what this does and does not guarantee.
state_leaf_hash: Hash one validated canonical format-2 clean-state entry.
state_leaf_preimage: Construct the exact format-2 leaf preimage for one validated entry.
validate_block_v2_shape: Validate the format-2 Block kind and parent cardinality contract.
validate_local_branch_ref: Validate a local branch ref name and return its canonical identity string.
validate_local_tag_ref: Validate a local tag ref name and return its canonical identity string.
validate_no_path_collisions: Reject duplicate paths and case-insensitive collisions.
validate_received_ref: Validate a received ref name: the reserved remotes/ namespace, required rather than rejected (the mirror image of validate_local_branch_ref/validate_local_tag_ref, which reject it).
validate_repo_path: Validate that a path is safe as a repository-relative path.
verify_active_rollback_draft: Verify that the active WAL contains exactly one rollback draft matching the current ref.
verify_repository: Verify a repository layout without modifying it, with the default options (full accumulation across all thirteen stages). See verify_repository_with_options for --stop-on-first-error.
verify_repository_with_options: Verify a repository layout without modifying it.
verify_signer_trusted: Verify that the signer matches one of the repository-local trust policy’s adopted keys.
verify_trusted_publication_envelope: Verify a publication envelope against the current repository-local trust policy. Returns the adopted key id whose signature matched (DC-78 §D3): the sealer’s identity already lives inside the envelope’s own signature, non-strippably — this is reporting that fact, not new state.
worktree_status: Compute read-only worktree status against the snapshot referenced by a ref.
write_active_ref_metadata: Write active-WAL ref metadata, replacing whatever was there before. pub API, so the replace-semantics contract is enforced structurally rather than by caller discipline (design-v1.md §14.6’s condition): truncates to empty, then appends the canonical ref name, so a second call can never concatenate two names into one file the way a bare append would.