feat: add content-addressed provider snapshots

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to Elume are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow
 semantic versioning once `0.1.0` ships; pre-alpha releases may break anything.
 
+## [Unreleased]
+
+### Added
+
+- Track 026 adds content-addressed provider snapshots:
+  `strategy_content_digest(...)`,
+  `serialize_strategies_content_addressed(...)`,
+  `deserialize_strategies_content_addressed(...)`, and
+  `snapshot_bytes(..., mode="content_addressed")`.
+- `InMemoryProvider.snapshot(mode="content_addressed")` now emits a stable
+  manifest/root-hash artifact, with optional manifest-only output via
+  `include_objects=False`.
+
+### Unchanged
+
+- `snapshot_bytes(strategies)` remains backward-compatible in default
+  `mode="full"`.
+- `InMemoryProvider.snapshot()` remains a full deterministic provider dump by
+  default.
+
 ## [0.3.0] — 2026-05-05 — Cognitive substrate recategorization + linoss-dynamics dependency edge
 
 v0.3.0 reframes Elume from "agentic memory engine" to its honest description:

README.md

@@ -53,8 +53,9 @@ Things that did not exist anywhere before this project:
 - **The deterministic envelope** (`elume.envelope`, v0.1) — a canonical
   pre-image (BLAKE2b-256) over operation inputs, RNG state, result, and
   provider snapshot, giving every cognitive op a byte-identical replay
-  contract. Five reference operations registered today (belief embed,
-  basin recall, thought competition, evolution step, self-model step).
+  contract. Six reference operations registered today (belief embed,
+  basin recall, thought competition, evolution step, self-model step,
+  curiosity score).
 - **The platform-tagged float-hash policy** — `platform_fingerprint()`
   folded into the canonical pre-image so cross-platform replay drift
   surfaces as a hash mismatch by construction, not silent agreement on
@@ -102,6 +103,7 @@ These components are integrated into a shared memory pipeline for agentic learni
 - **No framework lock-in** — no FastAPI, Graphiti, or agent runtime in the core. Adapters live in consumers.
 - **Cross-platform float-hash policy** — `platform_fingerprint()` is folded into the canonical hash pre-image. Cross-platform drift is a visible mismatch, not silent corruption.
 - **Curiosity-driven hyperevolution** — the optional curiosity homing signal biases memory retrieval toward entropy-reducing directions, turning uniform-random search into goal-directed exploration.
+- **Content-addressed replay artifacts** — provider snapshots can stay full dumps by default or emit a manifest/root-hash form for larger replay stores.
 
 ## MemEvolve cartridge
 
@@ -140,13 +142,13 @@ BibTeX entries for all upstream academic citations are in [`CITATIONS.bib`](./CI
 
 Elume is an open-source integration project under active development.
 
-Twenty-five tracks landed: kernel bootstrap, core data models, LinOSS solver + timing, Hopfield network, basin field engine, attractor basin core, embedder protocol, provider contracts, the evolution engine, the self-modeling network engine, immutable cognitive record types, immutable mental-model domain records, immutable metacognitive control records, prior hierarchy records, mental-model subnetworks, the cognitive event protocol, cognitive-event embedders, immutable thought-level records, immutable neuronal-packet records, deterministic thought competition, prior-gated cognition, the MemEvolve cartridge, curiosity homing device, and hyperevolution wiring. Track `007` was retired after source review showed it was framed against the wrong dionysus3 concept. **1177 tests passing, ruff clean.**
+Twenty-six tracks landed: kernel bootstrap, core data models, LinOSS solver + timing, Hopfield network, basin field engine, attractor basin core, embedder protocol, provider contracts, the evolution engine, the self-modeling network engine, immutable cognitive record types, immutable mental-model domain records, immutable metacognitive control records, prior hierarchy records, mental-model subnetworks, the cognitive event protocol, cognitive-event embedders, immutable thought-level records, immutable neuronal-packet records, deterministic thought competition, prior-gated cognition, the MemEvolve cartridge, curiosity homing device, hyperevolution wiring, and content-addressed provider snapshots. Track `007` was retired after source review showed it was framed against the wrong dionysus3 concept. **1194 tests passing, ruff clean.**
 
 Phase 2 is complete through the prior gate: `Track 011` shipped `elume.network`, `Tracks 014`, `016`, `018`, `021`, and `022` landed the minimal cognition gate from `MentalModel` through `LinOSSEncoder`, `Tracks 012`, `013`, and `019` landed immutable thought and packet records plus deterministic EFE competition, and `Tracks 015`, `017`, and `020` landed metacognitive control, generic priors, and prior-gated cognition. See [`conductor/tracks.md`](./conductor/tracks.md).
 
-Phase 3 is complete: the MemEvolve cartridge (`elume.adapters.memevolve`), curiosity homing (`elume.cognition.curiosity`), and hyperevolution wiring now connect Elume's deterministic substrate to MemEvolve's outer evolutionary loop.
+Phase 3 is complete: the MemEvolve cartridge (`elume.adapters.memevolve`), curiosity homing (`elume.cognition.curiosity`), and hyperevolution wiring now connect Elume's deterministic substrate to MemEvolve's outer evolutionary loop. Phase 4 has started with content-addressed provider snapshots for larger replay artifacts.
 
-Archon-style deterministic-harness adoption is complete for v0.1.0. The kernel has injected RNGs, frozen trajectory metadata, provider snapshots, and an `elume.envelope` v0 operation registry covering belief embedding, evolution step, thought competition, self-model stepping, Hopfield recall, and (v0.2.0) curiosity scoring. Cross-platform float-hash policy is documented in `docs/archon-readiness/21-float-hash-policy.md`.
+Archon-style deterministic-harness adoption is complete for v0.1.0. The kernel has injected RNGs, frozen trajectory metadata, provider snapshots, content-addressed snapshot manifests, and an `elume.envelope` v0 operation registry covering belief embedding, evolution step, thought competition, self-model stepping, Hopfield recall, and (v0.2.0) curiosity scoring. Cross-platform float-hash policy is documented in `docs/archon-readiness/21-float-hash-policy.md`.
 
 ## Install
 

conductor/tracks.md

@@ -54,6 +54,10 @@ The fleets are **parallelizable** where dependencies allow — Fleet A and Fleet
 - [x] **Track 024: Curiosity Homing Device — `elume.cognition.curiosity`** — [./tracks/024-curiosity-homing/](./tracks/024-curiosity-homing/)
 - [x] **Track 025: Hyperevolution Wiring** — [./tracks/025-hyperevolution-wiring/](./tracks/025-hyperevolution-wiring/)
 
+### Phase 4 — Replay Artifact Scale
+
+- [x] **Track 026: Content-addressed provider snapshots** — [./tracks/026-content-addressed-snapshots/](./tracks/026-content-addressed-snapshots/)
+
 ### Downstream (dionysus3-side — not in this repo)
 
 - Dionysus3 consumes Elume via `pip install -e ../elume`. The dionysus3 adapter layer (routing, classification, Graphiti persistence, event bus, PSM/SMT enrichment) stays in dionysus3 and gets its own tracks in that repo's conductor.
@@ -87,6 +91,7 @@ The fleets are **parallelizable** where dependencies allow — Fleet A and Fleet
 | 023 | B | MemEvolve Cartridge | done | A2/A3/A4 | bingreeky/MemEvolve `dionysus_memory_provider.py`, `entity_extractor.py` (port, HTTP/HMAC stripped) | `elume/adapters/memevolve/` | **84 tests passing**; 2 seeded runs → byte-equal `MemoryResponse` | 002, 004, 006, 008, 009, 010 |
 | 024 | B | Curiosity Homing Device | done | A1 | dionysus3 `mosaeic_self_discovery.py:300-443`, `arousal_system_service.py:44-143` (port, FastAPI/Pydantic stripped) | `elume/cognition/curiosity.py`, `elume/envelope/ops/curiosity_score.py` | **42 tests passing**; entropy ordering, prior threshold tests, envelope replay, prior-gating integration | 017, 019, 020 |
 | 025 | B | Hyperevolution Wiring | done | A5 | — (net new) | `elume/adapters/memevolve/provider.py` (extend) | **5 integration tests passing**; curiosity=False and curiosity=True both deterministic; curiosity changes retrieval order and preserves fixture outcome metric | 023, 024 |
+| 026 | B | Content-addressed provider snapshots | done | — | — (net new) | `elume/envelope/snapshot.py`, `elume/providers/in_memory.py` | **17 new tests passing**; full snapshot compatibility plus content-addressed manifest/root/store tests | 010, envelope v0 |
 
 ## Phase 2 Stage 0 preflight findings
 

conductor/tracks/026-content-addressed-snapshots/plan.md

@@ -0,0 +1,52 @@
+# Track 026 Plan — Content-Addressed Provider Snapshots
+
+**Status:** Complete. Focused verification:
+`.venv/bin/pytest tests/unit/envelope/test_snapshot.py tests/contract/test_provider_contract.py -q`
+reported `63 passed`. Full verification:
+`.venv/bin/pytest -q` reported `1194 passed`; ruff was clean.
+
+## Implementation steps
+
+### Spec and compatibility guard
+
+- [x] Add Track 026 Conductor spec and plan.
+- [x] Add regression tests proving `snapshot_bytes(strategies)` default output
+  is unchanged.
+
+### Content-addressed snapshot helpers
+
+- [x] Add `strategy_content_digest(...)`.
+- [x] Add `serialize_strategies_content_addressed(...)` with:
+  - sorted `{name, digest}` manifest entries;
+  - `root_hash` over the stable manifest;
+  - optional embedded object payloads keyed by digest.
+- [x] Add `deserialize_strategies_content_addressed(...)` supporting embedded
+  objects and caller-provided object stores.
+- [x] Reject missing or tampered objects during restore.
+
+### Provider surface
+
+- [x] Extend `MemoryProvider.snapshot(...)` documentation/signature with an
+  optional mode.
+- [x] Extend `InMemoryProvider.snapshot(...)` to support
+  `mode="content_addressed"` while keeping `mode="full"` as default.
+
+### Verification
+
+- [x] Run focused tests:
+
+```bash
+.venv/bin/pytest tests/unit/envelope/test_snapshot.py tests/contract/test_provider_contract.py -q
+```
+
+- [x] Run lint:
+
+```bash
+.venv/bin/ruff check src tests reference_service/src
+```
+
+- [x] Run full suite:
+
+```bash
+.venv/bin/pytest -q
+```

conductor/tracks/026-content-addressed-snapshots/spec.md

@@ -0,0 +1,55 @@
+# Track 026: Content-Addressed Provider Snapshots
+
+## Objective
+
+Add a compact, content-addressed provider snapshot mode for replay artifacts
+without changing the existing full snapshot behavior. The current full dump is
+correct and deterministic; this track gives envelope consumers a Merkle-style
+manifest they can store separately from the strategy objects when populations
+become large.
+
+## Background
+
+The Archon envelope v0 deliberately shipped full provider snapshots because
+that was the simplest deterministic replay surface. The post-phase plan left
+one scale question open: whether provider snapshots should stay full dumps or
+gain a Merkle-root/content-addressed reference mode for large artifacts.
+
+## In Scope
+
+- `src/elume/envelope/snapshot.py`
+  - Keep `serialize_strategies(...)`, `deserialize_strategies(...)`, and
+    default `snapshot_bytes(...)` behavior backward-compatible.
+  - Add a content-addressed strategy population snapshot with stable leaf
+    digests and a stable population root hash.
+  - Support embedded objects for self-contained artifacts.
+  - Support manifest-only snapshots that can be restored with an external
+    object store.
+  - Validate object digests during restore.
+- `src/elume/providers/in_memory.py`
+  - Expose the new mode through `snapshot(mode="content_addressed")`.
+- `src/elume/providers/contracts.py`
+  - Document the optional snapshot mode without requiring existing callers to
+    change.
+- Unit/contract tests for determinism, digest sensitivity, embedded restore,
+  external-store restore, and tamper detection.
+
+## Out of Scope
+
+- Disk-backed or remote content-addressed storage.
+- Chunking non-strategy provider state such as basins or trajectories.
+- Changing the envelope hash pre-image.
+- Making content-addressed snapshots the default.
+
+## Acceptance
+
+- Existing full snapshot tests continue to pass unchanged.
+- Content-addressed snapshots are insertion-order stable.
+- The same strategy has the same object digest across populations.
+- Root hash changes when strategy content changes.
+- Manifest-only snapshots omit object payloads and can restore with a provided
+  object store.
+- Tampered embedded or external objects fail restore.
+- `snapshot_bytes(strategies)` remains byte-for-byte compatible in default mode.
+- `ruff check src tests reference_service/src` is clean.
+- Focused snapshot/provider tests pass.

docs/archon-readiness/00-summary.md

@@ -8,13 +8,13 @@
 landed, the envelope registry covers the five candidate operations from report
 `19` plus curiosity scoring, the cross-platform float-hash policy is documented
 in [`21-float-hash-policy.md`](./21-float-hash-policy.md) and folded into the
-canonical hash pre-image, and the current suite reports `1177 passed`.
+canonical hash pre-image, Track `026` adds content-addressed provider snapshot
+manifests, and the current suite reports `1194 passed`.
 
 **2026-05-05 reconciliation:** The blocker list below is historical audit
 context. Hopfield RNG injection, timestamp injection, trajectory metadata
-freezing, provider snapshots, float-hash policy, and envelope replay coverage
-have all landed. Remaining design work is limited to future provider-snapshot
-granularity if artifact size forces a Merkle/content-addressed variant.
+freezing, provider snapshots, float-hash policy, envelope replay coverage, and
+content-addressed provider snapshot manifests have all landed.
 
 ## Verdict
 

docs/plans/archon-adoption-phase-1.md

@@ -6,13 +6,13 @@
 
 **Post-plan update:** Tracks `017`, `020`, `023`, `024`, and `025` have landed,
 six reference envelope operations are registered, the reference demo is
-runnable, `EnvelopeOutput` records the live platform fingerprint, and the
-current verification baseline is `1177 passed`.
+runnable, `EnvelopeOutput` records the live platform fingerprint, Track `026`
+adds content-addressed provider snapshot manifests, and the current
+verification baseline is `1194 passed`.
 
 **2026-05-05 reconciliation:** This plan is now historical. The only remaining
-design item from the original open list is provider-snapshot granularity
-(full dump vs. Merkle/content-addressed reference) if artifact size becomes a
-problem.
+design item from the original open list, provider-snapshot granularity, is now
+resolved at v0 by Track `026` with an optional content-addressed manifest mode.
 
 ## 1. Objective
 
@@ -48,7 +48,7 @@ All 20 lanes are confined to their audit-designated write scope per the fleet-ow
 ## 3. Scope (out)
 
 - **Resolved:** `Track 017`, `Track 020`, the formal envelope operations, and cross-platform float-hash policy have landed.
-- **Still out of scope:** provider snapshot granularity beyond the current full deterministic dump. A Merkle/content-addressed snapshot can be added later if artifact size becomes a real constraint.
+- **Resolved:** provider snapshot granularity now has an optional content-addressed manifest mode in Track `026`; the full deterministic dump remains the default.
 - No changes to `pyproject.toml`, top-level `src/elume/__init__.py`, or `conductor/tracks.md` beyond what the lead pod merges at phase close.
 
 ## 4. Verification gates
@@ -71,4 +71,4 @@ After all 20 lanes merge into the integration branch:
 ## 6. Post-phase next steps (require user approval)
 
 - Resolved: Tracks `017`, `020`, `023`, `024`, and `025`; formal envelope ops; platform-tagged float-hash policy; `EnvelopeOutput.platform_fingerprint`.
-- Optional future work: decide whether `provider_snapshot` should stay a full deterministic dump or gain a Merkle-root/content-addressed mode for large artifacts.
+- Resolved: Track `026` keeps full provider snapshots as default and adds a Merkle-style content-addressed mode for large artifacts.

docs/plans/phase-2-handoff.md

@@ -6,8 +6,8 @@
 This document is the resume point for Phase 2 work if session context is cleared.
 
 **Post-handoff update:** Stage 4 and Phase 3 are complete. Tracks `015`,
-`017`, `020`, `023`, `024`, and `025` have landed, and the current suite
-reports `1177 passed` with ruff clean.
+`017`, `020`, `023`, `024`, `025`, and `026` have landed, and the current
+suite reports `1194 passed` with ruff clean.
 
 ## Current Status
 
@@ -29,7 +29,7 @@ reports `1177 passed` with ruff clean.
   - `Track 012` shipped immutable thought-level records in `src/elume/models/thought.py`.
   - `Track 013` shipped immutable packet records plus pure intrinsic-value computation in `src/elume/models/neural.py`.
   - `Track 019` shipped deterministic EFE competition in `src/elume/cognition/competition.py`.
-  - Full suite status at updated handoff: **`1177 passed`**
+  - Full suite status at updated handoff: **`1194 passed`**
   - Lint status at updated handoff: **`ruff check src tests reference_service/src` clean**
 
 - **Stage 4 complete.**
@@ -42,6 +42,9 @@ reports `1177 passed` with ruff clean.
   - `Track 024` shipped curiosity homing in `src/elume/cognition/curiosity.py` and `src/elume/envelope/ops/curiosity_score.py`.
   - `Track 025` shipped hyperevolution wiring inside `src/elume/adapters/memevolve/provider.py`.
 
+- **Phase 4 replay artifact scale started.**
+  - `Track 026` shipped content-addressed provider snapshots in `src/elume/envelope/snapshot.py` and `src/elume/providers/in_memory.py`.
+
 ## Key Documents
 
 - Original proposal: [phase-2-proposal.md](/Volumes/Asylum/dev/elume/docs/plans/phase-2-proposal.md)