Crate lex_store 

M6: content-addressed store. Spec §4.

Filesystem layout (§4.2):

<root>/
├── stages/
│   └── <SigId>/
│       ├── implementations/
│       │   ├── <StageId>.ast.json
│       │   └── <StageId>.metadata.json
│       ├── tests/
│       │   └── <test_id>.json
│       ├── specs/
│       │   └── <spec_id>.json
│       └── lifecycle.json
└── traces/
    └── <run_id>/
        └── trace.json

The filesystem is canonical. We don’t ship index.db (the spec calls it a cache); the in-memory index is rebuilt on Store::open by scanning the filesystem. Acceptance §4.6 requires that this rebuild produces identical results regardless of cache state — the obvious way to honor that is to keep the cache trivially derivable.

Modules

policy

<store>/policy.json — local trust policy.

users

<store>/users.json — actor identity (lex-tea v3d, #172).

Structs

Branch

CandidateInfo

Per-candidate metadata surfaced by Store::list_candidates (#294). Returned sorted by op_id for deterministic output.

GcPlan

The plan for a single GC pass: which ops survive (with the reason) and which are slated for deletion. apply_gc(plan) turns this into actual filesystem changes.

Lifecycle

Per-SigId lifecycle log: append-only list of state transitions for every implementation that’s ever been published under this signature.

MergeConflict

MergeEntry

MergeRecord

MergeReport

MergeResolutionChecker

Adapter turning a Store + dst branch into a lex_vcs::ResolutionChecker for one merge session.

MergeSummary

Metadata

Per-implementation metadata (<StageId>.metadata.json).

Operation

The operation as a whole — its kind and the causal predecessors it assumes. The OpId is computed from this plus a sorted view of parents.

OperationRecord

An operation paired with its computed OpId and the resulting stage transition. This is what gets persisted under <root>/ops/<OpId>.json.

Plan

Result envelope returned by Store::plan.

PlanPath

One linear chain from goal to a leaf, with its total cost and the union of effects along it.

PublishOp

One applied operation within a PublishOutcome.

PublishOutcome

The outcome returned by Store::publish_program.

SessionBudget

Rollup of a single session’s budget spend.

Spec

A spec attached to a SigId (spec §4.4). Kept opaque here — the spec-checker (M10) interprets its body.

StageDelta

On-disk format of a delta-encoded stage.

StageHistoryEntry

One entry in the per-SigId stage history surfaced by Store::sig_history. Newest-first ordering is the responsibility of the producer.

Store

Test

A test attached to a SigId (spec §4.4).

Transition

Enums

OperationKind

The kinds of operations that produce stage transitions. Mirrors the initial set in #129; new kinds (MoveBetweenFiles, SplitFunction, ExtractType) can be added later as long as they’re appended at the end of this enum or use explicit #[serde(rename = "...")] tags so existing OpIds stay stable.

RetentionReason

Why an op survived a GC plan. Serialized as JSON in the lex op gc --dry-run envelope so reviewers can see the reasoning per op.

StageStatus

StageTransition

Effect of applying an operation on a stage’s content-addressed identity. Used as the produces field of an OperationRecord so consumers can answer “after this op, what’s the head stage for this SigId?” without rerunning the apply step.

StoreError

Constants

DEFAULT_BRANCH

DELTA_CHAIN_CAP

Maximum length of a delta chain. Past this, [encode] yields None so the caller writes a full snapshot. The cap is a pragmatic balance between disk savings and reconstruction cost — 32 keeps the worst-case get_ast at 32 file reads + 32 splices, which dominates over filesystem latency.

DELTA_RATIO_THRESHOLD

A new stage is delta-encoded when the middle (non-shared) bytes are at most this fraction of the new stage’s size. Below the threshold the delta is a clear win; above it, the metadata overhead and the indirection cost of reconstruction usually outweigh the byte savings.

Type Aliases

OpId

Identity of an operation. (kind, payload, parents) SHA-256 in lowercase hex (64 chars). Two operations with identical payloads and parent sets produce identical OpIds; the store dedupes on this.