Module lock_lifecycle 

Substrate-wide LockLifecyclePrimitive trait.

The deterministic-lock pattern (transient build artifacts + explicit operator snapshots + typed diffs) generalizes across every package-manager adapter. cargo today, npm/bundler/poetry/ gomod/helm tomorrow. This trait is the typed contract: implement these methods, get the gen lock CLI surface + substrate refusal-on-drift gating for free.

Required substrate-side guarantees

An implementor promises:

1. State is a closed typed enum with at least the canonical four states — Unlocked / Locked / Drifted / MissingLock. Concrete adapters may add more (e.g. gen-npm might add WorkspaceProtocolMismatch). The state IS observable from filesystem alone (no daemons, no network, no cached state).

2. LockDiff is a structured value type (not text). Two consecutive update calls with no Cargo.lock/package-lock.json movement between produce byte-equal diffs.

3. current_state is pure — same filesystem state → same output. Idempotent and deterministic.

4. snapshot / update / reset are explicit operator verbs — they NEVER fire as a side-effect of current_state or any other read.

Trait-boundary testing

Each implementation provides a parallel mock impl (e.g. MockCargoLifecycle for tests) that lets gen-cli’s dispatcher exercise every state transition hermetically — same shape as PathDepResolver + MetadataSource already use.

Enums

LockError

Typed errors emitted by any LockLifecyclePrimitive. Adapters that need richer context wrap their domain errors in Source.

Traits

LockLifecyclePrimitive

Typed lock-lifecycle primitive — one impl per adapter.