AbstractRuntime 0.4.19__tar.gz → 0.4.21__tar.gz

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.21] - 2026-05-22
+
+### Added
+- Public model-residency capability discovery on the AbstractCore host facade so hosts can branch on task support before showing warmup controls.
+- Durable run-facade support for image edits through `edit_image(...)`.
+- First-class VisualFlow lowering for `edit_image` / `image_to_image` and `generate_music` media nodes.
+- A focused troubleshooting guide and repository code of conduct in the core documentation set.
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.25`, matching the released Core validation for task-aware text/image/TTS/STT residency.
+- Remote Runtime media execution now routes image edits through AbstractCore Server `/v1/images/edits` or provider-scoped `/{provider}/v1/images/edits`.
+- Runtime no longer auto-derives session prompt-cache keys for non-text generated-media or transcription output selectors; explicit `prompt_cache_binding` remains supported.
+- Local and remote model-residency responses now fail closed unless Core-owned residency truth verifies the loaded state.
+- Runtime docs, backlog, ADR links, and AI-readable `llms.txt` / `llms-full.txt` now reflect the Core-owned residency boundary and current media node support.
+
+### Fixed
+- Artifact-backed media resolution now preserves image/audio role metadata without failing when content type metadata is absent.
+
+## [0.4.20] - 2026-05-21
+
+### Added
+- Runtime now exposes a public host-local prompt-cache export/import admin surface on `get_abstractcore_host_facade(...)`:
+  - `list_prompt_cache_exports(...)`
+  - `prompt_cache_export(...)`
+  - `prompt_cache_import(...)`
+
+### Changed
+- Local Runtime now owns the prompt-cache export root/catalog policy:
+  - `~/.abstractruntime/prompt_cache_exports` by default
+  - `<base_dir>/prompt_cache_exports` for `create_local_file_runtime(...)`
+  - exact provider/model partitioning with Runtime-managed metadata sidecars
+- Remote and hybrid runtimes now fail honestly for prompt-cache export/import admin with a structured local-only response instead of implying server-side support.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now document the secondary host-local export/import contract distinctly from the primary durable bloc/binding prompt-cache path.
+
 ## [0.4.19] - 2026-05-21
 
 ### Added
@@ -489,7 +523,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.19...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.21...HEAD
+[0.4.21]: https://github.com/lpalbou/abstractruntime/compare/v0.4.20...v0.4.21
+[0.4.20]: https://github.com/lpalbou/abstractruntime/compare/v0.4.19...v0.4.20
 [0.4.19]: https://github.com/lpalbou/abstractruntime/compare/v0.4.18...v0.4.19
 [0.4.18]: https://github.com/lpalbou/abstractruntime/compare/v0.4.17...v0.4.18
 [0.4.17]: https://github.com/lpalbou/abstractruntime/compare/v0.4.16...v0.4.17

abstractruntime-0.4.21/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our Standard
+
+This project is maintained as a professional software collaboration. Contributors, maintainers, and users are expected
+to keep discussions respectful, technically focused, and welcoming to people with different backgrounds and experience
+levels.
+
+Examples of expected behavior:
+
+- Use clear, constructive language when giving feedback.
+- Assume good faith while still asking for evidence and reproducible details.
+- Keep disagreements focused on the code, docs, design, or release process.
+- Respect privacy and do not publish private contact details, credentials, logs, or user data.
+
+Examples of unacceptable behavior:
+
+- Harassment, threats, insults, or discriminatory language.
+- Sustained off-topic disruption of issues, pull requests, or discussions.
+- Publishing private information without explicit permission.
+- Pressuring maintainers or contributors to bypass safety, security, or release checks.
+
+## Reporting
+
+Report conduct concerns privately to the maintainer contact listed in the package metadata or through the repository
+owner's GitHub profile. Include the relevant links, screenshots, or context when possible.
+
+Maintainers may remove comments, close threads, block accounts, or restrict repository access when needed to protect the
+project and its contributors.
+

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.19
+Version: 0.4.21
 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.24; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.25; 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.24; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.25; 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.24; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.25; 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.24; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.25; 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.24; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.25; 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.24; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.25; 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,music,remote,vision,voice]>=2.13.24; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,music,remote,vision,voice]>=2.13.25; 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.19 • **Python:** 3.10+
+**Version:** 0.4.21 • **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.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.
+The `abstractcore` extra installs AbstractCore 2.13.25 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, lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, task-aware model residency for text/image/TTS/STT, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.8` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, or 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.19)
+## What’s included (v0.4.21)
 
 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, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
@@ -233,6 +233,7 @@ sr = create_scheduled_runtime(
 | [API Reference](docs/api.md) | Public API surface (imports + pointers) |
 | [Docs Index](docs/README.md) | Full docs map (guides + reference) |
 | [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Troubleshooting](docs/troubleshooting.md) | Symptom-oriented setup, runtime, and integration fixes |
 | [Architecture](docs/architecture.md) | Component map + diagrams |
 | [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
 | [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
@@ -244,6 +245,7 @@ sr = create_scheduled_runtime(
 | [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
 | [Changelog](CHANGELOG.md) | Release notes |
 | [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Contributor conduct expectations |
 | [Security](SECURITY.md) | Responsible vulnerability reporting |
 | [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
 | [ROADMAP](ROADMAP.md) | Prioritized next steps |

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/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.19 • **Python:** 3.10+
+**Version:** 0.4.21 • **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.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.
+The `abstractcore` extra installs AbstractCore 2.13.25 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, lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, task-aware model residency for text/image/TTS/STT, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.8` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, or 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.19)
+## What’s included (v0.4.21)
 
 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, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
@@ -156,6 +156,7 @@ sr = create_scheduled_runtime(
 | [API Reference](docs/api.md) | Public API surface (imports + pointers) |
 | [Docs Index](docs/README.md) | Full docs map (guides + reference) |
 | [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Troubleshooting](docs/troubleshooting.md) | Symptom-oriented setup, runtime, and integration fixes |
 | [Architecture](docs/architecture.md) | Component map + diagrams |
 | [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
 | [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
@@ -167,6 +168,7 @@ sr = create_scheduled_runtime(
 | [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
 | [Changelog](CHANGELOG.md) | Release notes |
 | [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Contributor conduct expectations |
 | [Security](SECURITY.md) | Responsible vulnerability reporting |
 | [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
 | [ROADMAP](ROADMAP.md) | Prioritized next steps |

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/README.md

@@ -18,11 +18,13 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `getting-started.md` — first steps (recommended)
 - `api.md` — public API surface (imports + pointers)
 - `architecture.md` — how the runtime is structured (with diagrams)
+- `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
 - `proposal.md` — design goals and scope boundaries
 
 ## Guides
 
 - `faq.md` — common questions (recommended)
+- `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
 - `manual_testing.md` — manual smoke tests and how to run the test suite
 - `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)
@@ -39,6 +41,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 ## Maintainers
 
 - `../CHANGELOG.md` — release notes
+- `../CODE_OF_CONDUCT.md` — contributor conduct expectations
 - `../CONTRIBUTING.md` — how to build/test and submit changes
 - `../SECURITY.md` — responsible vulnerability reporting
 - `../ACKNOWLEDGMENTS.md` — credits

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/adr/0005_runtime_owns_abstractcore_host_discovery_queries.md

@@ -50,6 +50,6 @@ Specifically:
 - 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)
+- Implementation: [`../backlog/completed/026_runtime_host_discovery_facade_for_core_catalogs.md`](../backlog/completed/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.21/docs/adr/0007_runtime_relays_core_owned_model_residency_truth.md

@@ -0,0 +1,60 @@
+## ADR 0007: Runtime relays Core-owned model residency truth
+
+### Status
+Accepted (2026-05-21)
+
+### Context
+Hosts and operator UIs ask Runtime whether a model is loaded. That question can
+mean different things:
+
+- a configured default provider/model;
+- a cached Runtime or gateway client;
+- a provider-owned model actually resident in memory.
+
+Only AbstractCore owns provider implementations and provider-specific loaded
+instance knowledge. Runtime can create and cache AbstractCore clients, but that
+does not prove provider residency. HTTP-backed local providers, provider
+servers, and native in-process providers all have different truth sources.
+
+### Decision
+AbstractRuntime relays model-residency truth from AbstractCore. It does not
+produce provider-residency truth itself.
+
+Specifically:
+
+- Runtime may expose its own cache/configuration state with fields such as
+  `runtime_cached` and `cache_state`.
+- Runtime may call public AbstractCore integration contracts such as
+  `get_model_residency(...)` on a Core provider object or remote
+  `/acore/models/*` responses.
+- Runtime must not call provider-native HTTP APIs, provider-specific unload/list
+  methods, or private provider internals to establish residency.
+- Runtime must not infer loaded state from provider names, provider metadata,
+  `local_provider`, `base_url`, ports, model catalogs, default configuration, or
+  the existence of a cached client.
+- If AbstractCore cannot verify provider residency, Runtime must fail closed:
+  `loaded=false`, `resident=false`, `provider_residency_verified=false`, and an
+  explicit unknown/provider-unverified state.
+
+### Consequences
+- Gateway, Flow, and other hosts can distinguish a cached Runtime client from a
+  truly provider-loaded model.
+- Positive `loaded=true` in Runtime local mode requires a Core-owned positive
+  provider-residency response.
+- Provider-specific loaded-instance work belongs in AbstractCore providers or
+  capability plugins, not in Runtime.
+- Some local rows remain visible as cache/configuration state while correctly
+  reporting that provider residency is unknown or not loaded.
+
+### Enforcement
+- Reviews should reject Runtime provider-name lists, `base_url` heuristics, and
+  direct provider-native residency probes.
+- Runtime tests should cover verified loaded, verified not-loaded, and unknown
+  provider-residency paths.
+- Backlog items that need new residency truth must start with an AbstractCore
+  contract or a Core backlog item.
+
+### See Also
+- Runtime backlog: [`../backlog/completed/0035_model_residency_provider_truth_for_local_http_clients.md`](../backlog/completed/0035_model_residency_provider_truth_for_local_http_clients.md)
+- Runtime backlog: [`../backlog/proposed/0036_local_media_residency_bridge_to_core_residency.md`](../backlog/proposed/0036_local_media_residency_bridge_to_core_residency.md)
+- Core companion ADR: [`../../../abstractcore/docs/adr/0008-provider-owned-model-residency-truth.md`](../../../abstractcore/docs/adr/0008-provider-owned-model-residency-truth.md)

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/adr/README.md

@@ -19,6 +19,7 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 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 |
+| 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 |
 
 ## Relationship to Backlog
 
@@ -32,6 +33,7 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 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` |
+| 0007 | `backlog/completed/0035_model_residency_provider_truth_for_local_http_clients.md`, `backlog/proposed/0036_local_media_residency_bridge_to_core_residency.md` |
 
 ## Adding New ADRs
 

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/api.md

@@ -156,6 +156,10 @@ VisualFlow compiler helpers are available from `abstractruntime.visualflow_compi
 - `visual_to_flow(...)` lowers VisualFlow into the internal Flow IR.
 - `compile_visualflow(...)` and `compile_visualflow_tree(...)` compile VisualFlow JSON into executable `WorkflowSpec` objects.
 
+VisualFlow authoring note (media nodes):
+- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
+- Generated-media and transcription nodes lower to a durable `EffectType.LLM_CALL` with an `output` selector (for example `{"modality":"music","task":"music_generation"}`), while `listen_voice` lowers to `WAIT_EVENT`. Hosts should persist the authoring node type rather than pre-lowering to `llm_call`.
+
 Public bundle APIs are exported from `src/abstractruntime/workflow_bundle/__init__.py` and re-exported in `src/abstractruntime/__init__.py`:
 - open: `open_workflow_bundle(...)`
 - registry: `WorkflowBundleRegistry`
@@ -176,7 +180,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.24 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.25 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -190,9 +194,10 @@ Entry points:
 - 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_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`)
-- host-facade client 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`)
+- host-facade client 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`, `get_model_residency_capabilities`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
+- host-local prompt-cache export/import admin also lives on the host facade and client delegation layer (`list_prompt_cache_exports`, `prompt_cache_export`, `prompt_cache_import`) and is intentionally local-only
 - host-facade email helpers delegate to Runtime's host-local comms facade/export layer (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
-- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -203,17 +208,18 @@ Entry points:
 Multimodal support:
 - 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, 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 and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, 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/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`
+- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; unsupported local media warmup for `image_generation`, `tts`, `stt`, and `music_generation` reports `requires_long_lived_server=true`, and image generation also reports `execution_mode="local_one_shot_subprocess"`
 - 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
+- Runtime only auto-derives session prompt-cache keys for text/chat calls; non-text output selectors such as image, voice, music, and transcription keep explicit `prompt_cache_binding` support but do not receive an inferred cache key
 - `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`

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-21
-> Version: 0.4.19
+> Updated: 2026-05-22
+> Version: 0.4.21
 > 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.

{abstractruntime-0.4.19 → abstractruntime-0.4.21}/docs/backlog/README.md

@@ -10,6 +10,14 @@ 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.
 
+## Counts
+
+- Planned: 5
+- Proposed: 3
+- Completed: 28
+- Deprecated: 13
+- Recurrent: 0
+
 ## Next recommended work
 
 1. `planned/018_workspace_access_policy_for_media_and_tools.md`
@@ -18,10 +26,15 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 2. `planned/014_remote_tool_worker_executor.md`
    The public ToolExecutor path is still the larger follow-on after the current
    Gateway boundary cleanup.
-3. `proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md`
+3. `proposed/0036_local_media_residency_bridge_to_core_residency.md`
+   Local Runtime media residency should relay live Core-owned truth for image/TTS/STT or stay unsupported when no
+   Core-owned local media residency facade is wired.
+4. `proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md`
    The comms/Telegram boundary cleanup is now complete; the remaining lower
    pressure follow-up is a Runtime-owned tool-spec surface if Gateway or the
    MCP worker still need one after adoption.
+5. `proposed/0038_core_server_pool_residency_affinity.md`
+   Future-only topology item for multiple AbstractCore servers, server identity, and residency routing affinity.
 
 ## Completed
 
@@ -52,6 +65,9 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 029 | `completed/029_runtime_music_generation_and_discovery_via_abstractcore.md` |
 | 0030 | `completed/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md` |
 | 0032 | `completed/0032_runtime_durable_outbound_comms_truth.md` |
+| 0033 | `completed/0033_runtime_host_local_prompt_cache_export_import_surface.md` |
+| 0035 | `completed/0035_model_residency_provider_truth_for_local_http_clients.md` |
+| 0037 | `completed/0037_visualflow_generate_music_node_compiler_parity.md` |
 
 ## Planned
 
@@ -67,10 +83,12 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 | 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` |
+| 0036 | `proposed/0036_local_media_residency_bridge_to_core_residency.md` |
+| 0038 | `proposed/0038_core_server_pool_residency_affinity.md` |
 
 ## Deprecated
 
 See `deprecated/DEPRECATED_README.md` for context on the deprecated backlog set.
+Recent deprecation:
+- `deprecated/0034_agent_runtime_convenience_constructor.md`