AbstractRuntime 0.13.1__tar.gz → 0.15.0__tar.gz

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

@@ -7,6 +7,133 @@ 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.
+Upgrade note (one way): hash-chained JSONL ledgers written by 0.14.0 carry `seq` on each line, and
+an older `verify_ledger_chain` reports those lines as tampered. Upgrade writers and verifiers together.
+
+### Added
+
+- **Replay view** (`abstractruntime.replay`, ADR 0010, backlog 0854; framework root 0993). One
+  pure, deterministic reducer turns a run tree's ledger records and snapshots into the view every
+  client renders (`replay_view_v1`).
+  - What the view holds:
+    - the run tree through delegation waits, with the workflow each run executes (bundle,
+      version, flow, the root's entrypoint);
+    - the status;
+    - the person-facing interaction: a delegated child's approval, a question, or a prompted
+      event, with the resume command to send;
+    - verbatim messages with their provenance (run, steps, seqs, artifacts);
+    - one activity per node execution (AbstractFlow's `executionIdFor` rules), with tool calls
+      matched to results;
+    - artifacts and usage.
+  - `$slim` pointers are resolved, and a windowed history is named in `warnings`.
+  - A wait is over when a resume OR a later step of the same run exists.
+  - `ReplayView.apply` folds newer records and returns a delta. `apply_delta` and `diff_views`
+    are the client side. `replay(all)` equals the fold of any chunking.
+  - Wait kinds agree with `automations.attention`. The person-facing kinds are tool_approval,
+    ask_user, and an event that carries a prompt. The non-person-facing kinds are delegation,
+    timer, job, pause, automation_wake and signal. The interaction carries `answer_payload`.
+  - A session tool policy's `abstract.tool_policy_decision` record is an activity
+    (`tool_policy`: allowed or denied by the conversation's policy, its revision and who set it),
+    never an interaction. The tool rows it names carry `decided_by: "session_policy"`.
+  - Every delta carries typed `changes` (status, interaction opened or closed, run, message,
+    activity, artifact, each with its run and seq), for push dispatch.
+  - Cursor tokens name each run by a collision-free prefix that is safe in a header.
+    `resolve_cursor_token` maps a token back.
+  - The conformance cases ship with the package (`abstractruntime.replay.conformance`), so a host
+    or a client port can run them. Guide: `docs/replay.md`.
+- **Durable ledger cursor** (gateway backlog 0082). A JSONL append after a torn last line (a
+  crash mid-write) now starts a new line; before, the fragment and the whole new record were
+  dropped together:
+  - Every ledger store numbers a run's records (`seq`). `JsonlLedgerStore` persists the number
+    on each line, allocated under an advisory file lock, so two processes never take the same
+    seq. Lines written before the field existed read as their position.
+  - `LedgerStore.list_after(run_id=, after=, limit=)` works on every store: an indexed read on
+    SQLite, a byte-offset seek on JSONL. `append()` returns the seq.
+  - `ObservableLedgerStore` passes `seq` to subscribers.
+  - `SqliteLedgerStore.import_records` copies a ledger in and keeps its `seq` values (migration).
+
+- **Session tool policy**: a conversation's standing "approve / deny without asking", applied before any approval
+  wait. `abstractruntime.storage.session_tool_policy` (`SqliteSessionToolPolicyStore`,
+  `InMemorySessionToolPolicyStore`, `session_policy_names`), `Runtime(session_tool_policy_store=...)` /
+  `Runtime.set_session_tool_policy_store()`. The TOOL_CALLS handler reads the run's session row once per batch: an
+  approved call runs with no wait, a denied call is refused with no wait, and each decision writes an
+  `abstract.tool_policy_decision` ledger record (who set the policy, when, which selector matched). It applies to
+  every run of the session (the run tree's root session: delegated children, resumes, restarts); approvals never
+  reach untrusted-input runs or automation occurrences (a deny does, and also wins over an approval that was shown
+  before it); never beyond the run's `allowed_tools`. Before this, "approve all" lived in each
+  client, which answered the wait after it arrived: the gate flashed in every app and in the ledger. See
+  [tool-approval.md](docs/tool-approval.md#session-tool-policy-a-conversations-standing-word).
+
+### Changed
+
+- Hash-chained ledgers: `seq` is persisted on each JSONL line and excluded from the hash by this
+  version's `compute_record_hash`. A verifier from an older version includes it, so it reports
+  every line written by this version as tampered. Upgrade every process that verifies a chain
+  (`verify_ledger_chain`) together with the writers.
+- `LedgerStore.list()` records carry `seq`. A consumer that compared records to `asdict(record)`
+  sees one more key. The hash chain excludes `seq` (it is the store's position, assigned after
+  the hash).
+
 ## [0.13.1] - 2026-10-27
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.13.1
+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,37 @@ 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.8.2 • **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
+  into the view every client renders (status, the interaction to answer, messages, activities,
+  artifacts), with incremental deltas. Every ledger store now numbers records with a durable
+  per-run `seq` cursor (`list_after`). See [docs/replay.md](docs/replay.md).
+- **Session tool policy**: a conversation's standing approve/deny is applied before any approval
+  wait, with an `abstract.tool_policy_decision` audit record. See
+  [docs/tool-approval.md](docs/tool-approval.md#session-tool-policy-a-conversations-standing-word).
+- Upgrade note: hash-chained JSONL ledgers written by 0.14.0 fail an older `verify_ledger_chain`;
+  upgrade writers and verifiers together.
+
 ## AbstractFramework ecosystem
 
 AbstractRuntime is one component of the wider [AbstractFramework](https://github.com/lpalbou/AbstractFramework) ecosystem:

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

@@ -4,10 +4,37 @@
 
 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.8.2 • **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
+  into the view every client renders (status, the interaction to answer, messages, activities,
+  artifacts), with incremental deltas. Every ledger store now numbers records with a durable
+  per-run `seq` cursor (`list_after`). See [docs/replay.md](docs/replay.md).
+- **Session tool policy**: a conversation's standing approve/deny is applied before any approval
+  wait, with an `abstract.tool_policy_decision` audit record. See
+  [docs/tool-approval.md](docs/tool-approval.md#session-tool-policy-a-conversations-standing-word).
+- Upgrade note: hash-chained JSONL ledgers written by 0.14.0 fail an older `verify_ledger_chain`;
+  upgrade writers and verifiers together.
+
 ## AbstractFramework ecosystem
 
 AbstractRuntime is one component of the wider [AbstractFramework](https://github.com/lpalbou/AbstractFramework) ecosystem:

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

@@ -27,9 +27,10 @@ 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, and per-call refiners (the `send_email` recipient rule: self and pre-authorised recipients)
+- `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)
 - `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and document nodes (`read_pdf` / `write_pdf` / `write_docx`)
 - `api.md#sessions-and-history` — session history replay: one window, the most recent 50,000 tokens of whole turns (`HISTORY_REPLAY_MAX_TOKENS`), returned as a `ReplayedHistory` whose `.report` records what was replayed and dropped
 - `api.md#conversation-search` — keyword search over a plane's conversations (`ConversationSearch`): questions, answers and the turn's artifacts, one SQLite FTS5 trigram index per plane, incremental `sync` with a time budget, exact then fuzzy matching
@@ -41,6 +42,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `entity-runtime.md` — per-entity runtimes for summoned entities: homes, the one-writer lease, act-only diary privacy (`$act_only` refs), durable visit waits with deadlines
 - `evidence.md` — artifact-backed evidence capture for external-boundary tools
 - `mcp-worker.md` — MCP worker CLI (`abstractruntime-mcp-worker`)
+- `replay.md` — the replay view: one reconstruction of a run tree (status, the interaction to answer, messages, one activity per execution, artifacts, usage, the workflow it executes) that every client renders; the durable cursor (`seq`, `list_after`); conformance fixtures
 - `snapshots.md` — snapshot/bookmark model and stores
 - `provenance.md` — tamper-evident hash-chained ledger
 - `limits.md` — runtime-aware `_limits` namespace and APIs

{abstractruntime-0.13.1 → abstractruntime-0.15.0}/docs/adr/0008_integration_facades_are_the_complete_host_surface.md

@@ -24,6 +24,12 @@ host needed, with no rule saying whose job it was to close the gap.
 2. A host never works around a missing name by importing `abstractcore` directly, vendoring the
    code, or guessing a replacement. It raises the gap to the runtime (backlog item or PR) and
    pins the runtime floor that carries the fix.
+   The same holds one level down and for whole capabilities, not only names: when a host finds
+   a FEATURE or CAPABILITY missing (a voice operation, a mail verb, a media task, a lookup), the
+   runtime, which does the integration, surfaces it through a facade, a typed refusal
+   (`CapabilityUnavailableError`, a 501 with the install hint) or a backlog item. A missing
+   capability is never a reason for a host to import a lower-level package (AbstractCore,
+   AbstractVoice, AbstractMemory, their dependencies) directly.
 3. A re-export is unchanged in identity (`facade.name is abstractcore.module.name`) and listed in
    the facade's `__all__`; the facade documents which AbstractCore version introduced the name.
 4. The facades are additive within a minor line: a name, once exported, is not removed without

abstractruntime-0.15.0/docs/adr/0010_one_replay_many_views.md

@@ -0,0 +1,104 @@
+# ADR 0010: One replay of the ledger, many views
+
+Status: Accepted.
+Date: 2026-10-27
+
+## Context
+
+The run ledger is the record of a run. Every client that shows a run needs the same few facts
+about it: its status, the approval or question it is waiting on, the replies, the tool calls and
+the steps. Until this decision, each client worked those facts out for itself from raw ledger
+records, run snapshots and its own memory. Panel-chat, the AbstractCode terminal client, the
+desktop Assistant, the iPhone and watch apps, the Observer, AbstractFlow and both gateway
+consoles each had their own reconstruction. The inventory, with file:line anchors, is in
+[backlog 0854](../backlog/planned/0854_replay_view.md). The reconstructions disagreed on the same
+run:
+
+- 2026-09-29: a delegated child's tool approval showed as "Approval needed" on one client and as
+  "Running a tool" on another. A delegation wait displaced the person-facing wait, and a `$slim`
+  dedup pointer was left unresolved.
+- 2026-10-04: a `wait_until` timer with no resume record left 182 of 3,278 runs showing "Waiting
+  for you" after they had completed.
+- 2026-10-11: one Agent node execution showed as two steps, because nothing in the records names
+  the execution.
+
+The operator's ruling (framework root backlog 0993,
+`abstractframework/docs/backlog/planned/0993_one_ledger_replay_many_views.md`): "there should be
+only one unified way to replay the ledger, on top of which we could have different views", and
+"logic should not be in the thin client". Each client decides what to show and how to forward
+the requests of the users and entities it serves.
+
+Durability had a gap of its own. The SQLite ledger had a per-run `seq` and the JSONL ledger had
+none. The gateway's cursor was a list position, and the file-to-SQLite migration renumbered
+records (gateway backlog 0082).
+
+## Decision
+
+1. **One reducer, in the runtime.** `abstractruntime.replay` is the only code that turns ledger
+   records into run state for display:
+   - `replay(records_by_run, runs_by_id)` folds a run tree's records and durable snapshots into a
+     `ReplayView`.
+   - `ReplayView.apply(records)` folds newer records into it and returns the delta.
+   - `replay(all)` is `apply` over every record, so it equals folding the same records in chunks.
+
+   The reducer is pure and deterministic: no I/O and no clock, and its input is records plus
+   snapshots. Its JSON is versioned (`replay_view_v1`). A change in meaning is a new version,
+   never a silent change.
+2. **The reducer owns these rules.** Each rule below was a divergence between clients:
+   - The run tree comes from delegation waits (`subworkflow:<id>`), `start_subworkflow` results
+     and the snapshots' `parent_run_id`. When the two disagree, the ledger's link wins.
+   - A wait is over when its run records a `resume` for its key OR any later step of the same run
+     exists. Observability events are not steps.
+   - The person-facing interaction is the newest open approval, question or prompted event
+     anywhere in the tree. A delegation, a timer or a pause never is one.
+   - Status precedence: a terminal snapshot, then the ledger's terminal record, then an open wait,
+     then running.
+   - `$slim` pointers are resolved against the STARTED record. A pointer that cannot be resolved
+     is dropped and named in `warnings`.
+   - Executions follow AbstractFlow's `executionIdFor` rules.
+   - Each run names the workflow it executes (`bundle_id@version:flow_id`; the root's flow is its
+     entrypoint). Workflows are the framework's native unit.
+3. **The durable cursor is the per-run ledger `seq`.**
+   - Every ledger store numbers records 1, 2, 3, … per run. JSONL persists the number on append,
+     allocated under an advisory file lock. A line written before the field existed is numbered
+     by its position.
+   - Every store answers `list_after(run_id, after, limit)`.
+   - `SqliteLedgerStore.import_records` keeps `seq` across a migration.
+   - A view's cursor is the seq of each run in its tree. Its token `<run id prefix>:<seq>.…` is
+     the view's ETag and the SSE event id.
+4. **Hosts serve the view, and clients render it.**
+   - AbstractGateway serves `GET /runs/{id}/view` (ETag, 304, `?at=<token>`) and
+     `GET /runs/{id}/view/stream` (one `view`, then `delta` events, `Last-Event-ID`). There is
+     one cached view per run tree, folded once per appended record and fanned out to every
+     subscriber, with no timed re-parse.
+   - Clients act through the host's commands. The view's `interaction.command` is the resume to
+     send. Clients hold no run state that the server could replay.
+   - A client may keep a local view only as a cache of these deltas (`apply_delta`). It never
+     builds one from raw records.
+
+## Enforcement
+
+- A client or host change that derives status, waits, tool rows or messages from raw ledger
+  records, outside `abstractruntime.replay`, conflicts with this ADR. The fix is a reducer change
+  with a fixture, or a view field.
+- A reducer change that alters an existing fixture's expected view needs one of two things: the
+  fixture's diff in the PR and its reason, or a new `replay_view_vN` when the meaning of a field
+  changes.
+- A new ledger store implements `list_after`, and its records carry `seq`. A migration between
+  stores preserves `seq`.
+
+## Validation
+
+- `tests/test_replay_conformance.py`: the conformance cases shipped in
+  `abstractruntime.replay.conformance` (redacted real ledgers and synthetic cases), each with its
+  expected view and hand-written semantic checks.
+- `tests/test_replay_invariants.py`: replay equals fold over any chunking and interleaving,
+  idempotence, delta round trips, and header-safe cursor tokens.
+- `tests/test_ledger_cursor_invariants.py` and `tests/test_jsonl_ledger_seq_cross_process.py`:
+  the invariants of gateway backlog 0082 at store level (completeness, `list_after` equals a
+  replay from the same cursor, cursor stability across reopen and migration, recovery), and dense
+  seqs under concurrent processes.
+- AbstractGateway `tests/test_gateway_replay_view.py`, `tests/test_migrate_preserves_ledger_seq.py`
+  and the principal isolation matrix: the routes through the real app.
+- Every client that renders runs runs the conformance fixtures in its CI once it migrates
+  (backlog 0854).

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.13.1 → abstractruntime-0.15.0}/docs/adr/README.md

@@ -20,7 +20,9 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 0005 | [Runtime Owns AbstractCore Host Discovery Queries](0005_runtime_owns_abstractcore_host_discovery_queries.md) | Accepted | 2026-05-20 | Hosts should ask Runtime for Core discovery/catalog snapshots |
 | 0006 | [Runtime Owns Durable AbstractCore Bloc Prompt-Cache Control](0006_runtime_owns_durable_abstractcore_bloc_prompt_cache.md) | Accepted | 2026-05-20 | Hosts should use Runtime for durable bloc/KV controls and binding-aware execution |
 | 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 a host needs is a runtime facade re-export; a gap is a runtime patch, never a host import |
+| 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
 
@@ -36,6 +38,8 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 0006 | `backlog/completed/027_runtime_durable_bloc_prompt_cache_facade.md` |
 | 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.13.1 → abstractruntime-0.15.0}/docs/api.md

@@ -133,6 +133,12 @@ Run index and creation (all built-in run stores, including the offloading wrappe
 - `JsonFileRunStore` event-wait and mailbox indexes (`list_event_waiters`, `list_event_waiters_by_prefix`, `list_mailbox_runs`) see what another process saved on the same folder (a split gateway: API process + runner process). Before each lookup the store reads its change signal (the creation log's size and the folder's mtime): when either moved, or at least every `EVENT_INDEX_REFRESH_S` (2 s), it stats each running or waiting run and re-reads the ones whose file changed since it last filed them. An idle store pays two stats per lookup; its own saves are never re-read. `event_index_stats()` returns `{refreshes, refiled, tracked}`.
 - `JsonFileRunStore.change_token()` answers "did any run of this folder change?" with one stat: `(creation-log size, active-index counter)`. Every save, create and delete through the store moves the counter; another process's create, delete or became-active line moves the log size. Not seen: another process re-saving a run that stays active (one ticking process per folder); ending a run, or re-saving a finished one, writes `=<run_id>`. `changed_run_ids(token)` names the runs this store changed since `token`, or `None` when that is unknown (the log moved, or more than 8,192 changes ago). `ObservableLedgerStore.change_token()` / `changed_run_ids(token)` do the same for ledger appends (process-local). The gateway runner's scan gate and its mail notification check compare these tokens instead of reading the directory.
 
+The durable cursor (ADR 0010):
+- Every ledger store numbers a run's records 1, 2, 3, … and `list()` returns each record with its `seq`. `JsonlLedgerStore` writes it on each line, allocated under an advisory file lock that spans the head read and the write, so another process appending to the same run never takes the same number. A line written before the field existed is numbered by its position. `append()` returns the seq.
+- `LedgerStore.list_after(*, run_id, after, limit=1000) -> (records, last_seq)`: the records after a seq. SQLite does an indexed read; JSONL seeks to the byte offset where the previous read ended; the default implementation filters `list()`. The decorators (observable, hash-chained, offloading) delegate it.
+- `ObservableLedgerStore` hands subscribers the record with its `seq`.
+- `SqliteLedgerStore.import_records(run_id, records)` copies a run's ledger in, keeping each `seq`. A migration from files to SQLite therefore keeps every cursor valid. It refuses a run that already has records.
+
 Common decorators:
 - `ObservableLedgerStore` for subscriptions (`src/abstractruntime/storage/observable.py`)
 - `HashChainedLedgerStore` + `verify_ledger_chain(...)` for tamper-evidence (`src/abstractruntime/storage/ledger_chain.py`)
@@ -326,6 +332,25 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 When available, it also includes `resolved_actions`: bounded capability/action summaries derived
 from Core route resolution and persisted from `LLM_CALL` results.
 
+## Replay view (one reconstruction of a run, every client)
+
+Implementation: `src/abstractruntime/replay/` (ADR 0010). Guide: [replay.md](replay.md).
+
+- `replay(records_by_run, runs_by_id=None, *, root_run_id=None) -> ReplayView`: folds a run
+  tree's ledger records (`{run_id: [records in ledger order]}`) and durable snapshots
+  (`RunState` or dicts) into a view. Pure and deterministic.
+- `ReplayView.apply(records, *, runs_by_id=None) -> delta`: folds newer records and snapshots.
+  The same delta is kept as `view.last_delta`. `apply(view, records)` is the module-level form.
+- `ReplayView.to_json()`: the view, `replay_view_v1` (status, `interaction`, `open_waits`,
+  `runs`, `messages`, `activities`, `artifacts`, `usage`, `workflow`, `cursor`, `warnings`).
+  Other reads: `cursor`, `run_ids`, `last_seq(run_id)`, `status()`, `run_statuses()` and
+  `is_terminal()`.
+- `apply_delta(view_json, delta)`, `diff_views(old, new)` and `parse_cursor_token(token)`: the
+  client side of a delta, the delta between two views, and a cursor token as `{run id prefix:
+  seq}`.
+- `wait_kind(wait)`, `workflow_ref(workflow_id)`, `PERSON_FACING_KINDS`,
+  `TERMINAL_STATUSES`, `REPLAY_VIEW_VERSION`.
+
 ## Runtime-owned integrations
 
 ### AbstractCore (LLM + tools)
@@ -410,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)
 
@@ -424,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