Define stale componentRef restore behavior for dock-zone layouts

Context

PR #13062 cross-family review approved the dock-zone model contract for #13061 and surfaced one non-blocking follow-up: the contract says item records include componentRef, used by future rendering adapters to locate or create components, but it does not state what happens when a persisted item references a component that no longer exists or cannot be created.

This ticket exists so the next docking-contract reader does not invent restore behavior ad hoc while implementing a consuming adapter.

Release classification: post-release (Approve+Follow-Up follow-up — non-blocking for #13062).

The Problem

HarnessDockZoneModel.md establishes the serializable dock-zone model as the stable authority for future drag-preview, split/tab rendering, and persistence leaves. Restore failure is exactly where those leaves can diverge: one adapter might silently drop a stale pane, another might create an error placeholder, another might keep a tombstone node, and persistence could become incompatible across implementations.

The issue is not a blocker for the current model contract, because no renderer or persistence adapter exists yet. It is a contract-seam follow-up before those consuming leaves start.

The Architectural Reality

• PR #13062 adds learn/agentos/HarnessDockZoneModel.md as the model-contract authority and registers it in learn/tree.json / SEO surfaces.
• The accepted boundary is serializable semantic layout state, not live runtime state. The contract explicitly excludes DOM/window/runtime references and credential material from persisted layout state.
• #13030 remains the QT-grade docking scoping anchor. The remaining decomposition includes drag-to-dock preview, split/tab rendering adapter, blueprint persistence, and second-use-shape validation.
• The correct layer is still the contract/docs layer unless a consuming adapter exposes a stronger runtime need. No .mjs implementation is prescribed here.

The Fix

Clarify stale or unresolvable componentRef behavior in the dock-zone model contract after #13061/#13062 lands.

The likely minimal fix is a short contract paragraph naming the allowed adapter behavior, for example: unresolvable component references are adapter-defined until the rendering/persistence slice owns a concrete policy, but the adapter must preserve enough semantic item metadata for explicit user recovery or validation instead of silently corrupting the saved layout.

The final wording should be V-B-A'd against the accepted #13062 text and the first consuming leaf's needs. Do not prematurely invent renderer UI or persistence mechanics in this ticket.

Contract Ledger Matrix

Decision Record impact

Aligned-with ADR 0020. No ADR amendment expected; this is a contract clarification under the docking line.

Acceptance Criteria

• learn/agentos/HarnessDockZoneModel.md explicitly addresses stale or unresolvable componentRef restore behavior.
• The clarification preserves the serializable-vs-runtime boundary: no DOMRect, window id, live instance, function, or credential material becomes part of persisted dock-zone state.
• The clarification does not prescribe drag-preview UI, split/tab rendering, or persistence implementation beyond the restore-seam boundary.
• PR evidence cites #13062 review feedback and explains whether the policy is concrete or intentionally adapter-defined.

Out of Scope

• Implementing a rendering adapter.
• Implementing drag-to-dock preview behavior.
• Implementing blueprint persistence.
• Adding a new src/layout/Dock primitive.
• Changing ADR 0020.

Avoided Traps

• Silent drop of unknown panes — rejected unless a future adapter explicitly proves it is the right user-facing recovery behavior.
• Hardcoding live runtime refs into the saved model — rejected by the #13062 contract boundary.
• Bundling renderer policy into a docs follow-up — rejected; this ticket names the seam, not the whole renderer.

Related

Parent epic: #13012 Refs #13030 Refs #13061 Refs PR #13062 Source review: https://github.com/neomjs/neo/pull/13062#pullrequestreview-4490979780

Live latest-open sweep: checked latest 20 open issues at 2026-06-13T04:55Z; no equivalent found. Closest source surfaces: #13030 and #13061. A2A in-flight sweep: checked latest 30 messages at 2026-06-13T04:55Z; no recent [lane-claim] / [lane-intent] overlaps this stale-componentRef follow-up. KB/local sweep: ask_knowledge_base for dock-zone componentRef restore unresolvable stale component reference HarnessDockZoneModel returned no matching ticket; exact rg over active/archive issues and discussions found no componentRef / stale-restore ticket.

Origin Session ID: d2d31447-5009-47a8-992e-9ecc35b806c1 Retrieval Hint: "dock-zone componentRef stale restore unresolvable component reference HarnessDockZoneModel PR 13062 review follow-up"