DOC10_Orchestration_Integration_Ledger_R10_Consolidated.md

Current Specs/DOC10/DOC10_Orchestration_Integration_Ledger_R10_Consolidated.md

Generated 2026-06-09T01:23:58.539Z from commit dbaa25962edc11ab30e8d4ca1715f9ae5bf77331. Worktree: clean.

Open text page · Open raw txt · Open path URL

# DOC10 Orchestration Integration Ledger — R10 [Consolidated Current]

## Revision Lineage (must persist in all later versions)

Based on DOC10 Orchestration Integration Ledger R9 plus DOC10 Orchestration Integration Ledger R9.1 (Topology Control Plane). This consolidated current version fully subsumes those prior operative versions.

## Consolidation Rule

If an inherited baseline statement conflicts with a later merged revision block in this same file, the later merged revision block governs.

## Included Source Chain

- 1. Inherited Baseline — DOC10 Orchestration Integration Ledger R9 — source file: `DOC10_ORCHESTRATION_INTEGRATION_LEDGER_R9.md`
- 2. Merged Revision — DOC10 Orchestration Integration Ledger R9.1 (Topology Control Plane) — source file: `DOC10_ORCHESTRATION_INTEGRATION_LEDGER_R9_1_Topology_Control_Plane.md`

---

# Part 1 — Inherited Baseline — DOC10 Orchestration Integration Ledger R9

# DOC10 Orchestration Integration Ledger

Version: R9
Status: merged master ledger
Supersedes:
- DOC10 Orchestration Integration Ledger R8

Absorbs / retires as active tracker:
- DOC12 Inter-Document Integration Addendum R2 (fully merged into this ledger; retain only as historical provenance until owner-doc rows are accepted/rejected)

## Why this ledger exists

DOC10, DOC11, DOC12, DOC13, DOC15, and related owner docs generate obligations for many other specs and implementation surfaces.
This ledger is the single suite-wide coordination record for those obligations so they do not disappear into chat history, red-team packets, or temporary addenda.

This ledger exists to prevent:
- cross-doc drift,
- duplicate facades and schemas,
- missing hooks,
- UI controls that are not wired to backend operations,
- room/chat/runtime semantics being specified in one place and forgotten in another,
- auth / capability / context / cost / abort truth going decorative,
- hidden system-agent bus behavior being confused with visible room behavior,
- OpenClaw release changes being noticed in one spec but never reflected in others,
- migration drift between canonical specs and the actual implementation plan.

## 0) No-drift rules

1. This ledger is the canonical follow-on list for DOC10 + DOC11 + DOC12 + related owner-doc generated cross-document obligations.
2. If a future DOC10, DOC11, DOC12, DOC13, DOC15, or major companion revision creates a cross-doc dependency, it must be added here.
3. If a future implementation chooses a different canonical schema than the one listed here, the owner spec and this ledger must both be updated together.
4. A path/control may not ship unless the ledger can answer:
- what envelope/payload is emitted,
- what handler consumes it,
- what owner doc mutates durable state,
- what telemetry is emitted,
- what UI state refreshes.
5. For any live execution path there must be one authoritative context-assembly owner.
6. Gateway handoff without correlated reverse telemetry is non-compliant.
7. A cancel/terminate control that does not reach the real downstream runtime is non-compliant.
8. A visible multi-agent control is non-compliant unless it creates a real participant/runtime effect or explicit refusal.
9. A room/forum/panel surface is non-compliant unless it declares a retention/learning policy bundle.
10. Hidden system-agent bus behavior and visible room behavior must remain distinct.
11. Channel projection must be capability-driven and truthful.
12. Anything listed under **Required now** is not optional.
13. Canonical docs may define semantics; implementation appendices may define physical repo mapping. Canonical docs must not freeze false repo paths as truth.
14. The master ledger is the only suite-wide active tracker. Temporary addenda may exist during drafting, but once merged they become historical only.

### 0.1 Contract acceptance tracking
Each obligation in this ledger should eventually be tracked with one of:
- `pending`
- `acknowledged`
- `accepted`
- `accepted_with_modification`
- `rejected`

Owner-doc revision passes should update that status explicitly rather than silently absorbing or ignoring obligations.

### 0.2 Feeder-doc merge / retirement rule
- DOC12 Inter-Document Integration Addendum R2 is now **absorbed** into this R9 ledger.
- After adoption of R9, do **not** continue tracking DOC12 Addendum R2 as a parallel active queue.
- Keep the addendum only as historical provenance until each mirrored XDI row is accepted/rejected in the relevant owner-doc revision.
- If DOC12 generates new cross-doc obligations later, add them directly here unless a temporary drafting packet is needed for review; if a temporary packet is created, it becomes stale once merged into the master ledger.
- DOC15 Cross-Document Integration Contract remains a **specialized subsystem contract**, not a second suite-wide master ledger.

### 0.3 Stable XDI ID rule
Newly merged rows in this revision use stable IDs of the form `XDI-R9-###`.
The ID stays stable even if the owner-doc wording changes.
If one ledger row splits into several owner-doc changes, keep the original row and create child notes rather than silently renumbering.

---

## 1) Canonical schemas and source-of-truth decisions to settle now

### 1.1 STOP canonicalization and migration
Canonical path:
- `ELNOR_MEMORY/system/stop_request.json`

Canonical shape:
- `STOPStateSchema` from DOC10 R10 section 7.4

All docs that reference STOP should converge on this path and schema.

Affected docs:
- DOC1
- DOC9
- DOC10
- DOC11 / any Gateway-integrated job runners or discovery runners
- Q modal / stop controls
- any current stop-controller adapter

Required additional rule:
- existing stop-controller or tiered-stop shapes may be adapted temporarily, but they must reconcile into the canonical durable shape above.

### 1.2 Route trace, artifact origin, transaction manifest, and usage seeds
Canonical DOC10-owned orchestration artifacts:
- `RouteTraceRecordSchema`
- `ArtifactOriginSchema`
- `TransactionManifestSchema`
- `ExecutedBehaviorBundleSchema`
- provisional `ProvisionalUsageSummarySchema` seed fields

These must be accepted by owner docs when DOC10-originated actions/proposals/artifacts are created.

Narrowing rule:
- transaction manifests are read-only provenance groupings in the near term,
- they do not imply distributed rollback or revert-all orchestration.

### 1.3 Effective mode and intake canonicalization
Canonical DOC10-owned contracts:
- `OrchestrationModeStateSchema`
- `EffectiveModeStateSchema`
- `OperationEnvelopeSchema`

Required rule:
- runtime behavior, read-models, and UI must use `EffectiveModeStateSchema` when degrade overlays or STOP constraints change behavior without changing the persisted mode file,
- legacy intake paths may coexist temporarily, but they must adapt into `OperationEnvelopeSchema`.

### 1.4 Entity discovery public facade
Canonical public contract owner:
- DOC10 facade contract

Underlying summary/data owners:
- Running Brief / OCM
- DOC7
- DOC6
- DOC9
- DOC1
- any other subsystem exposing entities

The public entity discovery response must not be duplicated with competing schemas.

### 1.5 Unified Inbox canonical container
Canonical container owner:
- DOC10 container schema

Owner docs retain semantics for their own item types:
- DOC1 for memory-lifecycle items
- DOC8 for learning/friction items
- DOC9 for repair/proposal items
- DOC3 for capability-related proposals where applicable

Migration rule:
- existing pending-item surfaces may remain behind an explicit compatibility adapter only.

### 1.6 Gateway-first interactive Q chat and guard alignment
Canonical rule owner:
- DOC11 for Gateway-first chat assembly and controls
- DOC10 for the normative requirement that Q interactive chat dispatches to `gateway_interactive_chat`
- DOC4 for the bridge posture and philosophical baseline

Required rule:
- `shouldDefaultToGatewayFirstChat()` must consume canonical fields only,
- the `ActionabilityDecision.kind` mismatch is closed in DOC10 R10; downstream code must migrate to canonical fields.

### 1.7 Route hints, route blocklist, and reroute lifecycle
Canonical owner:
- DOC10

Canonical paths:
- `ELNOR_MEMORY/system/orchestration/route_hints.jsonl`
- `ELNOR_MEMORY/system/orchestration/route_hints_current.json`
- `ELNOR_MEMORY/system/orchestration/route_blocklist.jsonl`
- `ELNOR_MEMORY/system/orchestration/route_blocklist_current.json`
- `ELNOR_MEMORY/system/orchestration/route_aliases.jsonl`
- `ELNOR_MEMORY/system/orchestration/route_aliases_current.json`

DOC1 process memory may inform route hints but is not the canonical route-hint store.

### 1.8 Capability awareness, Context Card, and registry facade
Canonical owner:
- DOC10 for `CapabilityAwarenessSnapshot`, `WhatCanIDoHereCardSchema`, and capability registry facade query contracts

Inputs owned by:
- DOC3 capability bridge metadata
- DOC11/OpenClaw catalog and effective controls
- DOC10 route blocklist, alias state, health/quarantine consumption
- room/participant context from DOC12 where applicable
- page/entity context from entity discovery

Required rule:
- capability-registry derivation from runtime facts -> bridge cache -> route-facing facade must be explicit and source-labeled.

### 1.9 Gateway reverse telemetry, executed behavior, and abort interop
Canonical producers:
- DOC11 / Gateway bridge layer

Canonical consumers:
- DOC10 route trace and running jobs
- DOC8 friction/self-learning where relevant
- DOC9 repair wake flows where relevant
- Q dashboard / engineering panel surfaces
- DOC12 room participant/runtime overlays where room dispatch is involved

Canonical contracts:
- `GatewayHandoffPayloadSchema`
- `GatewayReverseEventSchema`
- `GatewayAbortInteropSchema`
- `ExecutedBehaviorBundleSchema`

Required producer-side rule:
- minimum `gateway.*` event families, required fields, `correlation_id` echo, room/participant correlation fields, and abort acknowledgment / timeout semantics must be guaranteed or explicitly marked unsupported/degraded.

### 1.10 Running jobs, dispatch results, and read-model response pack
Canonical owner:
- DOC10 for `RunningJobSchema`, `DispatchResultSchema`, and required read-model schemas

Required read-model surfaces:
- `/api/orchestration/state`
- `/api/orchestration/jobs`
- `/api/orchestration/traces/:routeTraceId`
- `/api/orchestration/system-agents`
- `/api/orchestration/context-card`
- `/api/orchestration/capabilities/snapshot`

Required rule:
- these endpoints must return locked response schemas, not ad hoc JSON.

### 1.11 SystemPulseSchema and `WhatCanIDoHereCardSchema`
Canonical owner:
- DOC10

These schemas are the required shared read models for:
- Engineering / Orchestration Panel
- header/system pulse UI
- capability-awareness surfaces
- room-aware capability surfaces where room context changes actionability

### 1.12 Shared normalized dedupe key, proxy result envelope, and authority matrix
Canonical shared contracts:
- `SharedNormalizedEventKeySchema`
- owner-doc proxy result/refusal envelope
- Mode x Operation Authority Matrix

Required rule:
- all owner-doc proxy mutations and high-volume friction streams must either accept the canonical shapes directly or provide an explicit compatibility mapping.

### 1.13 Canonical orchestration storage root and usage / token / cost seed fields
Canonical root:
- `ELNOR_MEMORY/system/orchestration/`

Required rule:
- route traces, jobs, manifests, read-model projections, and provisional usage seeds must all map to this root or an explicitly documented mirror/adapter path.

### 1.14 Room artifact and shared conversation substrate canonicalization
Canonical owner:
- DOC12 / EC room coordinator

Canonical room artifacts:
- `ELNOR_MEMORY/system/rooms/rooms_registry.json`
- `ELNOR_MEMORY/system/rooms/room_events.jsonl`
- `ELNOR_MEMORY/system/rooms/room_cost_events.jsonl`
- `ELNOR_MEMORY/system/rooms/<room_id>/room_state.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/commands.jsonl`
- `ELNOR_MEMORY/system/rooms/<room_id>/idempotency_index.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/participants_current.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/messages.jsonl`
- `ELNOR_MEMORY/system/rooms/<room_id>/turns.jsonl`
- `ELNOR_MEMORY/system/rooms/<room_id>/runtime_bindings_current.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/summary_current.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/cost_aggregate_current.json`
- `ELNOR_MEMORY/system/rooms/<room_id>/policy_current.json`

Canonical room/shared-conversation substrate contracts:
- `SharedConversationMessageSchema`
- `RoomParticipantSchema`
- `RetentionAndLearningPolicyBundleSchema`
- `RoomBootstrapPacketSchema`
- `ProjectionPolicySchema`

### 1.15 Visible participant registry and runtime-overlay reconciliation
Canonical owners:
- DOC12 owns room participation contracts and participant identity
- DOC4 owns configured visible-agent metadata and room/panel/forum eligibility
- DOC11 owns runtime overlays for those participants

Required rule:
- `DOC11 ParticipantRuntimeStatus.participant_id == DOC12 RoomParticipant.participant_id`
- the DOC11/DOC12 binding state machine MUST use one shared vocabulary,
- DOC4 visible-agent registry metadata must not collapse visible agents, task agents, and hidden system agents into one fake tier.

### 1.16 Unified room / route / cost correlation fields
When room dispatch is involved, the canonical correlation set must include:
- `room_trace_id`
- `room_id`
- `room_turn_id`
- `participant_id`
- `route_trace_id`
- `gateway_session_key`
- `operation_id`
- `correlation_id`
- `switch_segment_id` where execution truth changes mid-turn

Required rule:
- room cost, route traces, running jobs, reverse telemetry, and participant drawers must all be able to attribute execution using this set.

### 1.17 DOC11 runtime-truth, selector, auth, capability, and attachment seam
Canonical owner:
- DOC11

Canonical DOC11 seam families now expected by the suite:
- `TruthResolverResult`
- `GatewayControlMutationResult`
- `ExecutionWatermark`
- `GatewayRuntimeCapabilityCheckRequest/Result`
- `ContextInjectionManifest`
- `ContextBudgetResolutionRecord`
- `ProviderAuth*` route/request/result contracts
- `UsageSample` / `usage.sample.recorded`
- `SwitchSegmentRecord`
- `MismatchFallbackLogEntry`
- `AbortReceipt` / `AbortState`
- `SecureBlobRef`

Required rule:
- if Q renders a selector, badge, drawer, inspector, or action based on these seams, the underlying read-models and routes must be declared and anti-ghost tested.

### 1.18 OpenClaw auth-mode, secret-source, and native context-engine runtime truth
Canonical owner:
- DOC11 consuming runtime truth from OpenClaw / DOC4 evidence

Required runtime-discovered truth:
- `gateway.auth.mode`
- `credential_source_kind` (`gateway_store | secret_ref | env | file | exec | cli_managed | plugin_managed`)
- `native_context_engine_id`
- `native_context_engine_kind`
- `native_context_engine_owns_compaction`
- plugin system-context contribution presence
- prompt-injection policy posture when it affects context behavior

Required rule:
- these values must be surfaced as runtime-discovered truth, not assumed from config or UI state.

### 1.19 Usage / cost producer seam and max-output split
Canonical owner split:
- DOC11 produces usage/correlation seams
- DOC13 owns canonical cost interpretation and enforcement

Required split:
- `desired_max_output_tokens_user` = user-facing advisory/settings value unless native support is explicitly audited
- `dispatch_max_output_tokens_cap` = orchestration-imposed provider call cap for budget enforcement

Required rule:
- docs, UI, and telemetry must not blur those two fields together.

### 1.20 Context manifest / protected native context / CIL seam
Canonical owner split:
- DOC11 owns context manifest, native-vs-EC/Q split, protected native context guardrails, and diagnostics
- DOC15 owns CIL-specific capture contracts and downstream mismatch analysis

Required rule:
- CIL/extra context sources remain EC/Q-contributed unless explicitly runtime-native,
- DOC11 context manifests and diagnostics must remain available for DOC15 analysis,
- protected native context must remain read-only from EC/Q compaction/summarization logic.

---

## 2) DOC1 required amendments

### Required now
- Add a deterministic memory-selector query interface usable by DOC10.
- Accept `ArtifactOriginSchema` on memory candidates, promotion candidates, and memory-related inbox items influenced by DOC10.
- Preserve provenance on memory mutations surfaced through Q controls.
- Mark OpenClaw-native memory sources (or equivalent metadata) so DOC10 can dedupe against workspace memory.
- Emit owner-doc mutation telemetry back to DOC10/Q for promote/demote/edit/archive/delete outcomes.
- Accept route-trace and inbox-origin references on promote/review actions where applicable.
- Support lean-return expectations: refs, titles, tags, trust, scope, compact snippet metadata; not large free-form blobs on the hot path.
- Accept the DOC12 `RetentionAndLearningPolicyBundle` as an input/control surface for room/forum/panel-originating candidates.
- Enforce that room/forum/panel discussion cannot directly become durable memory unless policy and owner-doc approval allow it.
- Preserve room provenance fields on any memory candidate or approved memory mutation:
- `room_id`
- `room_message_id` / `room_turn_id`
- `participant_id`
- `trust_taint_mode`
- Support explicit suppression states when promotion is blocked by room or review policy.

### Required integration rule
- DOC10 selects bounded refs/hints only.
- DOC1 remains owner of memory lifecycle, storage, and mutation semantics.
- Gateway-first chat must not become a second DOC1 memory prompt assembler.
- Room/panel/forum policy bundles may gate memory promotion, but DOC1 still owns the final durability decision.

### Future-phase note
- Cross-turn dedupe quality can improve once DOC1 exposes stronger memory source metadata and usage history.
- Memory Browser should later expose room/panel/forum-derived candidate filters and policy-block reasons.

## 3) DOC2 / Freshness Manager required amendments

### Required now
- Emit `freshness.result.available` or equivalent hook when freshness evaluation materially changes route/annotation posture.
- Expose enough freshness state for:
- System Pulse
- lean annotation builder
- route scoring penalties / warnings
- Preserve TTL ownership inside the Freshness Manager; DOC10 must consume freshness, not redefine freshness math.

### Required integration rule
- DOC10 may read freshness outputs and surface warnings.
- DOC2 / Freshness Manager remains owner of freshness records, normalization, and TTL policy.

## 4) DOC3 required amendments

### Required now
- Export or confirm the canonical Capability Registry Bridge expected by DOC10.
- Required fields include:
- capability id
- family
- title
- aliases
- action verbs
- route tier
- supervision posture
- dry-run support
- routing eligibility
- health status
- origin owner
- built-in OpenClaw flag where applicable
- metadata ref
- updated_at
- Emit hooks for install/update/remove/quarantine/health change.
- Support bridge-cache replacement semantics so canonical DOC3 entries override provisional scanner output.
- Expose enough capability metadata to support visible agent selection, room eligibility hints, and room-aware "What can I do here?" surfaces.
- Ensure capability-awareness surfaces can answer which agents/tools are available in the current room or room-linked context.

### Required integration rule
- until DOC3 exports the canonical bridge, the scanner may act as the provisional dominant source;
- that provisional state must be labeled honestly in UI and telemetry;
- scanner defaults must remain low-trust, not optimistic.
- DOC12 may consume capability metadata for room UI and participant selection, but DOC3 still owns skills/capability artifacts.

### Future-phase note
- richer bridge derivation from runtime/OpenClaw facts can later move from provisional to first-class once DOC3 and DOC4 expose stronger metadata.
- agent-facing capability tags and coding-specialist hints may be added later without changing the canonical bridge ownership.

## 5) DOC4 required amendments

### Required now
- Explicitly distinguish:
- native runtime behavior,
- task agents / configured agents,
- OpenClaw-native capabilities,
- visible room-eligible agents,
- hidden system agents.
- Preserve the anti-hamstringing posture for OpenClaw native runtime.
- Accept DOC10 requirements for Gateway-first path and runtime truth boundaries.
- Align any capability snapshot/export reality with DOC10 capability-registry derivation rules.
- Define a visible configured-agent registry consumable by Q and DOC12, including canonical file path:
- `ELNOR_MEMORY/agents/visible_agents_registry.json`
- Minimum visible-agent registry fields:
- `agent_id`
- `display_name`
- `summary`
- `room_eligible`
- `panel_eligible`
- `forum_eligible`
- `supports_moderator_role`
- `default_runtime_kind`
- `tool_runtime_posture`
- Clarify that configured visible agents are the primary visible room participants.
- Clarify that native internal sub-agents remain allowed inside a visible participant turn unless a profile explicitly narrows them.
- Clarify ACP delegate posture relative to configured native agents and native sub-agents.
- Provide runtime evidence/bridge truth for:
- auth mode posture,
- credential-source posture when discoverable,
- native context engine availability,
- plugin-managed system-context behavior,
- `sessions.get` or successor runtime truth reads.

### Required integration rule
- DOC10 remains the orchestration registrar.
- DOC4 remains the bridge/runtime philosophy owner.
- Visible participant/agent registries for DOC12 must not collapse system-agent and task-agent tiers together.
- DOC11 must not claim any runtime/plugin/channel path that DOC4/OpenClaw evidence does not support.

### Future-phase note
- DOC4 and DOC12 should later converge on explicit visible-agent registry contracts without pulling DOC10 into room-specific ownership.
- Safe defaults for room-bound sessions and visible-room agent-main prohibition can be documented in a later DOC4 pass.

## 6) DOC6 required amendments

### Required now
- Add explicit compatibility notes for the shared conversation substrate introduced by DOC12.
- Adopt DOC12 shared-conversation contracts for any panel/forum multi-agent transcript, or provide a lossless mapping.
- Add a reusable Conversation Configuration block to panel setup and forum setup surfaces with:
- participants
- moderator
- room/turn mode
- bucket selection
- retention/learning preset
- projection settings
- Add bridge actions:
- open live room from panel/forum
- post room summary back
- attach panel/forum as room context
- create panel/forum from room where allowed
- Add retention / learning policy bundle support so panel/forum discussions do not silently poison memory or learning.

### Required integration rule
- panels remain guided artifacts,
- forums remain async artifacts,
- live rooms remain DOC12-owned,
- DOC10 consumes their surfaced entities, telemetry, and owner-doc controls, but does not collapse them into one generic artifact,
- DOC6 retains storage/lifecycle ownership of panels and forums even when they bridge to rooms.

### Future-phase note
- storage unification is not required immediately; bridge-compatible dual substrate is acceptable while the room substrate stabilizes.
- moderator-led room phases and per-panel/per-forum policy defaults are good next-wave additions, not blockers for the current ledger wave.

## 7) DOC7 required amendments

### Required now
- Preserve bucket refs as refs, not prompt dumps.
- Add bucket-launched room hooks in coordination with DOC12.
- Ensure bucket selectors and context attachment surfaces expose stable refs DOC10 can consume.
- Expose attachment provenance cleanly enough for route traces and origin inspection.
- Surface access / trust information where shared attachments or room attachments may affect downstream behavior.
- Add `Start Agent Chat` / `Open Live Room` actions from bucket detail pages.
- Add a room-aware bucket picker in room configurator and message composer.
- Expose bucket refs cleanly to DOC12 room attachment contracts.
- Preserve bucket access/provenance logging for room usage.
- Ensure bucket attachments are passed by ref/summary rather than prompt-pasted wholesale.

### Required integration rule
- DOC7 owns bucket storage and access semantics.
- DOC10 consumes bucket refs, labels, and compact summaries only.
- DOC12/Q may consume bucket refs for room launch and room turns, but DOC7 remains the storage/materialization owner.

### Future-phase note
- recommended-agent hints and room-linked attachment chips are useful near-term enhancements but not blockers.

## 8) Running Brief / OCM required amendments

### Required now
- Cached brief contract must remain lean and bounded.
- No full Running Brief unified prompt assembly on the Gateway-first hot path.
- Live OCM path remains defined but gated until explicitly enabled.
- Brief excerpt trimming and cached-brief TTL must align with DOC10 limits.
- Conversation-context surfaces must not silently add a second live context assembler for existing DOC10 paths.
- Add room summary outputs and participant-scoped room brief assembly.
- Ensure room bootstrap packets include fresh-surface reset language and participant roster.
- Preserve strict isolation across parallel room participants.
- Keep room summaries bounded and ref-first; do not inject raw transcript dumps.

### Required integration rule
- Running Brief / OCM owns brief generation and conversation-context summarization.
- DOC10 consumes compact outputs and refs only.
- DOC12 defines when room bootstrap/summary is required and the minimum room-specific fields.

### Future-phase note
- room-specific summary views and room-aware query restrictions may be added later.

## 9) DOC8 required amendments

### Required now
- DOC8 is the sole raw-event sequencer for high-volume failure streams.
- Accept `SharedNormalizedEventKeySchema` or provide an explicit compatibility mapping.
- Accept orchestration-origin provenance on friction/learning candidates where relevant.
- Accept new routing-quality / alias / degraded-mode friction types or provide an explicit mapping adapter.
- Ensure deduped downstream events can feed both DOC10 and DOC9 without duplication.
- Preserve repair-worthy and learning-worthy event separation cleanly.
- Add room-specific friction/event families such as:
- wrong participant responded,
- participant failed to respond,
- room deadlock,
- excessive rounds,
- ignored attached context,
- repeated manual redirection,
- projection failure impact.
- Consume room telemetry and room provenance fields when generating learning candidates.
- Respect room/panel/forum policy bundles when deciding whether learning signals are emitted or suppressed.

### Required integration rule
- DOC10 consumes normalized/deduped events from DOC8 rather than competing to sequence raw runtime errors itself.
- DOC12 supplies room-originated signals and suppression reasons; DOC8 remains the learning/friction owner.

### Future-phase note
- richer route-quality analytics, room health dashboards, and room usefulness metrics remain valuable but are not blockers.

## 10) DOC9 required amendments

### Required now
- Accept `RepairWakeRequest` from the DOC10 proxy path.
- Accept `ArtifactOriginSchema` and shared dedupe keys on repair wakes / repair-adjacent proposals.
- Emit `repair.session.completed` or equivalent completion hook with provenance.
- Emit explicit refusal when repair wake is blocked or invalid.
- Ensure repair-completion and repair-wake telemetry can flow back into DOC10/Q surfaces.
- Distinguish room-derived repair evidence from ordinary chat-derived repair evidence.
- Add repair-safe ACP delegate profile expectations and no-silent-write guardrails.
- Accept room provenance fields on repair proposals spawned from room/panel/forum discussion.
- Respect room/panel/forum policy bundles when deciding whether repair evidence is eligible.

### Required integration rule
- DOC10 may wake or link repairs.
- DOC9 remains owner of repair execution and repair mutation semantics.
- DOC12 provides room context, ACP room participation posture, and provenance; DOC9 decides repair semantics and approvals.

### Future-phase note
- convenience flows such as `open repair room` and room-summary links inside repair sessions can follow later.

## 11) DOC11 required amendments / cross-links

### Required now
- Provide the concrete Gateway-first chat assembly and session-control path.
- Provide the producer-side reverse-telemetry contract:
- minimum families,
- required fields,
- `correlation_id` echo,
- degraded/unsupported truthfulness when native families are absent,
- room/participant correlation fields when room dispatch is involved.
- Provide the real abort/cancel path:
- request shape / transport,
- ack,
- timeout,
- unsupported-runtime behavior,
- cleanup lifecycle,
- room-wide and per-participant propagation semantics.
- Provide the DOC10 -> DOC11 handoff/annotation handshake mapping.
- Provide a declared Gateway health source.
- Ensure live stream / push transport is sufficient for reverse telemetry and job updates.
- Accept a room-aware dispatch request type (`room_turn_dispatch`) with stream-capable results and full room/participant correlation.
- Support participant session binding for room-bound sessions using the shared DOC11/DOC12 binding-state vocabulary.
- Expose a session status read used for binding reconciliation.
- Provide a room bootstrap injection slot separate from lean EC annotations.
- Preserve OpenClaw runtime autonomy inside participant turns.
- Expose the RuntimeTruthResolver/selector-governance seams needed by DOC10/Q so all selector views resolve from one truth model.
- Define and route truthful model CRUD / orphan repair / fallback / switch semantics, including:
- soft-delete behavior,
- orphaned existing bindings,
- switch segment generation,
- mismatch/fallback logging,
- repair flow commands.
- Define and route the provider/model auth subsystem with concrete route contracts, request/response shapes, and state transitions for:
- catalog,
- profiles,
- state,
- start,
- complete,
- cancel,
- relogin,
- remove profile,
- set default,
- probe,
- verify CLI,
- callback relay,
- plugin-managed / proxy / SecretRef-aware discovery where supported.
- Stamp executed auth provenance into runtime truth / watermark seams.
- Surface auth-mode truth, SecretRef-aware credential-source truth, and active context-engine truth as runtime-discovered state.
- Provide capability-check contracts with TTL/invalidation rules and truthful attachment transport/failure reasons.
- Preserve honest attachment transport behavior:
- every attachment chooses a transport mode,
- unsupported URL-only attachments fail explicitly,
- no silent drop,
- no durable raw base64,
- durable attachment references use `SecureBlobRef` or equivalent.
- Provide context manifest, budget-resolution, protected-native-context, native-context-engine, and prompt-injection-policy diagnostics sufficient for Q and DOC15.
- Emit `UsageSample` / `usage.sample.recorded` seams on completed, failed, and aborted turns when provider-native usage exists; emit `usage_state = unknown` explicitly when it does not.
- Preserve the max-output split:
- `desired_max_output_tokens_user`
- `dispatch_max_output_tokens_cap`
- Publish docs-consistency CI / anti-ghost test minima so downstream implementation cannot invent decorative controls.

### Required integration rule
- DOC11 owns Gateway-first chat assembly, model controls, runtime/Gateway truth, auth/runtime seams, and OpenClaw-facing wrapper honesty.
- DOC10 owns the orchestration contracts that DOC11 must satisfy at the seam.
- DOC4/OpenClaw remains canonical for what is actually native.

### Future-phase note
- room-turn dispatch examples for ACP-specialist flows and future voice surfaces can land later; they must not dilute the current runtime seam.

## 12) DOC12 required amendments / cross-links

### Required now
- Keep room / participant / room-turn behavior in DOC12, not DOC10.
- Accept DOC10 shared contracts where relevant:
- route traces,
- artifact origin,
- transaction manifest linking,
- cost/usage seed fields,
- proxy result/refusal envelopes where DOC10 surfaces room-origin side effects.
- Align retention / learning policy bundles with DOC1 / DOC8 / DOC9 expectations.
- Align room/session/runtime binding with DOC11 Gateway session truth and DOC4 visible-agent registry posture.
- Keep the hidden system-agent bus and visible rooms distinct.
- Own the canonical room operation semantics and route/control rows for at least:
- `room_create`
- `room_post_message`
- `room_round_request`
- `room_add_participant`
- `room_remove_participant`
- `room_mute_participant`
- `bucket_launch_room`
- `panel_to_room`
- `forum_to_room`
- `room_projection_emit`
- `room_post_summary_to_forum`
- `room_post_summary_to_panel`
- `room_create_panel_from_room`
- Use the shared binding-state vocabulary and participant ID join rules required by DOC11.
- Require stream-capable room-turn transport and room/participant correlation fields.
- Treat Add Agent / mute / unmute / remove / stop as real policy mutations with idempotency and optimistic concurrency (`_version`).
- Own `RetentionAndLearningPolicyBundleSchema`, `ProjectionPolicySchema`, `RoomBootstrapPacketSchema`, and room artifact schemas.
- Keep ACP support optional and defeatable.
- Keep channel projection capability-driven and truthful.
- Define room action capability reporting so DOC11/Q can degrade room-policy actions to read-only when unavailable.

### Required integration rule
- DOC12 owns live-room, participant, room-turn, projection-policy, and room-ui semantics.
- DOC10 remains the orchestration hub for non-room execution and shared-contract consumers.
- DOC11 owns runtime overlays for those participants; DOC12 owns the participant and room-policy truth those overlays attach to.

### Future-phase note
- moderator-led room phases, richer room analytics, and projection hardening are important but need not block the current seam closure pass.

## 13) DOC13 required amendments / cross-links

### Required now
- Freeze the canonical shared cost/usage/token language for:
- chat turns,
- running jobs,
- route traces,
- rooms,
- panels/forums,
- repair/discovery work,
- room-projection side effects where they incur model cost.
- Reconcile DOC10/DOC12 provisional usage seed fields into canonical shared schemas.
- Provide cost/blocker policy primitives and telemetry shapes.
- Accept DOC11 `UsageSample` / `usage.sample.recorded` as the producer seam and pick one consumption path:
- `usage_sample_store`, or
- normalized internal `usage.sample.recorded` event.
Do not support both half-heartedly.
- Support partial usage on failure/abort when provider-native usage exists.
- Support explicit `usage_state` and `cost_truth_mode` (`verified | estimated | unknown`).
- Attribute cost per participant, per room, per panel/forum/run, and across switch segments where execution truth changes.
- Honor `dispatch_max_output_tokens_cap` as the orchestration-imposed cost/budget clamp.
- Expose room and participant subtotal seams usable by room headers, participant drawers, running jobs, and budget-warning surfaces.

### Required integration rule
- until DOC13 freezes the canonical model, DOC10/DOC11/DOC12 seed fields remain provisional and should not diverge.
- DOC11 produces usage/correlation truth; DOC13 owns cost interpretation, rollup, and enforcement.

### Future-phase note
- if native compaction/context-engine maintenance cost later becomes visible, DOC13 may distinguish runtime-native maintenance from user-turn spend; that is useful but not required for the current pass.

## 14) DOC15 required amendments / cross-links

### Required now
- Preserve the specialized DOC15 Cross-Document Integration Contract as the subsystem-specific owner-by-owner capture document.
- Mirror any DOC15-required-now cross-doc blocker into this master ledger rather than creating a second suite-wide tracker.
- Ensure DOC11 context manifests, native-vs-EC/Q contribution split, protected-native-context diagnostics, and mismatch/degradation evidence remain available for CIL mismatch analysis.
- Treat CIL/context-plan sources as EC/Q-contributed context unless explicitly runtime-native by audited evidence.
- Preserve enough runtime truth for DOC15 `DispatchCheckpoint` / context analysis to reason about:
- model/provider/auth provenance,
- capability-check posture,
- context pressure state,
- mismatch/fallback/switch behavior.

### Required integration rule
- DOC15 remains the CIL-specific seam/contract owner.
- DOC10 remains the suite-wide master tracker.
- DOC11/DOC12/DOC13 must expose the signals DOC15 depends on, but DOC15 does not become the owner of their runtime or room semantics.

### Future-phase note
- DOC15 may later request richer prompt-lineage / room-close / review-outcome fields; those should be added here as XDI rows when they become required-now blockers.

## 15) Q frontend/backend and external-channel required amendments

### Backend required now
- Implement or adapt to `OperationEnvelope` intake.
- Provide a live stream/push path for jobs, reverse telemetry, and trace updates.
- Provide room routes and backend proxies for:
- room create/post/add participant/remove participant/mute/unmute/stop,
- room event stream,
- room summary/bridge actions,
- bucket-launch-room and panel/forum-to-room flows.
- Validate proxy request schemas in EC.
- Return canonical read-model response schemas.
- Surface explicit refusal/failure states for owner-doc proxy mutations.
- Respect idempotency keys where required.
- Preserve real mode/effective-mode divergence when present.
- Provide DOC11-backed routes for:
- model catalog create/update/delete/restore,
- orphan repair,
- auth start/complete/cancel/relogin/remove/set-default/probe/verify-cli/callback,
- capability checks,
- context explain/dry-run,
- truth-resolver debug read,
- mismatch/fallback log read,
- participant runtime drawer read,
- abort by supported scope.

### Frontend required now
- Route banners, intent cards, and running jobs must update from real reverse telemetry or read-model refresh, not client guesswork.
- Abort/cleanup states must be visible.
- Stream degradation must be visible.
- Context authority violations, capability-cache staleness, and bridge-state truthfulness must be renderable.
- Pending-item/inbox compatibility may exist temporarily, but it must be explicit.
- Add Room header, participant drawer/sidebar, Add Agent flow, Configure Room modal, room composer, and room transcript rendering.
- Subscribe to the room event stream and use it as the primary room UI refresh trigger.
- Add mute/unmute/remove participant actions.
- Add bucket picker in room configurator and room composer where attachments/context can be room-scoped.
- Add linked room actions in panel/forum/bucket surfaces.
- Surface room usage/cost aggregates and any budget-block reasons.
- Add ACP settings / active delegations views only if ACP is enabled.
- Add DOC11 truth surfaces:
- runtime truth chips,
- truth-resolver debug view,
- context inspector,
- mismatch/fallback log viewer,
- capability-check viewer,
- auth challenge and auth-state surfaces,
- attachment transport/result visibility,
- settings-only badges for unsupported controls,
- explicit orphaned/degraded/pending/rejected states.

### Required UI behavior
- any visible control must have:
- telemetry,
- backend command,
- durable mutation or explicit refusal,
- read-model refresh,
- success/failure/pending/disabled states,
- anti-ghost tests.
- live state must come from stream/read-model truth, not local optimistic imagination.
- room-policy buttons that DOC12 does not currently grant must render as read-only explanation, not clickable no-op controls.
- settings-only controls that do not affect runtime truth must be visibly labeled as such and never painted as verified.

### External-channel integration required now
- Treat Q as canonical room control surface.
- Add projection-mode selection that is capability-driven.
- Require thread-capable channels to prove support before enabling thread projection.
- Use narrated/speaker-prefixed projection for single-stream channels.
- Keep channel-projection truth separate from room-runtime truth so failures do not masquerade as participant execution state.

### Compatibility note
- monolithic backend/frontend files may persist during migration, but the orchestration and room/runtime contracts above still govern behavior.

## 16) Gateway protocol and source validation obligations

### Required now
- Verify actual OpenClaw / DOC11 protocol and type definitions before naming methods or payload shapes.
- Do not invent unsupported Gateway event families, auth semantics, context-engine assumptions, or abort semantics.
- If native Gateway output is weaker than DOC10/Q expects, surface unsupported/degraded state explicitly.
- Session truth belongs to Gateway/runtime, not to Q.
- Active context engine, auth mode, SecretRef/credential source kind, plugin system-context presence, and prompt-injection policy posture must be treated as runtime-discovered truth.
- `sessions.get` and similar runtime reads may be used for verification if present in the audited build.
- Main-branch / unpublished OpenClaw changes remain advisory until published and re-audited.

### Required rule
- canonical docs define seam requirements;
- implementation appendices map those seam requirements to actual source files and runtime types;
- runtime evidence refs must be pinned and refreshed when the audited OpenClaw build changes.

## 17) Telemetry, dashboard, and control obligations

### Required now
- Add telemetry phase tiering so hot-path vs near-real-time vs retained analytics are distinguished.
- Add startup self-test / degraded-start reporting.
- Add context-authority violation telemetry.
- Add capability hot-reload / stale-cache telemetry.
- Add route/job usage summaries that later align with DOC13 canonical schemas.
- Add explicit degraded-state surfacing when hook infrastructure, stream infrastructure, or reverse telemetry are impaired.
- Add room telemetry families and correlation requirements to observability expectations.
- Add auth telemetry families sufficient to prove the auth subsystem is real, including at minimum:
- challenge required,
- challenge completed,
- challenge cancelled,
- probe completed,
- probe failed,
- profile removed,
- default changed,
- profile mismatch recorded,
- scope-limited / invalid / stale transitions.
- Add protected-native-context violation telemetry.
- Add switch-segment / mismatch / fallback telemetry.
- Add orphan-model / orphan-binding / repair telemetry.
- Add explicit stream degraded / recovered / replay telemetry.
- Add room and participant cost subtotal update telemetry if the UI depends on live aggregate refresh.

### Required integration rule
- telemetry that materially affects user trust must be visible somewhere in Q or engineering surfaces.
- if a control can fail, time out, degrade, or become stale, there must be a visible state or drill-down showing that truth.

### Future-phase note
- heavy analytics, auto-learning, and later-phase exploration loops remain defined but gated.

## 18) Shared orchestration infrastructure obligations

### Required now
- Define the orchestration storage root and compatibility rules for mirrors.
- Define write-order / reconciliation notes where one operation writes:
- chat history,
- route traces,
- jobs,
- manifests,
- telemetry artifacts,
- room artifacts,
- usage samples,
- switch segments,
- auth state snapshots,
- context manifests.
- Define compatibility between orchestration mutability flags and existing remote-write / durable-write permission enforcement.
- Add Gateway watchdog / dead-letter handling if current transport cannot guarantee bounded failure detection.
- Add hook payload / retry / debounce / fallback contracts if current EventBus is too primitive.
- Define dual-connection write-leader rules where Q backend and EC both subscribe to Gateway telemetry.
- Require docs-consistency CI to fail when:
- a route appears in prose but not in the route matrix,
- a read-model appears in prose but not in the read-model matrix,
- a referenced schema is not defined/exported,
- a control lacks route/store/test coverage,
- runtime evidence refs are stale,
- a required cross-doc obligation is not mirrored to this ledger.
- Require anti-ghost action tests proving every visible control either performs the real mutation/path or emits a truthful refusal.
- Require idempotency keys and optimistic concurrency (`_version`) for room mutations.

### Required integration rule
- if current infrastructure cannot meet a required orchestration contract yet, that degraded state must be explicit and user-visible.

## 19) Absorbed feeder-doc and DOC11 seam merge record

The rows below are the newly merged obligations this R9 ledger absorbed from DOC12 Addendum R2 and DOC11 V12.
Unless otherwise noted, status is `pending` until the target owner-doc revision explicitly accepts/rejects the row.

| XDI ID | Source | Targets | Summary | Status |
|---|---|---|---|---|
| XDI-R9-001 | DOC12 Addendum R2 | DOC10, DOC12, EC/Q | Canonical room artifact paths and room event/cost/runtime-binding stores | pending |
| XDI-R9-002 | DOC12 Addendum R2 | DOC12, DOC6, DOC7, DOC10 | Shared conversation substrate / participant / bootstrap / projection contracts | pending |
| XDI-R9-003 | DOC12 Addendum R2 | DOC4, DOC12, Q | Visible-agent registry and room/panel/forum eligibility metadata | pending |
| XDI-R9-004 | DOC12 Addendum R2 | DOC10, DOC12, Q | Room operation matrix rows and room-aware control surfaces | pending |
| XDI-R9-005 | DOC12 Addendum R2 | DOC10, DOC11, DOC12, DOC13 | Unified room correlation fields for traces, telemetry, cost, and runtime truth | pending |
| XDI-R9-006 | DOC12 Addendum R2 | DOC11, DOC12, Q | Room-aware dispatch / room-turn stream transport / room stop propagation | pending |
| XDI-R9-007 | DOC12 Addendum R2 + DOC11 V12 | DOC11, DOC12 | Shared binding-state vocabulary and participant ID join rules | pending |
| XDI-R9-008 | DOC12 Addendum R2 | DOC1, DOC8, DOC9, DOC12 | Retention and learning policy bundle gating across room/panel/forum surfaces | pending |
| XDI-R9-009 | DOC12 Addendum R2 | DOC7, DOC12, Q | Bucket-launch-room and room-aware bucket picker / attachment-by-ref path | pending |
| XDI-R9-010 | DOC12 Addendum R2 | DOC6, DOC12, Q | Panel/forum conversation configuration block and room bridge actions | pending |
| XDI-R9-011 | DOC12 Addendum R2 | DOC8 | Room-specific friction families and suppression-aware learning input | pending |
| XDI-R9-012 | DOC12 Addendum R2 | DOC9 | Room-derived repair evidence and ACP-safe repair posture | pending |
| XDI-R9-013 | DOC12 Addendum R2 | Running Brief / OCM, DOC12 | Room summary outputs and fresh-surface bootstrap packet obligations | pending |
| XDI-R9-014 | DOC12 Addendum R2 | Q, DOC12 | Real room surfaces: header, drawer, Add Agent, stream refresh, policy actions, cost UI | pending |
| XDI-R9-015 | DOC12 Addendum R2 | DOC12, external channel adapters, Q | Capability-driven channel projection rules and narrated-mode fallback | pending |
| XDI-R9-016 | DOC11 V12 | DOC10, Q, EC | RuntimeTruthResolver / selector-governance seam consumed as one truth model | pending |
| XDI-R9-017 | DOC11 V12 | DOC11, Q, DOC10 | Model CRUD, soft delete, orphan repair, switch-segment, and mismatch/fallback truth | pending |
| XDI-R9-018 | DOC11 V12 | DOC11, Q, DOC10 | Concrete auth route contracts, state machine, challenge UX, and executed auth provenance | pending |
| XDI-R9-019 | DOC11 V12 | DOC4, DOC11, Q | Auth mode truth, credential-source truth, `sessions.get` verification, SecretRef awareness | pending |
| XDI-R9-020 | DOC11 V12 | DOC4, DOC11, Q, DOC15 | Active native context-engine truth and plugin system-context classification | pending |
| XDI-R9-021 | DOC11 V12 | DOC11, Q, DOC15 | Context manifest, protected native context violations, and native-pressure diagnostics | pending |
| XDI-R9-022 | DOC11 V12 | DOC11, Q | Capability-check TTL/invalidation, attachment transport truth, URL-only reject path | pending |
| XDI-R9-023 | DOC11 V12 | DOC11, DOC13, Q | `UsageSample` / partial-usage seam, room/participant subtotal inputs, `dispatch_max_output_tokens_cap` split | pending |
| XDI-R9-024 | DOC11 V12 | Q, EC | Truth-resolver debug view, context inspector, mismatch/fallback viewer, capability viewer | pending |
| XDI-R9-025 | DOC11 V12 | DOC10, DOC11, Q, CI/tooling | Docs-consistency CI, route/read-model coverage checks, anti-ghost action tests | pending |
| XDI-R9-026 | This R9 merge pass | DOC10 governance | DOC12 Addendum R2 retired as active tracker after absorption into R9 | accepted |

## 20) Suggested implementation order

1. Adopt this R9 master ledger as the only active suite-wide tracker.
2. Update DOC11 / Gateway contracts / runtime truth / auth / capability / context / abort / usage seams.
3. Update DOC12 room contracts / room artifacts / participant runtime alignment / room event stream obligations.
4. Update DOC4 visible-agent registry and runtime-evidence posture.
5. Update Q backend/frontend to remove ghost controls and implement truthful room/runtime/auth/debug surfaces.
6. Update DOC13 canonical cost model and usage subtotal seam.
7. Update DOC6/DOC7 room bridge actions and bucket room-launch path.
8. Update DOC1/DOC8/DOC9 policy-gated memory/learning/repair seams for room/panel/forum provenance.
9. Update Running Brief / OCM room bootstrap and summary obligations.
10. Re-run docs-consistency CI and runtime evidence audit.
11. Mark XDI rows accepted / accepted_with_modification / rejected in the owner-doc revisions.

## 21) Defined but gated / preserved later ideas

These remain architecturally preserved but are not Required now:
- heavy alias auto-learning,
- deep analytics,
- exploration execution loop,
- teach mode / workflow detector,
- advanced room projection into external channels beyond minimal capability-gated support,
- richer room analytics and moderator-led phase tooling,
- broader cost optimization policies before DOC13 freezes the shared model,
- a dedicated Q voice spec that normalizes voice input/output through the ordinary DOC11 dispatch seam rather than bloating DOC11 itself.

## 22) R9 closure checklist

Before the next major suite convergence pass, confirm:
- this R9 ledger is adopted as the only active suite-wide master ledger,
- DOC12 Addendum R2 is marked historical / merged rather than tracked in parallel,
- DOC11 V12 cross-doc obligations are mirrored here with stable XDI rows,
- room artifact and participant-runtime truth contracts are acknowledged,
- visible-agent registry ownership is acknowledged,
- room/event/cost correlation fields are acknowledged,
- auth route/state/provenance obligations are acknowledged,
- active context-engine / auth-mode / credential-source runtime truth is acknowledged,
- context manifest / protected native context / CIL seam obligations are acknowledged,
- `UsageSample` / subtotal / partial-usage / `dispatch_max_output_tokens_cap` seam is acknowledged,
- Q room surfaces and DOC11 truth/debug surfaces are acknowledged,
- docs-consistency CI and anti-ghost action tests are acknowledged,
- owner-doc revision passes begin updating XDI statuses instead of silently absorbing or ignoring them.

---

# Part 2 — Merged Revision — DOC10 Orchestration Integration Ledger R9.1 (Topology Control Plane)

# DOC10 Orchestration Integration Ledger

Version: R9.1
Status: merged master ledger
Supersedes:
- DOC10 Orchestration Integration Ledger R9
- DOC10 Orchestration Integration Ledger R8

Absorbs / retires as active tracker:
- DOC12 Inter-Document Integration Addendum R2 (fully merged into this ledger; retain only as historical provenance until owner-doc rows are accepted/rejected)

This revision incorporates:
- the full DOC10 R8 master-ledger baseline,
- the DOC12 Inter-Document Integration Addendum R2 merge block,
- the new DOC11 V12 cross-doc seam obligations,
- OpenClaw runtime-truth release-alignment obligations that now affect DOC4/DOC11/Q/DOC13,
- room/runtime/auth/context/cost/debug/anti-ghost-button obligations that must survive the DOC11 and DOC12 revision wave,
- explicit XDI rows for the newly merged obligations,
- the Retrieval / Graph / Topology Control Packet R1 merge block,
- explicit XDI rows for retrieval-lane ownership, graph/topology read-model preservation, provider truth, retrieval receipts, and graph-aware consumer seams.