AbstractRuntime 0.4.15__tar.gz → 0.4.17__tar.gz

{abstractruntime-0.4.15 → abstractruntime-0.4.17}/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.17] - 2026-05-21
+
+### Added
+- Runtime now surfaces AbstractCore-backed music through the same durable boundary as other generated artifacts:
+  - host discovery snapshot methods for music providers/models
+  - durable run-scoped `generate_music(...)`
+  - artifact-backed normalized music outputs for local and remote Runtime paths
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.24`.
+- The `multimodal` extra now installs `abstractcore[remote,vision,voice,audio,music]>=2.13.24`, which includes AbstractMusic's lightweight remote ACE backend path via `abstractmusic>=0.1.4`.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now describe the shipped music boundary and the current `0030` Gateway cleanup scope more accurately.
+
+## [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
@@ -434,7 +461,9 @@ 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.15...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.17...HEAD
+[0.4.17]: https://github.com/lpalbou/abstractruntime/compare/v0.4.16...v0.4.17
+[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

{abstractruntime-0.4.15 → abstractruntime-0.4.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.15
+Version: 0.4.17
 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.20; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.24; 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.20; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.24; 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.20; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.24; 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.20; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.24; 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.20; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.24; 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.20; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.24; 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.20; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,music,remote,vision,voice]>=2.13.24; 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.15 • **Python:** 3.10+
+**Version:** 0.4.17 • **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.20 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, 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.
+The `abstractcore` extra installs AbstractCore 2.13.24 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, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.4` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, and music 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.15)
+## What’s included (v0.4.17)
 
 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, `MODEL_RESIDENCY`, public discovery/host/run facades, 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 image/voice/music outputs, 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.15 → abstractruntime-0.4.17}/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.15 • **Python:** 3.10+
+**Version:** 0.4.17 • **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.20 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, 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.
+The `abstractcore` extra installs AbstractCore 2.13.24 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, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.4` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, and music 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.15)
+## What’s included (v0.4.17)
 
 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, `MODEL_RESIDENCY`, public discovery/host/run facades, 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 image/voice/music outputs, 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.15 → abstractruntime-0.4.17}/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.17/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.15 → abstractruntime-0.4.17}/docs/adr/README.md

@@ -18,6 +18,7 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 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
 
@@ -30,6 +31,7 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 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
 

{abstractruntime-0.4.15 → abstractruntime-0.4.17}/docs/api.md

@@ -125,7 +125,7 @@ Key types:
 Artifacts are used by:
 - offloading wrappers (`src/abstractruntime/storage/offloading.py`)
 - evidence capture (`docs/evidence.md`, `src/abstractruntime/evidence/recorder.py`)
-- AbstractCore media integration: input artifact refs can be materialized for LLM calls, and generated image/voice/audio outputs are stored as artifact refs
+- AbstractCore media integration: input artifact refs can be materialized for LLM calls, and generated image/voice/music/audio outputs are stored as artifact refs
 
 ## Snapshots / bookmarks
 
@@ -176,7 +176,7 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.20 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.24 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -187,22 +187,22 @@ Entry points:
 - 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`)
-- 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`, `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`)
+- 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_music_providers`, `list_music_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`, `generate_music`, `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
+- install `abstractruntime[multimodal]` for common AbstractCore media, vision, voice, audio, and music dependencies
 - local clients call AbstractCore's unified `generate(..., media=..., output=...)`
-- 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 and hybrid clients support AbstractCore Server chat media content arrays plus image generation, speech, music generation, 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
+- generated image/voice/music/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
@@ -210,6 +210,9 @@ Multimodal support:
 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.15 → abstractruntime-0.4.17}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-20
-> Version: 0.4.15
+> Updated: 2026-05-21
+> Version: 0.4.17
 > 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.
@@ -28,7 +28,7 @@ Key invariants (enforced by code, not convention):
 
 ## AbstractCore capability boundary
 
-AbstractRuntime's job is persistence and orchestration. AbstractCore owns model/provider capability execution: chat, structured output, cached sessions/prompt cache, media input analysis, image generation, voice/audio generation, transcription, and future modalities such as music or video.
+AbstractRuntime's job is persistence and orchestration. AbstractCore owns model/provider capability execution: chat, structured output, cached sessions/prompt cache, media input analysis, image generation, voice/audio generation, music generation, transcription, and future modalities such as video.
 
 The boundary is intentionally narrow:
 - Workflow nodes request model work with `EffectType.LLM_CALL`; the runtime persists the request/result and delegates execution to the configured AbstractCore client.

{abstractruntime-0.4.15 → abstractruntime-0.4.17}/docs/backlog/README.md

@@ -10,6 +10,19 @@ This folder contains a structured backlog used during development. Items are gro
 
 If you are new to the project, start with `../README.md` and `../architecture.md` instead.
 
+## Next recommended work
+
+1. `planned/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md`
+   This is the narrow Runtime work that unblocks the last high-pressure direct
+   `abstractcore` imports in Gateway for comms/email and Telegram without
+   reopening the already-completed media/discovery boundary work.
+2. `planned/018_workspace_access_policy_for_media_and_tools.md`
+   Keep workspace and tool policy explicit while Gateway extracts its local
+   workspace helpers.
+3. `planned/014_remote_tool_worker_executor.md`
+   The public ToolExecutor path is still the larger follow-on after the current
+   Gateway boundary cleanup.
+
 ## Completed
 
 | ID | Item |
@@ -34,6 +47,9 @@ If you are new to the project, start with `../README.md` and `../architecture.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` |
+| 029 | `completed/029_runtime_music_generation_and_discovery_via_abstractcore.md` |
 
 ## Planned
 
@@ -44,13 +60,15 @@ If you are new to the project, start with `../README.md` and `../architecture.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` |
+| 0030 | `planned/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md` |
 
 ## Proposed
 
-| Date | Item |
-|------|------|
+| ID | 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` |
+| 0031 | `proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md` |
 
 ## Deprecated
 

{abstractruntime-0.4.15 → abstractruntime-0.4.17}/docs/backlog/completed/020_runtime_gateway_install_boundary.md

@@ -18,7 +18,7 @@ the base package, while still exposing explicit extras and profile cascades for
   `abstractruntime[multimodal]`.
 - Runtime now exposes explicit profile-cascade extras (`apple`, `gpu`, `all-apple`, `all-gpu`) instead of requiring
   hosts to guess how to align local-engine install profiles.
-- The package metadata floor has since advanced to `abstractcore>=2.13.20`; the original completion landed on an older
+- The package metadata floor has since advanced to `abstractcore>=2.13.23`; the original completion landed on an older
   2.13.12-aligned floor and was later tightened without changing the boundary itself.
 - Regression tests cover package metadata, optional-stack imports, and the rule that Gateway env/auth does not leak
   into Runtime's remote AbstractCore client boundary.
@@ -79,7 +79,7 @@ through extras, and tests prove the packaging/import boundary.
 
 ### Residual risks
 
-- Version-floor references in historical backlog text had drifted behind the current `abstractcore>=2.13.20` baseline.
+- Version-floor references in historical backlog text had drifted behind the current `abstractcore>=2.13.23` baseline.
   That drift is now explicit here, but other historical backlog notes may still mention `2.13.12`.
 - This item validates the package/import boundary, not every higher-level deployment profile that Gateway may choose.
 

abstractruntime-0.4.17/docs/backlog/completed/027_runtime_durable_bloc_prompt_cache_facade.md

@@ -0,0 +1,177 @@
+# 027 Runtime Durable Bloc Prompt-Cache Facade
+
+## Metadata
+- Created: 2026-05-20
+- Status: Completed
+- Completed: 2026-05-20
+- Origin: promoted from `proposed/2026-05-20_runtime_durable_bloc_prompt_cache_facade.md`
+
+## Goal
+
+Give hosts a public Runtime-owned path for durable AbstractCore bloc/KV
+prompt-cache operations and make normal Runtime `LLM_CALL` execution binding
+aware, so apps can use exact prompt-cache reuse across restarts without
+reaching into Core or provider internals.
+
+## What Shipped
+
+- Extended `AbstractCoreHostFacade` with durable bloc/KV methods:
+  - `upsert_text_bloc(...)`
+  - `get_bloc_record(...)`
+  - `get_bloc_kv_manifest(...)`
+  - `ensure_bloc_kv_artifact(...)`
+  - `load_bloc_kv_artifact(...)`
+- Wired those methods through local, multi-local, remote, and hybrid
+  AbstractCore Runtime clients.
+- Forwarded `prompt_cache_binding` through remote Runtime execution.
+- Made Runtime `LLM_CALL` key injection binding-aware:
+  - normalize `expected_prompt_cache_binding` to `prompt_cache_binding`
+  - adopt `binding.key` when no explicit key is supplied
+  - fail fast on mismatched explicit key vs binding key
+  - skip derived session-key injection when a binding is present
+- Added an explicit local Runtime bloc-root policy:
+  - default local root: `~/.abstractruntime/blocs`
+  - default file-runtime root: `<base_dir>/blocs`
+  - optional `bloc_root_dir=...` override
+- Raised the AbstractCore dependency floor to `2.13.22`.
+
+## Current Code Pointers
+
+- `src/abstractruntime/integrations/abstractcore/host_facade.py`
+- `src/abstractruntime/integrations/abstractcore/llm_client.py`
+- `src/abstractruntime/integrations/abstractcore/effect_handlers.py`
+- `src/abstractruntime/integrations/abstractcore/factory.py`
+- `tests/test_abstractcore_host_facade.py`
+- `tests/test_prompt_cache_modules.py`
+- `tests/test_remote_llm_client.py`
+- `tests/test_packaging_extras.py`
+- `docs/adr/0006_runtime_owns_durable_abstractcore_bloc_prompt_cache.md`
+
+## Validation
+
+Focused validation run on 2026-05-20:
+
+- `pytest -q tests/test_abstractcore_host_facade.py tests/test_remote_llm_client.py tests/test_prompt_cache_modules.py tests/test_packaging_extras.py`
+- Result: `40 passed in 0.16s`
+
+Broader regression slice:
+
+- `pytest -q tests/test_abstractcore_discovery_facade.py tests/test_abstractcore_host_facade.py tests/test_abstractcore_run_facade.py tests/test_model_residency_control_plane.py tests/test_multimodal_abstractcore_integration.py tests/test_remote_llm_client.py tests/test_prompt_cache_modules.py tests/test_packaging_extras.py tests/test_runtime_install_boundary.py`
+- Result: `108 passed in 0.37s`
+
+Additional validation:
+
+- `python -m py_compile src/abstractruntime/integrations/abstractcore/llm_client.py src/abstractruntime/integrations/abstractcore/host_facade.py src/abstractruntime/integrations/abstractcore/factory.py src/abstractruntime/integrations/abstractcore/effect_handlers.py tests/test_abstractcore_host_facade.py tests/test_prompt_cache_modules.py tests/test_remote_llm_client.py tests/test_packaging_extras.py`
+- Result: clean
+
+Practical proof points from the shipped tests:
+
+- Remote Runtime now forwards `prompt_cache_binding` in chat-generation
+  requests and preserves the exact binding payload.
+- Remote Runtime omits local loaded-runtime selectors when bloc/KV calls are
+  explicitly proxied with `base_url=...`.
+- Local Runtime bloc helpers use the Runtime-owned bloc root and return
+  structured artifact metadata including `prompt_cache_binding`.
+- Binding-aware execution accepts binding-only requests, preserves matching
+  explicit keys, rejects mismatches before provider execution, and does not
+  derive a competing session key for keyless bindings.
+
+## Completion report
+
+### Date
+
+2026-05-20
+
+### Summary
+
+Runtime now owns the app-facing durable bloc prompt-cache boundary for
+AbstractCore-backed hosts. Hosts can create or read durable blocs, ensure or
+load KV artifacts, and then execute ordinary `LLM_CALL`s with a
+`prompt_cache_binding` through Runtime rather than relying on provider-private
+snapshot hacks.
+
+### Behavior changes
+
+- `get_abstractcore_host_facade(runtime)` is now the public Runtime surface for
+  durable bloc/KV prompt-cache operations in addition to normal prompt-cache
+  control and model residency.
+- Remote Runtime no longer drops `prompt_cache_binding`.
+- Local Runtime no longer injects or mutates a competing session cache key when
+  a durable binding is present.
+- File-backed local runtimes now default bloc storage under `<base_dir>/blocs`
+  instead of implicitly inheriting Core defaults.
+
+### Review and refinement cycles
+
+- Cycle 1: design review pushed three improvements before closeout:
+  - keep the work inside the existing host facade instead of adding a fourth
+    public facade
+  - define an explicit Runtime-owned bloc root policy instead of inheriting
+    Core defaults silently
+  - make `LLM_CALL` execution binding-aware, not just host-control aware
+- Refinements shipped:
+  - extended `AbstractCoreHostFacade`
+  - added explicit local/file-runtime bloc-root defaults
+  - normalized and enforced binding precedence in effect handling
+- Cycle 2: broader regression and compatibility review found one meaningful
+  issue:
+  - `MultiLocalAbstractCoreLLMClient` could break monkeypatched or older test
+    doubles that do not accept the new `bloc_root_dir` constructor kwarg
+- Final refinement shipped:
+  - added a narrow compatibility fallback in `_get_client(...)` for local
+    client call sites that reject only the new `bloc_root_dir` kwarg
+- Cycle 3: independent implementation review found one real remote-path
+  blocker plus two coverage gaps:
+  - remote bloc/KV proxy calls must not carry local selector fields when
+    `base_url` is supplied
+  - the direct-client `expected_prompt_cache_binding` alias path needed its own
+    regression
+  - the primary `MultiLocal` local deployment path and keyless-binding
+    precedence needed direct coverage
+- Final refinements shipped:
+  - `base_url` now wins cleanly for remote bloc/KV proxy calls
+  - direct client binding-alias normalization is covered and aligned with
+    Runtime semantics
+  - tests now cover the factory/local `MultiLocal` durable-bloc path and the
+    keyless-binding no-derived-key rule
+- Final blocker-only review reported no blockers.
+
+### Tests
+
+- `tests/test_abstractcore_host_facade.py`
+- `tests/test_prompt_cache_modules.py`
+- `tests/test_remote_llm_client.py`
+- `tests/test_packaging_extras.py`
+- regression coverage alongside:
+  - `tests/test_abstractcore_discovery_facade.py`
+  - `tests/test_abstractcore_run_facade.py`
+  - `tests/test_model_residency_control_plane.py`
+  - `tests/test_multimodal_abstractcore_integration.py`
+  - `tests/test_runtime_install_boundary.py`
+
+### Docs
+
+- `README.md`
+- `docs/README.md`
+- `docs/getting-started.md`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `llms.txt`
+- `llms-full.txt`
+- `docs/adr/0006_runtime_owns_durable_abstractcore_bloc_prompt_cache.md`
+
+### Residual risks
+
+- This repo now provides the Runtime-side durable bloc contract, but sibling
+  hosts still need to adopt it instead of provider-private snapshot flows where
+  those still exist.
+- Provider-native snapshot save/load remains a separate local-admin concern and
+  should not be confused with the primary durable bloc contract.
+
+### Follow-ups
+
+- Evaluate whether Gateway should expose app-facing durable bloc routes on top
+  of this Runtime surface.
+- Keep the separate local-admin snapshot item proposed until there is a real
+  operator need beyond durable bloc/KV/binding reuse.