oka_artifacts library

Content-addressed artifact store with delta chains (ADR-0043).

Git stores pointers; bytes live here. Snapshot cadence emerges from measured delta ratios — the "diff → diff… → snapshot" shape, with no configuration and no cron.

Classes

ArtifactPointer

Provenance-bound pointer to one stored artifact.

ArtifactStore

The store. All writes are atomic (temp + rename); all reads verify hashes at every step.

DeltaChain

Append deltas against the materialized head while they pay; otherwise take a fresh snapshot. A delta "stops paying" when DeltaRatio fires, when maxChainDepth is reached, or after orEvery revisions since the last snapshot.

DeltaCodec

Encodes target against base and reconstructs target from (base, delta).

DeltaRatio

Delta pays while deltaSize / fullSize <= over.

Materialization

Result of walking a chain back to full bytes.

RecordReceipt

One recorded revision's receipt.

SharedPrefixCodec

Test codec whose delta size tracks the shared prefix: tiny deltas for tiny edits, huge deltas for unrelated content — ratio-driven rollover becomes deterministically testable.

SnapshotOnly

Full snapshots only; dedup by content hash still applies.

StorageStrategy

How the store may represent a new revision of one artifact.

VerifyReport

XorTestCodec

Deterministic invertible codec for tests: delta = length-prefixed XOR of target against the repeated base. Delta size tracks target size (ratio ~1.0 — chains never roll by ratio), so ratio-driven rollover needs a controllable codec like SharedPrefixCodec.

ZstdCliCodec

zstd --patch-from via the CLI (ADR-0043 decision 4: chosen codec — fast, ubiquitous, one flag). Compression and decompression both need the base file, which is exactly the chain materialization pattern.

Functions

encodeCanonical(Map<String, Object?> value) → String

JSON helper shared by the store files (sorted keys, compact).

Exceptions / Errors

ArtifactCodecException

A codec operation failed mid-store.

ArtifactStoreCorruptException

A chain failed integrity during materialization; the problems name each broken link. Never silently truncated.