AbstractRuntime 0.4.14__tar.gz → 0.4.16__tar.gz

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.16] - 2026-05-21
+
+### Added
+- Public durable AbstractCore bloc lifecycle operations on `get_abstractcore_host_facade(...)` across local, remote, and hybrid runtimes:
+  - `list_blocs(...)`
+  - `list_bloc_kv_artifacts(...)`
+  - `delete_bloc_kv_artifact(...)`
+  - `prune_bloc_kv_artifacts(...)`
+  - `delete_bloc(...)`
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.23`.
+- Runtime's public docs and AI-readable `llms.txt` / `llms-full.txt` now describe the shipped durable bloc prompt-cache lifecycle boundary, including per-model KV artifacts and explicit cleanup controls.
+
+## [0.4.15] - 2026-05-20
+
+### Added
+- Public AbstractCore Runtime facades for:
+  - discovery/catalog snapshot queries (`get_abstractcore_discovery_facade(...)`)
+  - prompt-cache and model-residency host control operations (`get_abstractcore_host_facade(...)`)
+  - durable run-scoped child-run execution for image, TTS, STT, and direct LLM calls (`get_abstractcore_run_facade(...)`)
+- `EffectType.MODEL_RESIDENCY` with AbstractCore-backed load/list/unload handling and VisualFlow lowering support for runtime-owned model residency control.
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.20`.
+- Local cached-vision discovery now depends on AbstractCore's public `get_local_vision_cache_catalog()` helper instead of private server internals.
+- Local media residency no-op/unsupported responses now complete truthfully with warning/degraded metadata, and media-only results distinguish runtime orchestration identity from the actual media backend identity.
+- Documentation was refreshed for the current Runtime/Core boundary, including root docs, ADR/backlog references, and AI-readable `llms.txt` / `llms-full.txt`.
+
 ## [0.4.14] - 2026-05-19
 
 ### Fixed
@@ -419,7 +448,16 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.7...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.16...HEAD
+[0.4.16]: https://github.com/lpalbou/abstractruntime/compare/v0.4.15...v0.4.16
+[0.4.15]: https://github.com/lpalbou/abstractruntime/compare/v0.4.14...v0.4.15
+[0.4.14]: https://github.com/lpalbou/abstractruntime/compare/v0.4.13...v0.4.14
+[0.4.13]: https://github.com/lpalbou/abstractruntime/compare/v0.4.12...v0.4.13
+[0.4.12]: https://github.com/lpalbou/abstractruntime/compare/v0.4.11...v0.4.12
+[0.4.11]: https://github.com/lpalbou/abstractruntime/compare/v0.4.10...v0.4.11
+[0.4.10]: https://github.com/lpalbou/abstractruntime/compare/v0.4.9...v0.4.10
+[0.4.9]: https://github.com/lpalbou/abstractruntime/compare/v0.4.8...v0.4.9
+[0.4.8]: https://github.com/lpalbou/abstractruntime/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/lpalbou/abstractruntime/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/lpalbou/abstractruntime/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/lpalbou/abstractruntime/compare/v0.4.4...v0.4.5

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.14
+Version: 0.4.16
 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
@@ -23,24 +23,24 @@ Requires-Python: >=3.10
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
 Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.15; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.23; extra == 'abstractcore'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'abstractcore'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'abstractcore'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'abstractcore'
 Provides-Extra: all-apple
-Requires-Dist: abstractcore[all-apple]>=2.13.15; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.23; extra == 'all-apple'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-apple'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-apple'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-apple'
 Provides-Extra: all-gpu
-Requires-Dist: abstractcore[all-gpu]>=2.13.15; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.23; extra == 'all-gpu'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-gpu'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-gpu'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-gpu'
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.13.15; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.23; extra == 'apple'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'apple'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'apple'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'apple'
@@ -50,18 +50,18 @@ Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.13.15; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.23; extra == 'gpu'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'gpu'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'gpu'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'gpu'
 Provides-Extra: mcp-worker
-Requires-Dist: abstractcore[tools]>=2.13.15; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.23; extra == 'mcp-worker'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'mcp-worker'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'mcp-worker'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'mcp-worker'
 Provides-Extra: multimodal
-Requires-Dist: abstractcore[audio,remote,vision,voice]>=2.13.15; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,remote,vision,voice]>=2.13.23; extra == 'multimodal'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'multimodal'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'multimodal'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'multimodal'
@@ -81,7 +81,7 @@ 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.4.10 • **Python:** 3.10+
+**Version:** 0.4.16 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -115,7 +115,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.23 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, and the public local vision-cache catalog helper used by Runtime discovery are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -169,7 +169,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.10)
+## What’s included (v0.4.16)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -193,7 +193,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, cached sessions/prompt cache, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/README.md

@@ -4,7 +4,7 @@
 
 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.4.10 • **Python:** 3.10+
+**Version:** 0.4.16 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -38,7 +38,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.23 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, and the public local vision-cache catalog helper used by Runtime discovery are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -92,7 +92,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.10)
+## What’s included (v0.4.16)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -116,7 +116,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, cached sessions/prompt cache, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/README.md

@@ -24,7 +24,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 
 - `faq.md` — common questions (recommended)
 - `manual_testing.md` — manual smoke tests and how to run the test suite
-- `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, cached sessions/prompt-cache control, media inputs, generated media outputs, and tool approval waits via AbstractCore
+- `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, cached sessions, durable bloc prompt-cache control, media inputs, generated media outputs, and tool approval waits via AbstractCore
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
 
 ## Features (reference)

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/adr/0002_execution_modes_local_remote_hybrid.md

@@ -34,6 +34,6 @@ effect payloads, client construction arguments, or Runtime-owned environment var
 ### See Also
 - Implementation: [`backlog/completed/005_abstractcore_integration.md`](../backlog/completed/005_abstractcore_integration.md)
 - Integration guide: [`integrations/abstractcore.md`](../integrations/abstractcore.md)
-- Gateway install boundary: [`backlog/proposed/2026-05-08_runtime_gateway_install_boundary.md`](../backlog/proposed/2026-05-08_runtime_gateway_install_boundary.md)
+- Gateway install boundary: [`backlog/completed/020_runtime_gateway_install_boundary.md`](../backlog/completed/020_runtime_gateway_install_boundary.md)
 - Code: `src/abstractruntime/integrations/abstractcore/factory.py`
 - Framework ADR: `../../../docs/adr/0033-install-profiles-config-entrypoints-and-server-boundaries.md`

abstractruntime-0.4.16/docs/adr/0004_runtime_owns_run_scoped_media_execution_truth.md

@@ -0,0 +1,44 @@
+## ADR 0004: Runtime owns run-scoped media execution truth
+
+### Status
+Accepted (2026-05-20)
+
+### Context
+Hosts sometimes need to trigger image generation, TTS, or STT for an existing run after the main workflow was already created.
+
+If a host executes that media work directly and only appends ledger-like records afterward, Runtime is no longer the
+source of truth for:
+
+- what was requested;
+- what provider/model path actually executed;
+- which artifacts were produced;
+- how replay should represent the step.
+
+We also observed that local media residency can be misunderstood as successful warmup even when the local execution mode
+is a one-shot subprocess boundary that cannot reuse the previous warm state.
+
+### Decision
+AbstractRuntime owns run-scoped media execution truth.
+
+Specifically:
+
+- Hosts must route run-scoped image/TTS/STT work through Runtime, not execute it out-of-band.
+- The integration provides a public durable run facade that creates Runtime-owned child runs for these operations.
+- Operator/control-plane prompt-cache and model-residency controls remain separate host-oriented helpers and do not
+  create durable run history by themselves.
+- Local unsupported media residency must be reported explicitly with machine-readable fields such as
+  `execution_mode`, `requires_long_lived_server`, and `config_hint`.
+- Media-only normalized results must separate orchestration identity from actual media backend identity via
+  `runtime_provider` / `runtime_model` and `media_provider` / `media_model`.
+
+### Consequences
+- Gateway/other hosts have a clean migration target for run-scoped media routes without synthesizing history after the
+  fact.
+- Ledger and artifact truth stay Runtime-authored and replay-friendly.
+- Optional local media warmup can remain non-fatal while still rendering honestly as a warning/no-op.
+- Consumers can distinguish the runtime orchestration model from the media backend that produced the output.
+
+### See Also
+- Implementation: [`../backlog/completed/023_truthful_local_media_residency_boundaries.md`](../backlog/completed/023_truthful_local_media_residency_boundaries.md)
+- Implementation: [`../backlog/completed/024_runtime_owned_run_scoped_media_execution.md`](../backlog/completed/024_runtime_owned_run_scoped_media_execution.md)
+- Integration guide: [`../integrations/abstractcore.md`](../integrations/abstractcore.md)

abstractruntime-0.4.16/docs/adr/0005_runtime_owns_abstractcore_host_discovery_queries.md

@@ -0,0 +1,55 @@
+## ADR 0005: Runtime owns AbstractCore host discovery queries
+
+### Status
+Accepted (2026-05-20)
+
+### Context
+Gateway and other hosts still need to answer operator and thin-client discovery questions such as:
+
+- which providers are available;
+- which models a provider exposes;
+- what a model's capabilities are;
+- which voice, TTS, STT, and vision catalogs are currently visible;
+- which local vision models are cached.
+
+Before this decision, those reads were often handled outside Runtime by:
+
+- raw HTTP proxying from Gateway to AbstractCore server routes;
+- direct imports of public `abstractcore.*` registries and helpers from Gateway;
+- in at least one case, direct import of a Core-server route implementation.
+
+That creates an inconsistent boundary: execution and some controls go through Runtime, but discovery reads bypass it entirely.
+
+These discovery reads are not durable run truth in the same sense as `LLM_CALL`, `TOOL_CALLS`, or run-scoped media child runs. They are current-environment snapshots that may change between the original query and a later replay.
+
+### Decision
+AbstractRuntime owns the host-facing AbstractCore discovery/query boundary.
+
+Specifically:
+
+- Hosts should ask Runtime for AbstractCore discovery and catalog queries rather than importing Core registries or proxying Core server routes directly.
+- Runtime provides a public discovery facade for host-oriented snapshot queries.
+- These discovery methods are query/snapshot oriented, not durable run effects.
+- Replay or audit consumers should treat discovery results as recorded snapshots when they are persisted by hosts, not as work that should be re-executed automatically.
+- Gateway-local liveness, auth, install diagnostics, and non-Core helper projections may remain host-local.
+
+### Consequences
+- Runtime becomes the single Python integration boundary for AbstractCore execution, control, and discovery surfaces.
+- Gateway can shrink into an HTTP projection layer rather than a second Core integration layer.
+- Discovery results remain semantically distinct from durable run execution truth.
+- Some local discovery implementations may still require Runtime integration code to adapt Core capability helpers or server-backed routes until Core exposes cleaner public helpers.
+
+### Enforcement
+- New Gateway or host adoption work should prefer Runtime facades over direct `abstractcore.*` imports for discovery/catalog routes.
+- Runtime docs should distinguish durable run work, operator controls, and snapshot discovery queries.
+- Direct Gateway reach-through to `runtime._abstractcore_llm_client` remains prohibited when a public facade exists.
+
+### Validation
+- Runtime tests should cover local and remote discovery facade behavior.
+- Documentation should show the public discovery facade entrypoint and its scope.
+- Follow-up backlog work in hosts should remove direct Core discovery bypasses where the facade now covers them.
+
+### See Also
+- Implementation: [`../backlog/planned/026_runtime_host_discovery_facade_for_core_catalogs.md`](../backlog/planned/026_runtime_host_discovery_facade_for_core_catalogs.md)
+- Existing operator controls: [`0004_runtime_owns_run_scoped_media_execution_truth.md`](0004_runtime_owns_run_scoped_media_execution_truth.md)
+- Integration guide: [`../integrations/abstractcore.md`](../integrations/abstractcore.md)

abstractruntime-0.4.16/docs/adr/0006_runtime_owns_durable_abstractcore_bloc_prompt_cache.md

@@ -0,0 +1,104 @@
+## ADR 0006: Runtime owns durable AbstractCore bloc prompt-cache control
+
+### Status
+Accepted (2026-05-20)
+
+### Context
+AbstractCore `2.13.22` added a public durable prompt-cache contract for local
+backends:
+
+- text/file blocs as durable source-of-truth content,
+- provider/model-specific KV artifacts,
+- request-time `prompt_cache_binding` proof for exact reuse.
+
+Before this decision, Runtime only owned:
+
+- best-effort session prompt-cache controls,
+- model-residency controls,
+- discovery/query snapshots,
+- durable run-scoped media execution.
+
+That left a real gap for app-facing durable prompt caching:
+
+- hosts had no public Runtime path for bloc/KV control operations;
+- remote Runtime execution dropped `prompt_cache_binding`;
+- `LLM_CALL` key injection could derive a competing session key even when a
+  durable binding was present;
+- local Runtime had no explicit bloc-store root policy and would otherwise
+  inherit Core defaults implicitly.
+
+### Decision
+AbstractRuntime owns the host-facing durable AbstractCore bloc prompt-cache
+boundary.
+
+Specifically:
+
+- Hosts should use the existing `AbstractCoreHostFacade` for durable bloc/KV
+  prompt-cache controls rather than adding a fourth public facade.
+- The public host surface includes:
+  - `upsert_text_bloc(...)`
+  - `get_bloc_record(...)`
+  - `list_blocs(...)`
+  - `get_bloc_kv_manifest(...)`
+  - `ensure_bloc_kv_artifact(...)`
+  - `load_bloc_kv_artifact(...)`
+  - `list_bloc_kv_artifacts(...)`
+  - `delete_bloc_kv_artifact(...)`
+  - `prune_bloc_kv_artifacts(...)`
+  - `delete_bloc(...)`
+- Runtime mirrors Core's public bloc request/response model instead of
+  inventing a Gateway-local save/load vocabulary.
+- `LLM_CALL.payload.params.prompt_cache_binding` is the public Runtime binding
+  input. Runtime may also accept the local Python alias
+  `expected_prompt_cache_binding`, but it must normalize to
+  `prompt_cache_binding`.
+- When a binding is present:
+  - `binding.key` becomes the effective `prompt_cache_key` when no explicit key
+    was supplied;
+  - mismatched `prompt_cache_key` and `binding.key` fail before provider or
+    server execution;
+  - Runtime must not auto-derive a competing session key;
+  - local session prompt-cache preparation must not mutate the bound key before
+    generation.
+- Local Runtime owns an explicit bloc-root policy:
+  - default local root: `~/.abstractruntime/blocs`
+  - default file-runtime root: `<base_dir>/blocs`
+  - explicit `bloc_root_dir=` overrides are allowed for hosts such as Gateway
+
+### Consequences
+- Runtime becomes the public Python boundary for three distinct prompt-cache
+  tracks:
+  - session prompt-cache reuse,
+  - durable bloc/KV/binding reuse,
+  - local-admin snapshot save/load/list work if promoted later
+- Hosts can expose durable bloc caching without reaching into Core or provider
+  internals.
+- Hosts can also reclaim durable bloc/KV storage through the same Runtime
+  boundary instead of manual filesystem deletion or private Core hooks.
+- Runtime does not silently inherit Core's default `~/.abstractcore/blocs`
+  layout.
+- Provider-private prompt-cache snapshot save/load remains a separate local-admin
+  concern and is not promoted by this decision.
+
+### Enforcement
+- New host adoption work should use `get_abstractcore_host_facade(runtime)` for
+  durable bloc/KV operations.
+- Runtime docs and AI-readable docs must describe the durable bloc track
+  separately from session prompt caching.
+- Runtime code review should reject any new auto-derived prompt-cache behavior
+  that competes with `prompt_cache_binding`.
+
+### Validation
+- Host-facade tests cover delegation and remote route shaping for bloc/KV
+  operations.
+- `LLM_CALL` tests cover binding-only adoption, alias normalization, and
+  mismatch fail-fast behavior.
+- Regression coverage includes local/root-policy tests and the broader
+  AbstractCore Runtime facade suite.
+
+### See Also
+- Implementation: [`../backlog/completed/027_runtime_durable_bloc_prompt_cache_facade.md`](../backlog/completed/027_runtime_durable_bloc_prompt_cache_facade.md)
+- Core binding contract: `../abstractcore/docs/adr/0007-durable-memory-bloc-cache-binding.md`
+- Related Runtime ADRs:
+  - [`0004_runtime_owns_run_scoped_media_execution_truth.md`](0004_runtime_owns_run_scoped_media_execution_truth.md)
+  - [`0005_runtime_owns_abstractcore_host_discovery_queries.md`](0005_runtime_owns_abstractcore_host_discovery_queries.md)

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/adr/README.md

@@ -16,6 +16,9 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 0001 | [Layered Coupling with AbstractCore](0001_layered_coupling_with_abstractcore.md) | Accepted | 2025-12-11 | Kernel stays dependency-light; AbstractCore integration is opt-in |
 | 0002 | [Execution Modes](0002_execution_modes_local_remote_hybrid.md) | Accepted | 2025-12-11 | Support local, remote, and hybrid execution topologies |
 | 0003 | [Provenance Hash Chain](0003_provenance_tamper_evident_hash_chain.md) | Accepted | 2025-12-11 | Tamper-evident ledger first; cryptographic signatures deferred |
+| 0004 | [Runtime Owns Run-Scoped Media Execution Truth](0004_runtime_owns_run_scoped_media_execution_truth.md) | Accepted | 2026-05-20 | Hosts must route run-scoped media execution through Runtime |
+| 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 |
 
 ## Relationship to Backlog
 
@@ -26,6 +29,9 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 0001 | `backlog/completed/005_abstractcore_integration.md` |
 | 0002 | `backlog/completed/005_abstractcore_integration.md` |
 | 0003 | `backlog/completed/007_provenance_hash_chain.md`, `backlog/planned/008_signatures_and_keys.md` |
+| 0004 | `backlog/completed/023_truthful_local_media_residency_boundaries.md`, `backlog/completed/024_runtime_owned_run_scoped_media_execution.md` |
+| 0005 | `backlog/completed/026_runtime_host_discovery_facade_for_core_catalogs.md` |
+| 0006 | `backlog/completed/027_runtime_durable_bloc_prompt_cache_facade.md` |
 
 ## Adding New ADRs
 
@@ -34,4 +40,3 @@ When making a significant architectural decision:
 2. Use the template: Status, Context, Decision, Consequences
 3. Set status to "Accepted" once the decision is final
 4. If superseding an old ADR, update the old one's status to "Superseded by NNNN"
-

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/api.md

@@ -176,21 +176,26 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.12 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.23 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
 Entry points:
 - `create_local_runtime(...)`, `create_remote_runtime(...)`, `create_hybrid_runtime(...)` (`src/abstractruntime/integrations/abstractcore/factory.py`)
+- public discovery facade: `AbstractCoreDiscoveryFacade`, `get_abstractcore_discovery_facade(...)` (`src/abstractruntime/integrations/abstractcore/discovery_facade.py`)
+- public host facade: `AbstractCoreHostFacade`, `get_abstractcore_host_facade(...)` (`src/abstractruntime/integrations/abstractcore/host_facade.py`)
+- public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`)
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
-- prompt-cache control methods on the configured LLM client: `get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules` (`src/abstractruntime/integrations/abstractcore/llm_client.py`)
+- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_vision_provider_models`, `list_cached_vision_models`)
+- host-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
+- run-facade helpers create durable child runs for existing runs (`execute_llm_call`, `generate_image`, `generate_voice`, `transcribe_audio`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
 - `media`: a media path, artifact ref (`{"$artifact": "..."}` or `{"artifact_id": "..."}`), media dict, or list of those
 - `output`: AbstractCore output selector; top-level `outputs` is accepted as a runtime alias
-- `params`: provider/model routing, generation controls, prompt-cache keys, structured-output schema options, and tracing metadata
+- `params`: provider/model routing, generation controls, prompt-cache keys or `prompt_cache_binding`, structured-output schema options, and tracing metadata
 
 Multimodal support:
 - install `abstractruntime[multimodal]` for common AbstractCore media, vision, voice, and audio dependencies
@@ -198,11 +203,16 @@ Multimodal support:
 - remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, speech, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
 - remote transcription requires one audio media item that resolves to a local file path or artifact-backed temporary file
 - generated image/voice/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
+- media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
+- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`, while unsupported local media warmup also reports `execution_mode="local_one_shot_subprocess"` and `requires_long_lived_server=true`
 - Gateway/hosts remain responsible for explicit Core server URLs, Core server auth headers, provider/model defaults, selected Core/capability install profiles, and translation of Gateway-owned env/config into explicit Runtime inputs; Runtime persists only JSON-safe routing metadata and artifact refs
 
 Prompt cache / cached sessions:
 - LLM clients expose cache control methods listed above for host-side preparation and inspection
 - `LLM_CALL.params.prompt_cache_key` selects a cache key for a call; runtime can also derive a session-scoped key from `run.vars["_runtime"]["prompt_cache"]` or the Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE` process default
+- `LLM_CALL.params.prompt_cache_binding` is the durable exact-reuse input for bloc-backed prompt caching; if a binding includes `key`, Runtime adopts it as the effective prompt-cache key and refuses mismatches before provider execution
+- `get_abstractcore_host_facade(...)` also exposes durable bloc helpers (`upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`)
+- local Runtime owns the bloc root policy: `~/.abstractruntime/blocs` by default, `<base_dir>/blocs` for `create_local_file_runtime(...)`, and explicit `bloc_root_dir=...` overrides when needed
 - provider cache/session handles are not durable runtime state and should not be stored in `RunState.vars`
 
 Attachment registration limits:

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-08
-> Version: 0.4.9
+> Updated: 2026-05-20
+> Version: 0.4.16
 > Scope: this describes **what is implemented in this repository**.
 
 AbstractRuntime is a **durable workflow runtime**: it executes workflow graphs as a persisted state machine with explicit waits (user, time, events, jobs, subworkflows). A run can pause for hours/days and resume **without** keeping Python stacks/coroutines alive.
@@ -36,6 +36,7 @@ The boundary is intentionally narrow:
 - Generated binary outputs are written to `ArtifactStore` and returned as `artifact_id` / `artifact_ref`, keeping `RunState.vars` and ledger records bounded and JSON-safe.
 - Remote chat media is sent to AbstractCore Server as provider-ready content arrays, but persisted provider-request metadata redacts data URLs so checkpoints and ledgers do not embed media bytes.
 - Provider sessions and prompt-cache objects are not runtime state. Runtime may carry stable cache keys, while AbstractCore clients/servers manage warm caches.
+- Hosts should use Runtime-owned AbstractCore facades for discovery snapshots, prompt-cache/model-residency control operations, and durable run-scoped media child runs instead of reaching through private runtime attachments or importing Core internals directly.
 - Local execution can use richer AbstractCore capability plugins. Remote and hybrid execution map the common media cases to AbstractCore Server endpoints and OpenAI-compatible content arrays, while hybrid keeps tool execution local.
 - Gateway and other hosts compose Runtime with the desired Core/capability/memory profile. Runtime's base package includes the AbstractMemory contract but not backend extras such as LanceDB; hosts choose storage, embeddings, and readiness policy. Hardware profile extras such as `apple`, `gpu`, `all-apple`, and `all-gpu` cascade through AbstractCore when a host selects them.
 - Remote and hybrid clients use explicit Core server URLs and auth headers supplied by the host. Runtime does not read Gateway auth environment variables for provider/model/auth decisions or treat Gateway bearer tokens as Core server/provider credentials.
@@ -168,7 +169,7 @@ Registered in `Runtime._register_builtin_handlers()` (`src/abstractruntime/core/
 
 ### Host-wired effects
 The kernel defines the protocol; concrete integrations provide handlers:
-- `LLM_CALL`, `TOOL_CALLS`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control, media inputs, generated media outputs, provider-key header routing for remote servers, passthrough tools, and approval-gated local tool execution.
+- `LLM_CALL`, `TOOL_CALLS`, `MODEL_RESIDENCY`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control, discovery/catalog snapshots, model residency, durable run-scoped media child runs, media inputs, generated media outputs, provider-key header routing for remote servers, passthrough tools, and approval-gated local tool execution.
 - `MEMORY_KG_*`: provided by the AbstractMemory bridge (`src/abstractruntime/integrations/abstractmemory/effect_handlers.py`)
 
 ### Reliability: retries + idempotency

{abstractruntime-0.4.14 → abstractruntime-0.4.16}/docs/backlog/README.md

@@ -1,8 +1,11 @@
 # Backlog (maintainers)
 
+This README currently serves as the backlog overview for this repository.
+
 This folder contains a structured backlog used during development. Items are grouped as:
 - `completed/` — implemented work items (what shipped, with implementation pointers)
-- `planned/` — future work proposals
+- `planned/` — committed future work items that still match current runtime reality
+- `proposed/` — uncommitted ideas and follow-on risks worth preserving
 - `deprecated/` — historical backlog notes (superseded)
 
 If you are new to the project, start with `../README.md` and `../architecture.md` instead.
@@ -24,6 +27,15 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 012 | `completed/012_run_store_query_and_scheduler_support.md` |
 | 013 | `completed/013_effect_retries_and_idempotency.md` |
 | 016 | `completed/016_runtime_aware_parameters.md` |
+| 019 | `completed/019_runtime_host_facade_for_core_operator_surfaces.md` |
+| 020 | `completed/020_runtime_gateway_install_boundary.md` |
+| 021 | `completed/021_runtime_gateway_env_namespace_cleanup.md` |
+| 022 | `completed/022_model_residency_control_plane.md` |
+| 023 | `completed/023_truthful_local_media_residency_boundaries.md` |
+| 024 | `completed/024_runtime_owned_run_scoped_media_execution.md` |
+| 026 | `completed/026_runtime_host_discovery_facade_for_core_catalogs.md` |
+| 027 | `completed/027_runtime_durable_bloc_prompt_cache_facade.md` |
+| 028 | `completed/028_runtime_bloc_kv_lifecycle_and_pruning.md` |
 
 ## Planned
 
@@ -31,9 +43,16 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 |----|------|
 | 008 | `planned/008_signatures_and_keys.md` |
 | 014 | `planned/014_remote_tool_worker_executor.md` |
-| 015 | `planned/015_agent_integration_improvements.md` |
 | 017 | `planned/017_limit_warnings_and_observability.md` |
 | 018 | `planned/018_workspace_access_policy_for_media_and_tools.md` |
+| 025 | `planned/025_runtime_retention_and_purge_contract.md` |
+
+## Proposed
+
+| Date | Item |
+|------|------|
+| 2026-05-20 | `proposed/2026-05-20_agent_runtime_convenience_constructor.md` |
+| 2026-05-20 | `proposed/2026-05-20_runtime_local_admin_prompt_cache_save_load.md` |
 
 ## Deprecated