AbstractRuntime 0.14.0__tar.gz → 0.15.0__tar.gz

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-28
+
+Requires AbstractMemory 0.4.0 or newer (`abstractmemory.graph`). ADR 0011, backlog 0856.
+
+### Upgrade notes (one-way)
+
+- AbstractMemory 0.4.0 rewrites a SQLite home's JSON-text vectors as float32 BLOBs on first write; a 0.3.x reader then
+  finds no vectors (zero semantic hits, no error). Every process sharing a home or a plane moves to AbstractMemory 0.4.0
+  (and so AbstractRuntime 0.15.0) together. See the AbstractMemory 0.4.0 changelog.
+- The JSON-file ledger writes a `ledger_<run_id>.idx` row index beside each ledger; older readers ignore it, and a
+  missing or stale index is rebuilt from the ledger.
+
+### Added
+
+- **Ledger row address** (on 0.14.0's per-run `seq`, ADR 0010): `LedgerStore.get_record(run_id, seq)` returns one
+  record ready to read (a terminal row's `$slim` markers resolved against its STARTED row, offloaded leaves
+  rehydrated); `find_started_record(run_id, step_id, before_seq=)`. SQLite reads by primary key; the JSON-file backend
+  keeps a per-run line-offset index and checks the seq persisted on the line, so a point read is a seek and one line
+  parse (0.05 ms at 10,000 rows instead of a 58 ms full parse), and a rewritten file is read by persisted seq, never
+  by position.
+- **Step context**: an effect handler reads its own step with
+  `abstractruntime.core.step_context.current_step_context(run.run_id)`: `run_id`, `step_id`, `seq` of the attempt's
+  STARTED row, `node_id`, `attempt`, `effect_type`. Out of band like the progress callback; `None` outside a runtime
+  step; a nested runtime shadows it.
+- **Memory facade** (`abstractruntime.integrations.abstractmemory.memory_facade`): `MemoryFacade` (`open_mind`, `stamp`,
+  `stamp_current_step`, `reconstruct_source`, `history`, `sources_of`, `derived_from_source`, `apply_revision`),
+  `is_real_run`, and the AbstractMemory names hosts use re-exported unchanged (`GATEWAY_NAMES`). Hosts no longer import
+  `abstractmemory`. `reconstruct_source` answers `ok`, `source_gone` or `unsupported`, never raises for a missing
+  source. See [AbstractMemory integration](docs/integrations/abstractmemory.md).
+- **Provenance stamping**: `MEMORY_FORM`, `MEMORY_KG_ASSERT` and the `DIARY_WRITE` graph projection add a `sources`
+  list to the provenance they write: the `step` ref `(run_id, seq, step_id)` of the writing effect, an `artifact` ref
+  for the verbatim / `span_id`, a `diary_entry` ref for a projection. The legacy flat keys stay. A synthetic run id
+  (`chat-<session_id>`, `diary:<entity_id>`, ...) is never a `run`/`step` ref: the home-direct chat path carries
+  artifact or diary-entry refs only.
+- **`MEMORY_REVISE`** (`EffectType.MEMORY_REVISE`, VisualFlow node `memory_revise`): one revision of a mind (assert /
+  close / narrow ops) applied atomically through `MemoryGraph.apply_revision` as a workflow step, its provenance
+  stamped with the step that applied it. Handler from `build_memory_kg_effect_handlers` (new optional `journal=`); a
+  store that is not a graph home answers a failed outcome naming AbstractMemory backlog 0057; an ungrounded revision
+  fails with `ProvenanceRequired`.
+
+- **Source integrity** (architect pass): every ref the runtime stamps carries a `digest` (step: sha256 of the STARTED
+  record as written, also on the step context; artifact: the sha256 of its bytes; diary entry: the chain
+  `record_hash`), and `reconstruct_source` verifies it: new statuses `mismatch` (the bytes changed since the memory
+  named them) and `partial` (a `$slim` marker or an `{"$artifact": id}` leaf whose artifact is gone or uncheckable;
+  never `ok` with a hole). A step ref resolves only to its STARTED row (a rewritten JSON-file ledger answers
+  `source_gone`, never another row).
+- **Owner partitions**: `MEMORY_REVISE` and `MEMORY_KG_ASSERT` write only the run's own owners (its run, its session,
+  the global owner); `MEMORY_REVISE` refuses `recorded_at` (record time is the store's); a replayed revision reports
+  the memory's sources, not the retry's step.
+- **Persisted JSON-file row index** (`ledger_<run_id>.idx` beside the ledger): a fresh process reads a 100,000-row
+  ledger's row in 39 ms instead of 320 ms.
+
+### Changed
+
+- `AbstractMemory>=0.4.0` (was `>=0.3.2`).
+- SQLite `find_started_record` reads newest-first with `LIMIT 1` (0.01 ms at 10,000 rows instead of 3.5 ms).
+
 ## [0.14.0] - 2026-10-27
 
 Two features: the replay view with a durable per-run ledger cursor, and the session tool policy.

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.14.0
+Version: 0.15.0
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: abstractcore>=2.30.0
-Requires-Dist: abstractmemory>=0.3.2
+Requires-Dist: abstractmemory>=0.4.0
 Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.1
 Requires-Dist: httpx<1.0.0,>=0.28.1
@@ -55,10 +55,25 @@ Description-Content-Type: text/markdown
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.14.0 • **Python:** 3.10+
+**Version:** 0.15.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.15.0
+
+- **Memory facade** (`abstractruntime.integrations.abstractmemory.memory_facade.MemoryFacade`): the one
+  host surface for AbstractMemory 0.4.0's memory graph (open a mind, stamp provenance, reconstruct a
+  source, history, revisions); hosts no longer import `abstractmemory`. ADR 0011. See
+  [docs/integrations/abstractmemory.md](docs/integrations/abstractmemory.md).
+- **`MEMORY_REVISE`** effect and `memory_revise` VisualFlow node: one atomic revision of a mind
+  (assert / close / narrow) as a workflow step, stamped with the step that applied it.
+- **Ledger provenance**: `LedgerStore.get_record(run_id, seq)` point reads, a step context for
+  effect handlers, and a digested `step` / `artifact` / `diary_entry` source ref on every memory
+  write the runtime performs (`reconstruct_source` answers `ok`, `partial`, `mismatch`,
+  `source_gone` or `unsupported`).
+- Upgrade note: requires AbstractMemory 0.4.0, whose vector re-encoding is one-way; move every
+  process sharing a memory home together.
+
 ## What's new in 0.14.0
 
 - **Replay view** (`abstractruntime.replay`): one deterministic reducer turns a run tree's ledger

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/README.md

@@ -4,10 +4,25 @@
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.14.0 • **Python:** 3.10+
+**Version:** 0.15.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.15.0
+
+- **Memory facade** (`abstractruntime.integrations.abstractmemory.memory_facade.MemoryFacade`): the one
+  host surface for AbstractMemory 0.4.0's memory graph (open a mind, stamp provenance, reconstruct a
+  source, history, revisions); hosts no longer import `abstractmemory`. ADR 0011. See
+  [docs/integrations/abstractmemory.md](docs/integrations/abstractmemory.md).
+- **`MEMORY_REVISE`** effect and `memory_revise` VisualFlow node: one atomic revision of a mind
+  (assert / close / narrow) as a workflow step, stamped with the step that applied it.
+- **Ledger provenance**: `LedgerStore.get_record(run_id, seq)` point reads, a step context for
+  effect handlers, and a digested `step` / `artifact` / `diary_entry` source ref on every memory
+  write the runtime performs (`reconstruct_source` answers `ok`, `partial`, `mismatch`,
+  `source_gone` or `unsupported`).
+- Upgrade note: requires AbstractMemory 0.4.0, whose vector re-encoding is one-way; move every
+  process sharing a memory home together.
+
 ## What's new in 0.14.0
 
 - **Replay view** (`abstractruntime.replay`): one deterministic reducer turns a run tree's ledger

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/docs/README.md

@@ -27,6 +27,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `manual_testing.md` — manual smoke tests and how to run the test suite
 - `artifacts.md` — Runtime artifact identity, descriptors, provenance, catalog search, and access stats
 - `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, the `config_facade` models/engines/host-jobs passthroughs for hosts, the `structured_facade` response_format check for hosts, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings, locks and model switching, live token streaming, workspace-scoped tools, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
+- `integrations/abstractmemory.md` — the AbstractMemory memory facade (ADR 0011): open a mind, stamp provenance from the step context, reconstruct a source from the ledger (`get_record`), history and revisions, and the `MEMORY_REVISE` effect / `memory_revise` node
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
 - `email.md` — email for each user: run-scoped account binding and the host resolver, sending without asking (self and pre-authorised recipients), the durable event inbox and mail feeder, the `email.received@1` trigger on the primary or any other mailbox of the user, mail verbs for flows (changes and sends only on a Read and write mailbox: `email_mailbox_read_only`, `email_mailbox_cannot_send`), and the send-email action
 - `tool-approval.md` — tool risk tiers, the run-policy rank ceiling, the session tool policy (a conversation's standing approve/deny, applied before any approval wait), and per-call refiners (the `send_email` recipient rule: self and pre-authorised recipients)

abstractruntime-0.15.0/docs/adr/0011_memory_facade_is_the_complete_host_surface_for_abstractmemory.md

@@ -0,0 +1,131 @@
+# ADR 0011: The memory facade is the complete host surface for AbstractMemory
+
+Status: Accepted.
+Date: 2026-10-27
+
+## Context
+
+AbstractMemory ADR 0003 (one semantic temporal graph, every memory tied to the ledger, every change a revision)
+rules that every memory a mind holds names the ledger sources it came from, and that the verbatim of any source can
+be reconstructed. AbstractMemory returns references; it never reads a ledger. The ledger, the artifacts, the diary
+chain and the event inbox belong to this package, so two jobs land here:
+
+- **Stamping.** The runtime performs memory writes for hosts (`MEMORY_FORM`, `MEMORY_KG_ASSERT`, the `DIARY_WRITE`
+  projection). The audit of 2026-10-27 (`abstractframework/untracked/memory-transition/audit/abstractruntime_entity.md`)
+  found that none of them wrote a ledger row address: they wrote `run_id`/`turn_id` (`writer_run_id` on the KG lane),
+  and on the home-direct entity path the `run_id` is a synthetic `chat-<session_id>` that no store can load. The
+  handlers could not do better: an effect handler received `(run, effect, default_next_node)` and nothing told it
+  which ledger row its own step had.
+- **Reconstruction.** The only addressable ledger unit is `(run_id, seq)` (`step_id` is shared by a STARTED row and
+  its terminal row). `LedgerStore` had no read by address, `list()` did not return `seq`, terminal rows hold `$slim`
+  markers instead of payload bytes the STARTED row already holds, and oversized leaves may be offloaded to the
+  artifact store. Runs, ledgers, artifacts and inbox payloads are deletable.
+
+And one boundary: ADR 0008 decision 2 already names AbstractMemory as a package a host must not import, yet no
+AbstractMemory facade existed, so AbstractGateway imports `abstractmemory` directly (34 lines across 8 files in the
+audit). The hole is the same as the one ADR 0008 closed for AbstractCore: a facade that lags what hosts need, with
+no rule saying whose job it is to close the gap.
+
+## Decision
+
+1. **One host surface.** `abstractruntime.integrations.abstractmemory.memory_facade` (`MemoryFacade`) and the existing
+   effect-handler builders of `abstractruntime.integrations.abstractmemory` (`build_memory_kg_effect_handlers`,
+   `build_memory_seam_effect_handlers`, `build_entity_brain_effect_handlers`) are the ONLY surface through which a
+   host reaches AbstractMemory. The facade opens a mind (`MemoryFacade.open_mind(path)`: the SQLite triple store,
+   journal and `abstractmemory.graph.MemoryGraph` of one home), exposes the graph reads (`history`, `sources_of`,
+   `derived_from_source`), stamps provenance (`stamp`) and reconstructs sources (`reconstruct_source`). It is
+   complete by contract: a name or capability a host needs and cannot reach through it is a runtime defect, fixed by
+   adding it here and cutting a patch release. A host never imports `abstractmemory` to work around a gap (ADR 0008
+   decision 2 applies unchanged).
+2. **The ledger row address is `(run_id, seq)`.** `LedgerStore.get_record(run_id, seq)` returns one record with its
+   `$slim` markers resolved against the STARTED row of the same `step_id` and, under `OffloadingLedgerStore`, its
+   offloaded `{"$artifact": id}` leaves rehydrated; `list(run_id)` records carry `"seq"`. `seq` is the per-run
+   record number of ADR 0010 (runtime 0.14.0): SQLite's key, persisted on each JSON-file line (lines written before
+   it read as their position), excluded from the hash chain. `append()` returns the seq of the row it wrote.
+3. **The runtime stamps every memory write it performs.** The runtime publishes the current step to the handler it is
+   executing (`abstractruntime.core.step_context`: `run_id`, `seq` of the step's STARTED row, `step_id`, `node_id`,
+   `attempt`, `effect_type`). The memory writers stamp through `MemoryFacade.stamp`: a `step` ref `(run_id, seq,
+   step_id)` for the writing effect, an `artifact` ref for each verbatim artifact (`payload_ref`, `span_id`), a
+   `diary_entry` ref for a diary projection. The new `sources` list is additive; the legacy flat keys (`run_id`,
+   `turn_id`, `writer_run_id`, ...) stay so existing readers keep working.
+4. **A synthetic run id is never a source.** A run id that no store can load (`chat-<sid>`, `diary:<eid>` used as a
+   run, `global_memory`) is never stamped as a `run` or `step` ref; a `seq` is never guessed. When the runtime cannot
+   name a ledger source, the stamp carries what is real (an artifact, a diary entry) or nothing new, and the graph
+   write path (`MemoryGraph.apply_revision`, `ProvenanceRequired`) refuses an ungrounded write. That refusal is the
+   intended outcome; fabricating a ref to pass it is a defect.
+5. **Reconstruction never raises for a missing source.** `MemoryFacade.reconstruct_source(ref)` answers
+   `{"status": "ok", "kind", "content", "metadata"}`, `{"status": "source_gone", "reason"}` when the run, ledger row,
+   artifact, diary entry or event no longer exists, or `{"status": "unsupported", "reason"}` for a kind the host did
+   not give the facade a store for (or one with no indexed path, `message` today).
+6. **The facade is additive within a minor line**, like ADR 0008 decision 4: a name, once exported, is not removed
+   without a deprecation note and a major or minor bump.
+
+## Consequences
+
+### Positive
+- Every memory the runtime forms in a real run can be traced to the exact ledger row (and artifact) it came from,
+  and that row reads back verbatim with one call.
+- A host's import-boundary test for AbstractMemory becomes a true gate, as it is for AbstractCore.
+- Deleted sources are a typed answer, so a reader can say "the source of this memory is gone" instead of failing.
+
+### Negative
+- The facade needs AbstractMemory's graph package (`abstractmemory.graph`, AbstractMemory 0.4.0) for `open_mind`,
+  `stamp` and the graph reads; the memory writers stamp through it, so the runtime's AbstractMemory floor moves to
+  0.4.0 with the release that carries this ADR. `get_record` and the reconstruction of steps and artifacts need no
+  AbstractMemory at all.
+- Memory written on the home-direct entity path (synthetic `chat-<sid>` runs) carries artifact refs only until that
+  path runs as real runs; derived writes outside any effect (world models, tending, the night passes) carry no
+  ledger source until backlog 0857 lands.
+
+### Neutral
+- `seq` is ADR 0010's per-run record number (persisted on JSON-file lines, excluded from hashes); the diary chain and
+  the record digests a memory stamps exclude it.
+- The step context is out of band (a `ContextVar`, like the progress callback): effect payloads stay JSON and a
+  handler called directly, outside a runtime step, sees no step.
+
+### Open decisions (operator)
+- **Durability of a JSON-file row address: decided, option (a).** Of the two options (a) persist `seq` inside each
+  JSON-file record at append, (b) SQLite plane ledgers, runtime 0.14.0 shipped (a) with ADR 0010 (the per-run `seq`
+  is the durable cursor, persisted on each JSONL line under a file lock, excluded from the hash chain; lines written
+  before it read as their position). The row address therefore survives a rewrite: `get_record` and the JSON-file
+  row index find a record by its persisted `seq` (never by line position), and a step ref whose row was dropped
+  answers `source_gone`.
+- **Memory ownership.** `owner_id` is a partition string derived from the run (`run`: the run id, `session`:
+  `session_memory_<sid>`, `global`: the plane's global owner). The runtime refuses a payload `owner_id` the run does
+  not derive, but a session id is still caller-chosen upstream. The full fix (owner = the principal, scope = the
+  kind of memory) is an operator decision (AbstractMemory ADR 0003 decisions 2/13 as amended).
+
+## Enforcement
+- Code review: a runtime memory write site that does not stamp through `MemoryFacade.stamp`, or that builds a
+  `run`/`step` ref from a run id it cannot load or a seq it did not get from the step context, is rejected.
+- A host need that the facade does not cover becomes a runtime backlog item or PR before the host ships; the host's
+  changelog names the runtime version that closes it.
+- The kernel import boundary (`tests/test_runtime_install_boundary.py`) stays green: AbstractMemory is imported
+  lazily, inside functions, everywhere in this package, the facade included; the facade imports no AbstractCore.
+- AbstractGateway burns its direct `abstractmemory` imports down onto this facade (its boundary test, never an
+  exemption for a name the facade could carry).
+
+## Validation
+- `tests/test_ledger_get_record.py`: `get_record` on the SQLite and JSON-file backends (and under
+  `OffloadingLedgerStore`) returns the terminal row of a slimmed step with its payload rebuilt from the STARTED row;
+  `list()` carries `seq`; the diary hash chain still verifies.
+- `tests/test_memory_facade.py`: `reconstruct_source` for a step whose terminal row was slimmed, an artifact, a
+  deleted artifact (`source_gone`), a run, a diary entry, an event, a message (`unsupported`); `stamp` adds a step
+  ref for a real run and none for a synthetic one; facade re-exports keep identity.
+- `tests/test_memory_step_provenance.py`: an episode formed by `MEMORY_FORM` in a real run carries a `step` ref whose
+  `(run_id, seq)` resolves through `get_record` to that `MEMORY_FORM` step; a diary projection carries a
+  `diary_entry` ref; the synthetic chat path carries artifact refs only; `MEMORY_KG_ASSERT` carries the step ref.
+
+## Backlog links
+- Implementation: [0856](../backlog/completed/0856_memory_facade_and_ledger_provenance.md) (memory facade, ledger row
+  address, step context, stamping).
+- Follow-up: [0857](../backlog/planned/0857_entity_direct_memory_writes_provenance.md) (entity writes outside any
+  effect: world models, tending, the night passes).
+- AbstractMemory backlog 0056 (`abstractmemory.graph`: `SourceRef`, `Provenance`, `MemoryGraph`).
+
+## Related
+- ADR 0003 (tamper-evident hash chain: `seq` is excluded from the record hash), ADR 0008 (integration facades are the
+  complete host surface; this ADR is its AbstractMemory counterpart).
+- AbstractMemory ADR 0002 (AbstractMemory owns the graph), ADR 0003 (one graph, ledger provenance, revisions).
+- Root ADR 0007 (active context vs stored memory), ADR 0011 (`span_id` = `artifact_id`).
+- AbstractGateway ADR 0001 (lower-level access through runtime facades).

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/docs/adr/README.md

@@ -22,6 +22,7 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 0007 | [Runtime Relays Core-Owned Model Residency Truth](0007_runtime_relays_core_owned_model_residency_truth.md) | Accepted | 2026-05-21 | Runtime reports loaded state only from AbstractCore residency truth |
 | 0008 | [Integration Facades Are the Complete Host Surface](0008_integration_facades_are_the_complete_host_surface.md) | Accepted | 2026-10-27 | Every AbstractCore name or capability a host needs is surfaced by the runtime (facade re-export, typed refusal, backlog); a gap is a runtime patch, never a host import of a lower-level package |
 | 0010 | [One Replay of the Ledger, Many Views](0010_one_replay_many_views.md) | Accepted | 2026-10-27 | `abstractruntime.replay` is the only reconstruction of run state from the ledger; hosts serve its view, clients render it; the per-run ledger `seq` is the durable cursor |
+| 0011 | [The Memory Facade Is the Complete Host Surface for AbstractMemory](0011_memory_facade_is_the_complete_host_surface_for_abstractmemory.md) | Accepted | 2026-10-27 | Hosts reach AbstractMemory only through `memory_facade` and the effect-handler builders; the runtime stamps ledger provenance (step `(run_id, seq)`, artifact, diary entry) on every memory write it performs, never from a synthetic run id; reconstructing a deleted source answers `source_gone`, never raises |
 
 ## Relationship to Backlog
 
@@ -38,6 +39,7 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 0007 | `backlog/completed/0035_model_residency_provider_truth_for_local_http_clients.md`, `backlog/proposed/0036_local_media_residency_bridge_to_core_residency.md` |
 | 0008 | AbstractGateway backlog 1044 (mailbox access) and `tests/test_gateway_import_boundary.py`; runtime 0.13.1 `email_facade.resolve_srv_default` |
 | 0010 | `backlog/planned/0854_replay_view.md`; AbstractGateway backlog 0943 (view routes), 0082 (durable cursor); framework root 0993 |
+| 0011 | `backlog/completed/0856_memory_facade_and_ledger_provenance.md`, `backlog/planned/0857_entity_direct_memory_writes_provenance.md`; AbstractMemory backlog 0056 |
 
 ## Adding New ADRs
 

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/docs/api.md

@@ -435,7 +435,28 @@ Docs: `integrations/abstractcore.md`.
 
 Implementation: `src/abstractruntime/integrations/abstractmemory/effect_handlers.py`.
 
-This provides handlers for `MEMORY_KG_*` effects (opt-in wiring layer).
+This provides handlers for `MEMORY_KG_*` effects and `MEMORY_REVISE` (opt-in wiring layer):
+`build_memory_kg_effect_handlers(store=, run_store=, now_iso=, journal=None)`. `MEMORY_REVISE` applies one revision of
+a mind (assert / close / narrow ops) through `abstractmemory.graph.MemoryGraph`, stamped with the step that applied it;
+VisualFlow node type `memory_revise`. Payload and result: [MEMORY_REVISE](integrations/abstractmemory.md#memory_revise-memory-reconsideration-as-a-workflow-step).
+
+### AbstractMemory facade (host surface)
+
+`abstractruntime.integrations.abstractmemory.memory_facade` is the only way a host reaches AbstractMemory (ADR 0011;
+AbstractMemory 0.4.0+):
+
+- `MemoryFacade.open_mind(path, *, embedder=None, **stores)`; `MemoryFacade(graph=, ledger_store=, run_store=,
+  artifact_store=, diary_store=, event_inbox=, runtime_id=)`; `.graph`, `.store`, `.journal`
+- `stamp(provenance, *, run_id, seq=None, step_id=None, artifact_ids=(), runtime_id=None) -> dict` and
+  `stamp_current_step(provenance, *, run_id, artifact_ids=())`: add `step` / `run` / `artifact` SourceRefs, never for a
+  synthetic run id (`is_real_run`), never a guessed seq
+- `reconstruct_source(ref) -> {"status": "ok" | "source_gone" | "unsupported", ...}`; never raises for a missing source
+- `history(memory_id)`, `sources_of(memory_id)`, `derived_from_source(ref)`, `apply_revision(revision)`
+- `GATEWAY_NAMES`: AbstractMemory names re-exported unchanged (`memory_facade.X is abstractmemory.X`), resolved lazily
+
+Ledger row address: `LedgerStore.get_record(run_id, seq)` (slim markers resolved, offloaded leaves rehydrated),
+`list()` records carry `"seq"`, `append()` returns it. Step context: `abstractruntime.core.step_context.current_step_context(run_id)`
+inside an effect handler. Details: [integrations/abstractmemory.md](integrations/abstractmemory.md).
 
 ## Utilities (host UX)
 
@@ -449,6 +470,7 @@ This provides handlers for `MEMORY_KG_*` effects (opt-in wiring layer).
 - `architecture.md` — component map + durability invariants
 - `faq.md` — common questions and gotchas
 - `integrations/abstractcore.md` — `LLM_CALL` / `TOOL_CALLS` wiring
+- `integrations/abstractmemory.md` — memory facade, provenance stamping, `MEMORY_REVISE`
 
 ### Host ASGI serving
 

{abstractruntime-0.14.0 → abstractruntime-0.15.0}/docs/backlog/README.md

@@ -12,9 +12,9 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 ## Counts
 
-- Planned: 31
+- Planned: 32
 - Proposed: 14
-- Completed: 37
+- Completed: 39
 - Deprecated: 13
 - Recurrent: 0
 
@@ -93,6 +93,7 @@ mtime). The anticipated ADR ("an automation is its controller root run") is not
 
 | ID | Item |
 |----|------|
+| 0856 | [Memory facade and ledger provenance](completed/0856_memory_facade_and_ledger_provenance.md): completed 2026-10-27, released in abstractruntime 0.15.0 (2026-10-28, PR #6 merge `88a584b`; floor AbstractMemory>=0.4.0); ADR 0011: `MemoryFacade` (open a mind, stamp, reconstruct a source), `LedgerStore.get_record(run_id, seq)` (JSON-file line-offset index), the step context, a `step` ref on every memory write the runtime performs, `MEMORY_REVISE` / node `memory_revise`. Follow-up 0857. |
 | 0851 | [Per-account voice stores](completed/0851_per_account_voice_stores.md): completed 2026-10-27 (0.13.0); the runtime's voice catalog and voice library use its `voice_store_dir` / `voice_library_dirs`; real-weights E2E 9/9. |
 | 0852 | [Capability refusals are not retried](completed/0852_capability_refusals_are_not_retried.md): completed 2026-10-27 (0.13.0); one engine call for a refused request. |
 | 0847 | [Automations v1: controller, contracts, occurrences, triggers](completed/0847_automations_v1_controller_contracts_occurrences_triggers.md): completed 2026-09-27, moved from planned; UNRELEASED; `79d9bf6`…`d02578a`, 2957 passed / 26 skipped; reviews GO after fixes; E2E 9/9. |
@@ -147,6 +148,7 @@ mtime). The anticipated ADR ("an automation is its controller root run") is not
 | 0848 | `planned/0848_automations_v2_external_event_inbox_and_run_triggers.md` (P2, after 0847's release; contracts pass 2026-09-27) |
 | 0853 | `planned/0853_session_tool_policy_before_the_approval_wait.md` (P1; abstractruntime 0.14.0: a conversation's approve/deny stored per session and applied before any approval wait, with an `abstract.tool_policy_decision` ledger record; gateway routes and client wiring remain) |
 | 0854 | `planned/0854_replay_view.md` (P0; abstractruntime 0.14.0 carries the reducer, the durable per-run `seq` cursor and the conformance cases; gateway routes and client migration remain; ADR 0010) |
+| 0857 | `planned/0857_entity_direct_memory_writes_provenance.md` (P2; entity memory written outside any effect: world models, tending, night passes; follows 0856) |
 | 0044 | `planned/runtime_systemic_reliability/0044_meta_analysis_record.md` (track source record) |
 | 0045 | `planned/runtime_systemic_reliability/0045_crash_replay_harness_and_ordering_invariant.md` |
 | 0046 | `planned/runtime_systemic_reliability/0046_per_run_driver_exclusion.md` |

abstractruntime-0.15.0/docs/backlog/completed/0855_prefix_stability_contract_of_consecutive_llm_calls.md

@@ -0,0 +1,36 @@
+# 0855 — Prefix-stability contract of consecutive LLM calls (only trailing system riders may differ)
+
+**Status**: completed on branch `fix/prefix-cache-reuse` (2026-10-27), UNRELEASED · **Priority**: P1 ·
+**Created**: 2026-10-27
+**Cross-package**: AbstractCore 0858 (native MLX snapshot before trailing riders: the provider half, must ship in a
+Core release); root [1060](../../../../docs/backlog/recurrent/1060_gateway_security_resilience_and_latency_standing_duty.md)
+(latency budget) and [1056](../../../../docs/backlog/proposed/1056_programmable_ai_systems_workflows_as_the_central_primitive.md).
+
+## Why
+Operator report 2026-10-27: a gateway agent run on a local MLX hybrid model re-prefilled the whole prompt at every
+step (10 of 10 calls cold, 24,552 tokens at step 10). Audit of the run's ledger: the runtime's requests ARE
+append-only — system prompt and tool list byte-identical across 11 calls, every message of call N present
+unchanged in call N+1, the grounding envelope stamped once into the durable user turn — except one thing: the
+session attachment index, a `system` rider re-injected at the TAIL on every call (`effect_handlers.py`, backlog
+0212). That rider is the intended design; the cold calls came from the provider's snapshot including it (Core
+0858). Nothing pinned the runtime's half of the contract, so a later change (a timestamp in the system prompt, the
+index moved between turns, a reordered tool list) would silently re-create the same symptom on every backend.
+
+## What shipped
+- `tests/test_llm_call_prefix_stability_contract.py`, through the real `Runtime` (ledger grounding pass) and
+  `make_llm_call_handler` (attachment injection), with a session attachment and a clock that moves on every read:
+  across 4 consecutive tool-loop calls `system_prompt`, `tools` and generation params are identical; call N minus its
+  trailing system riders is a prefix of call N+1; no `system` message sits mid-history; a moving timestamp never
+  reaches the prefix. Red on regression (verified by mutation): a timestamp in the system prompt → 2 failed; the
+  index placed after the first user turn → 1 failed.
+- The injection site documents the rider contract and names the Core seam.
+
+## Limits (from the adversarial review)
+- The test stops at the LLM-client seam (stub client): what `llm_client` does afterwards (grounding normalization,
+  synthetic/volatile key stripping) is not covered, and the transcript is built append-only by the test itself; the
+  agent adapter owns that shape. Follow-up: drive the real local client over a stub provider.
+
+## Not changed (deliberately)
+The index stays a trailing rider. Moving it into the history (after the turn's user message) would make the tool
+loop restorable with today's Core but makes every cross-turn first call cold once Core 0858 ships; stamping it
+durably would accumulate copies per turn.

abstractruntime-0.15.0/docs/backlog/completed/0856_memory_facade_and_ledger_provenance.md

@@ -0,0 +1,167 @@
+# 0856 — Memory facade and ledger provenance: the host surface for AbstractMemory, the ledger row address, and a step ref on every memory write
+
+**Status**: completed 2026-10-27, released in abstractruntime 0.15.0 (2026-10-28, PR #6 merge `88a584b`; floor AbstractMemory>=0.4.0) · **Priority**: P1 · **Created**: 2026-10-27
+**Cross-package**: AbstractMemory ADR 0003 and backlog 0056 (`abstractmemory.graph`: `SourceRef`, `Provenance`,
+`MemoryGraph`; AbstractMemory 0.4.0), AbstractGateway memory routes (`/api/gateway/memory/*` over this facade) and its
+import-boundary burn-down, AbstractNote thin-client slice (step and artifact refs on note revisions). ADR:
+[0011](../../adr/0011_memory_facade_is_the_complete_host_surface_for_abstractmemory.md).
+
+## Why
+Operator goal (2026-10-27, AbstractMemory ADR 0003): every derived memory is tied to the ledger's messages, events
+and artifacts, so the verbatim source of any understanding, or of any change of understanding, can be reconstructed.
+AbstractMemory stores references; resolving them is the runtime's job, because the runtime owns the ledger, the
+artifacts, the diary chain and the event inbox. Hosts must reach AbstractMemory through the runtime (ADR 0008
+decision 2), and no AbstractMemory facade existed.
+
+## Current code reality (2026-10-27, `main` 93c45b4)
+- `storage/base.py` `LedgerStore`: `append`, `list(run_id)`, `find_completed_result`; no read by address. SQLite
+  (`storage/sqlite.py`) has a `seq` primary key that `list()` does not return; JSONL has positions only.
+- A step is a STARTED row and a terminal row sharing one `step_id` (`core/runtime.py`, `_execute_effect_with_retry`);
+  the terminal row is slimmed (`storage/ledger_slim.py`: `$slim` markers resolved against the STARTED payload);
+  oversized leaves are offloaded (`storage/offloading.py`, rehydrated only by `find_completed_result`).
+- Effect handlers receive `(run, effect, default_next_node)`; nothing tells them their own ledger row. The publish
+  handler gets `step_id` as an extra argument.
+- Memory provenance written today (audit 2026-10-27, `untracked/memory-transition/audit/abstractruntime_entity.md`
+  §2): `MEMORY_FORM` `run_id`/`turn_id` + the verbatim artifact as `payload_ref` (`seam_handlers._handle_form`),
+  `MEMORY_KG_ASSERT` `writer_run_id`/`writer_workflow_id`/`span_id` (`effect_handlers._handle_assert`), diary
+  projections `{source, entry_id}` + `origin` (`identity_support.project_diary_entry`). No ledger row address; on the
+  home-direct entity path the `run_id` is the synthetic `chat-<session_id>`.
+- AbstractGateway imports `abstractmemory` directly in 34 lines across 8 files.
+
+## Scope
+In:
+- `LedgerStore.get_record(run_id, seq)` (base default over `list()`, SQLite by primary key, JSONL by position,
+  `OffloadingLedgerStore` rehydrating, the decorators delegating); `$slim` markers resolved against the STARTED row of
+  the same `step_id`; `list()` records carry `"seq"` (ADR 0010's per-run number since 0.14.0, excluded from the record hash); `append()`
+  returns the seq it wrote when the backend knows it.
+- `abstractruntime.core.step_context`: the runtime publishes the current step `(run_id, seq, step_id, node_id,
+  attempt, effect_type)` to the handler it executes (a `ContextVar`, out of band like the progress callback).
+- `integrations/abstractmemory/memory_facade.py`: `MemoryFacade` (`open_mind`, `graph`/`store`/`journal`, `stamp`,
+  `reconstruct_source`, `history`/`sources_of`/`derived_from_source`), `is_real_run`.
+- Stamping in `MEMORY_FORM`, `MEMORY_KG_ASSERT` and the `DIARY_WRITE` projection.
+- The workflow-native primitive (operator, 2026-10-27: "workflows are the framework's central native primitive; memory
+  capture and reconsideration should be expressible as workflow steps/effects with ledger provenance"):
+  `EffectType.MEMORY_REVISE` (host handler in `build_memory_kg_effect_handlers` over `MemoryGraph.apply_revision`)
+  and the VisualFlow node `memory_revise`.
+- Performance of the row address on the JSON-file backend (the gateway's default).
+- ADR 0011, docs (`api.md`, `integrations/abstractmemory.md`), CHANGELOG.
+
+Out:
+- Writes outside any effect (world models, tending, the night passes): [0857](../planned/0857_entity_direct_memory_writes_provenance.md).
+- Moving the memory writers onto `MemoryGraph.apply_revision` (AbstractMemory's convergence track); the gateway
+  routes and the gateway's import burn-down (AbstractGateway).
+- A hash chain on conversation ledgers; real runs behind the home-direct entity driver.
+
+## Validation
+- Both backends (and the offloading decorator): `get_record` of a slimmed terminal row returns the STARTED payload
+  bytes; a mutant that returns the slimmed row unresolved fails; `list()` carries `seq`; the diary chain verifies.
+- `reconstruct_source` on real temporary stores (`SqliteRunStore`, `SqliteLedgerStore`, `FileArtifactStore`,
+  `DiaryStore`, `JsonFileEventInbox`): ok / `source_gone` after deletion / `unsupported`.
+- A real `Runtime` run: the episode formed by `MEMORY_FORM` carries a `step` ref that resolves through `get_record` to
+  that step; the KG assertion carries one; a diary projection carries a `diary_entry` ref; the synthetic chat path
+  carries artifact refs only. Each test fails with the stamping line removed.
+
+## Report (2026-10-27)
+
+Commits on `feat/memory-graph-facade` (after `76b1319` WIP): `de96ede` memory facade, `7b0d031` step context
+installed, `dd9e924` stamping, `2574881` MEMORY_REVISE + node, `09db6f5` row-address performance, `76e9988` docs and
+version, `9eea551` diary reads in `GATEWAY_NAMES`; this report.
+
+What landed:
+- `integrations/abstractmemory/memory_facade.py`: `MemoryFacade` (`open_mind`, `graph`/`store`/`journal`, `stamp`,
+  `stamp_current_step`, `apply_revision`, `history`/`sources_of`/`derived_from_source`, `reconstruct_source`),
+  `is_real_run`, `GATEWAY_NAMES` (43 names: the gateway's direct imports, including the diary reads `open_questions` /
+  `open_problems` / `open_ideas`, + the 8 graph names; every one exists in AbstractMemory, none left out), resolved by module `__getattr__` so the module never imports AbstractMemory at
+  import time.
+- `core/runtime.py` `_execute_effect_with_retry` installs `effect_step_context(StepContext(...))` around the handler,
+  with the seq `append()` returned for the attempt's STARTED row.
+- Stamping: `seam_handlers._handle_form`, `effect_handlers._handle_assert`, `identity_support.project_diary_entry`.
+  A caller `payload_ref` is an artifact ref only when the artifact store holds it (a payload_ref may name an
+  identity-core `.yaml` record). A private diary projection names its entry only (no origin by design).
+- `MEMORY_REVISE` / `memory_revise`: contract in `docs/integrations/abstractmemory.md`. Caller `run`/`step` refs are
+  refused (runtime-owned); unknown payload keys are refused; the default `revision_id` hashes (run, node, scope,
+  owner, cause, ops) so a retried attempt is a no-op.
+
+Performance (10,000 rows, ~10 MB JSON-file ledger, ~1 KB rows, Apple Silicon, warm cache; method:
+fill one run's ledger with 5,000 STARTED/COMPLETED pairs through `append`, then the median of 20 calls each):
+
+| | JSONL before | JSONL after | SQLite before | SQLite after |
+|---|---|---|---|---|
+| `get_record(seq)` | 58 ms | 0.05 ms | 0.02 ms | 0.01 ms |
+| `find_started_record(step, before_seq=terminal)` (the slim-resolve path) | 58-72 ms (full parse) | 0.08 ms | 3.5 ms | 0.01 ms |
+| `find_started_record(step)` unbounded, row in the middle | 72 ms | 12 ms | 11 ms | 3.4 ms |
+| `find_started_record` worst case (first row) / miss | 72 ms | 24 ms / 7 ms | 11 ms | 10 ms |
+| first read in a cold process (index build) | 58 ms | 48 ms | 0.3 ms | 0.3 ms |
+
+JSONL: a per-run line-offset index (`_JsonlRowIndex`, 8 bytes per record, 128 runs LRU), written through by
+`append`, extended by reading only the bytes another writer appended (keyed by inode + indexed size), rebuilt for a
+recreated file; a torn trailing line falls back to the `list()` reading. `append` uses the index (not a full
+`list()`) to count after a foreign write. SQLite: `find_started_record` reads newest-first with `LIMIT 1` (Python's
+cursor prefetch made the unlimited query scan the rest of the run).
+
+Tests: `test_memory_facade.py` (10), `test_step_context.py` (4), `test_memory_step_provenance.py` (7),
+`test_memory_revise.py` (7), `test_jsonl_row_index.py` (6); each docstring lists the mutants checked by hand.
+Full suite (`PYTHONPATH=src:<AbstractMemory graph worktree>/src`): `main` 3763 passed / 46 skipped / 0 failed; this
+branch 3810 passed / 46 skipped / 0 failed (+47: the get_record, facade, step-context, provenance, MEMORY_REVISE and
+row-index tests). `tests/test_packaging_extras.py` pins the new `AbstractMemory>=0.4.0` floor.
+
+Seams and notes:
+- `abstractmemory.graph.Provenance.from_dict` turned a STRING `derived_from` into a tuple of characters
+  (`tuple("m1")`); reported, fixed on the AbstractMemory branch (`c2f035f`), not worked around here.
+- Review N1 (AbstractNote review): a tool approved by a human runs inside `Runtime.resume`, outside
+  `_execute_effect_with_retry`, so it saw no step context and its note carried no step ref. Fixed: the approval
+  resume publishes the waiting TOOL_CALLS step (`_waiting_step_context`: the WAITING row's `step_id`, the seq of ITS
+  STARTED row via `find_started_record`, `seq=None` when that row cannot be found, never guessed). Audit of the other
+  paths: WAIT_EVENT / WAIT_UNTIL / ASK_USER / subworkflow resumes only write the payload into vars (no handler or
+  tool runs; the next effect goes through `_execute_effect_with_retry`), terminal hooks are not effect handlers, the
+  publish / schedule handlers are effect handlers, and the tool executor's worker threads copy the context
+  (`contextvars.copy_context`). Test: `test_step_context.py::test_a_tool_run_by_an_approval_resume_sees_the_waiting_steps_started_row`
+  (SQLite and JSONL); the reviewer's AbstractNote proof script now records `ledger_seq` / `ledger_step_id` resolving to
+  the `note_capture` TOOL_CALLS STARTED row.
+- `is_real_run` reuses AbstractMemory's `is_synthetic_run_id` / `SYNTHETIC_RUN_ID_PREFIXES` (9e2c231), compared
+  case-insensitively, plus the configured global memory owner; a test pins that the two packages agree.
+- `llms-full.txt` was not regenerated (coredoc pass at release).
+
+### Review fixes (2026-10-27: gateway review R5/R6, runtime review 3a)
+- R1 `1779fa9`: MEMORY_REVISE normalizes caller ref kinds through `SourceRef` before refusing `run`/`step` ("STEP").
+- R2 `7bd49ab`: a caller ref's `run_id` must be the executing run or absent.
+- R3 `860eac7`: named artifacts must exist in the builder's new `artifact_store`; without one, a revision naming
+  artifacts is refused.
+- R4 `e184633`: the default `revision_id` also hashes the caller's sources, derived_from, artifact_ids, occurred_at.
+- R5 `e84be06`, `12b61c7`: `runtime_id` on the facade (`open_mind`, the KG / seam builders); a ref naming another
+  runtime (or any runtime, on a facade without one) is `unsupported`; lifted refs carry the facade's runtime_id.
+- R6 `e84be06`: a `run` source's ledger is bounded (`limit` default 200, max 1000, `ledger_left_out`, `truncated`).
+- R7 + R13 `af2ba20`: `stamp` screens caller refs (run/step dropped, synthetic run ids stripped, invalid refs
+  rejected, a flat run_id other than the stamped run never lifted; `rejected_sources` records each; never raises);
+  `is_real_run` reuses AbstractMemory's `is_synthetic_run_id`, case-insensitively.
+- R8 `69fcccc`: parity test: every stamped dict reads back through `Provenance.from_legacy` (AbstractMemory 4c821b2).
+- R9 `630b2ef`: the JSONL append ends a torn last line first.
+- R10 `11630a9`: `coerce_ledger_seq` never truncates (3.9 is refused); seq is 1-based (a step ref's seq >= 1).
+- R11 `a38324b`: a duplicate KG assertion's unrecorded sources are reported (`skipped_duplicate_rows[].lost_sources`).
+- R14 `6f44bf1`: `metadata.unresolved_markers` on a step whose STARTED row is gone.
+
+Notes (not fixed here):
+- R12: the step context is a `ContextVar`. A handler that starts a plain `threading.Thread` gives that thread no
+  context (the thread sees None and stamps no step ref); the tool executor copies the context into its workers
+  (`contextvars.copy_context`), and a handler that spawns its own threads must do the same.
+- R15: rows written by `MEMORY_KG_ASSERT` (and the seam writers) go through `store.add`, not through the graph, so
+  `MemoryGraph` does not know them until a revision adopts them (an `import`/`migration` revision); a `close` or
+  `narrow` revision on such a row needs that adoption first. Moving the writers onto `apply_revision` is the
+  convergence track (Out, above).
+- Follow-up (R11): record a second source on an existing memory (a revision adopting the row with the new refs)
+  instead of reporting it as lost.
+
+### Architect pass (2026-10-27)
+Open operator decisions, written in ADR 0011 (Open decisions), not chosen here:
+- JSON-file `seq` durability: DECIDED as option (a) by runtime 0.14.0 (ADR 0010, the persisted per-run `seq`); the
+  merge of 0.14.0 into this branch makes `get_record` and the row index read by persisted `seq` (a rewritten file
+  never answers another row).
+- Owner = principal, scope = kind (B1's full fix); the runtime now refuses an `owner_id` the run does not derive.
+
+C3 (persisted JSON-file row index, `ledger_<run_id>.idx`): 100,000-row run (87.5 MB), the architect's
+`c_jsonl_ledger.py`, this machine: first `get_record` in a fresh process 320 ms -> 39 ms (the persisted index plus at
+most 1/8 of the ledger's tail parsed); after 129 other runs evicted it from the 128-run cache 305 ms -> 42 ms; warm
+point read 0.03 ms (unchanged); 100k appends 5.0-5.2 s -> 6.0 s (the index rewrites, a small multiple of its final
+800 KB in total). The index is validated against the ledger (inode, indexed size inside the file and ending on a line
+break, row count) and rebuilt otherwise; `delete` removes it.
+

abstractruntime-0.15.0/docs/backlog/planned/0857_entity_direct_memory_writes_provenance.md

@@ -0,0 +1,38 @@
+# 0857 — Entity memory written outside any effect carries no ledger source: world models, tending, the night passes
+
+**Status**: planned · **Priority**: P2 · **Created**: 2026-10-27
+**Cross-package**: AbstractMemory ADR 0003 (every memory is sourced or derived; `MemoryGraph.apply_revision` refuses an
+ungrounded write) and its convergence track (moving writers onto revisions). ADR:
+[0011](../../adr/0011_memory_facade_is_the_complete_host_surface_for_abstractmemory.md) (Consequences, Negative).
+Follows [0856](../completed/0856_memory_facade_and_ledger_provenance.md).
+
+## Why
+0856 stamps a ledger source on every memory write the runtime performs INSIDE an effect (`MEMORY_FORM`,
+`MEMORY_KG_ASSERT`, the `DIARY_WRITE` projection, `MEMORY_REVISE`). Entity homes also write derived memory by calling
+AbstractMemory engines directly, outside any runtime step, so no step context exists and nothing names a source:
+
+- `identity/chat.py` `world_model_update` (two sites) and `author_world_model`;
+- `apply_tend_elections` (`identity/chat.py`, `integrations/abstractmemory/brain_handlers.py` `MEMORY_TEND`);
+- the night passes `sleep_pass` / `dream_pass` (`identity/life.py` `_consolidate`, `brain_handlers.py`
+  `MEMORY_CONSOLIDATE`).
+
+These memories are DERIVED: under ADR 0003 they must name the memories they were derived from (`derived_from`) or a
+ledger source. Today they carry `actor` / `channel` / `author` only, so a reader cannot trace them to any verbatim,
+and once the writers move onto `MemoryGraph.apply_revision` they would be refused (`ProvenanceRequired`).
+
+## Scope
+In:
+- Run the derived writes that have an enclosing effect (`MEMORY_TEND`, `MEMORY_CONSOLIDATE`) with that effect's step
+  context and stamp its `step` ref through `MemoryFacade.stamp_current_step`.
+- For the direct calls on the home-direct chat path and the life loop: either move them behind effects (a real run per
+  night pass / tend election, so a step ref exists), or pass `derived_from` = the memory ids the engine read, through
+  an AbstractMemory API that accepts it. Never a synthetic `chat-<sid>` run ref.
+- Tests on a real home: a world-model update / tend election / night pass record names its sources or the memories it
+  was derived from, and `MemoryFacade.sources_of(..., transitive=True)` reaches a ledger source.
+
+Out:
+- Real runs behind the home-direct entity driver as a whole (its own item); the gateway's routes.
+
+## Validation
+- Each derived writer above leaves provenance that `MemoryFacade.sources_of` resolves to at least one ledger source
+  (directly or through `derived_from`); a test fails when the stamping line is removed.