Docking design spec: perspectives, cross-window drag, SharedWorker seam

Context

The operator re-ranked the docking lane (2026-07-02) as an agent-harness cornerstone: the bar is Qt-Advanced-Docking-System-class WITH Neo's multi-window reality, and the assessed gap is not another implementation leaf but the missing design tier (operator direction comment on the parent: IC_kwDODSospM8AAAABIcPOUw). The parent epic's own history evidences unconverged design: its scope was reframed to "Docking on the Infinite Canvas — QT superset + multi-window" (2026-06-15) and reverted to "QT-parity docking polish" (2026-06-21) — a title oscillation is a design question wearing a rename. This ticket is the design gate that settles the tier above the remaining leaves. Filed under the product-surface planning lane ([lane-claim] broadcast 2026-07-02T02:30Z; #13158 self-assigned).

The Problem

The dockZone.v1 foundation is real and shipped (model contract, semantic-operation executor, split/tab adapter, drag preview, splitter resize, auto-hide model seam). But the remaining capability leaves (auto-hide UI #13280, named perspectives, grouped tab-drag/overflow) plus the multi-window bar share design questions that per-leaf contract settling cannot answer coherently:

• The persistence wrapper (neo.harness.dockLayout.v1) models layoutId/title/revision, but perspective semantics — what a perspective captures across MULTIPLE windows on one SharedWorker heap, restore into a different window topology, fail-closed restore — are unspecified.
• Cross-window drag semantics (a dock item dragged between Chromium popups sharing one App-Worker heap; boundary with the #13028 OS-window reintegration leaf) are unowned by any leaf.
• The SharedWorker seam — which docking state is per-window render projection vs worker-owned shared truth — is implicit in the adapter but never stated as a contract.
• The core-lift clause (contract §Ownership Boundary: stays in src/dashboard/ until a second non-dashboard consumer proves reuse) is approaching its trigger: the Institution Cockpit (#13444) and FM-UX surfaces (#13015) are becoming exactly that second consumer class. Fire, defer, or amend is a design decision, not a leaf decision.
• Operator assessment: parts of the existing interaction code are brittle — brittleness at the interaction layer is the symptom of missing design authority above it.

The Architectural Reality

• Contract of record: learn/agentos/HarnessDockZoneModel.md (dockZone.v1 — §Split Projection, §Serializable vs Runtime State, §Ownership Boundary, §Demand Validation).
• Shipped substrate: src/dashboard/DockZoneModel.mjs (semantic ops incl. resizeSplit, setItemAutoHidden), src/dashboard/DockLayoutAdapter.mjs, src/dashboard/DockSplitter.mjs, apps/agentos/view/DockPreview.mjs.
• Verification surface: examples/dashboard/dock/ (#13247 — slices landing).
• Multi-window substrate: Chromium popups on one SharedWorker App-Worker heap (ADR 0020 embodiment vessel); window-manager leaves #13025/#13028 are siblings, not children.
• Consumers-in-waiting: #13444 cockpit panes and #13015 FM-UX cards live INSIDE the docking shell; their container contract is this spec's downstream interface.

The Fix

Produce the docking design-tier specification as a contract document in learn/agentos/ (sibling-lift from HarnessDockZoneModel.md; exact filename settled at authoring per the sibling pattern — no new .mjs, so structural-pre-flight Stage 0 does not fire; if the cross-window seam proves to need binding decision authority beyond a contract doc, the spec escalates that single section to an ADR and says so explicitly). One PR. Sections the spec MUST settle:

1. Layout model formalization — the full dockZone.v1 state space incl. multi-window: worker-owned truth vs per-window projection (the SharedWorker seam), as a normative table.
2. Named perspectives — capture scope (single-window vs whole-topology), restore semantics into changed window topologies, fail-closed behavior, revision migration.
3. Cross-window drag — semantic-operation shape for item movement between windows, riding the existing preview→operation path; boundary with #13028 consumed, not owned.
4. Grouped drag + overflow — the multi-item operation contract (leaf-implementable afterward).
5. Core-lift clause disposition — fire / defer-with-named-trigger / amend §Ownership Boundary, given the cockpit/FM consumer class.
6. Container contract for embedded product surfaces — the minimal interface #13444 panes and #13015 FM-UX cards consume (coordination: #13015 steward has the options DM, 2026-07-02).

Contract Ledger Matrix

Decision Record impact

aligned-with ADR 0020. The spec itself declares whether the cross-window/SharedWorker seam requires a new ADR (escalation path named in The Fix); this ticket does not amend or supersede any ADR.

Acceptance Criteria

• Spec PR merged containing all six sections, each with explicit contracts (not aspirations).
• SharedWorker seam stated as a normative table: worker-owned vs window-projected state classes.
• Perspective semantics define capture scope, cross-topology restore, and fail-closed behavior.
• Cross-window drag defined as semantic operations on the existing preview→operation path (no parallel drag system — inherited guardrail).
• Core-lift clause dispositioned with a named trigger (fire / defer-until-X / amend).
• Container-contract section names its two consumers (#13444, #13015) and their minimal interface.
• JSON-first persistence guardrail restated and applied to every new persisted shape (no DOMRect, screen coordinates, windowId, live components in layouts).
• Cross-family review from ≥1 non-fable family before merge.
• Unstarted leaves (perspectives, grouped-drag) reference the spec as upstream; in-flight #13280 explicitly NOT gated on it.

Out of Scope

• Implementation of the capability leaves (they follow, one Contract-Ledgered leaf per capability, per the parent's epic-review discipline).
• Executing the core src/layout/Dock lift (the spec dispositions it only).
• Window-manager leaves #13025 / #13028 (consumed as boundaries).
• #13015 stewardship or FM-UX implementation (only the container interface is specified here).
• Public performance claims (inherited #13032 guardrail).

Avoided Traps

• Spec-as-epic sprawl — rejected: one document, one PR, six named sections.
• dockZone.v1 redesign — rejected: the tier is additive on the shipped model (the parent's own rule).
• Gating in-flight work — rejected: #13280 proceeds on its landed model seam; only unstarted leaves sequence behind the spec.
• Importing Qt-ADS architecture wholesale — rejected: Qt-ADS is the capability bar, not the design — its single-process, single-window-tree assumptions do not survive Neo's worker/multi-window reality (industry-friction-radar 3-step abstraction applies: extract the friction points, never the architecture).

Related

Parent: #13158. Foundation: the #13030 chain. Consumers: #13444, #13015. Boundaries: #13028, #13025. Verification: #13247. In-flight sibling: #13280.

Live latest-open sweep: checked latest 20 open issues at 2026-07-02T02:33Z; no equivalent found. A2A in-flight sweep: 30-message all-states scan at 02:33Z; only same-scope claim is my own [lane-claim] (02:30Z, first-claim-timestamp mine).

Origin Session ID: 4185a2ee-ff65-4544-9cc1-049d73e56649 Retrieval Hint: "docking design tier spec cross-window SharedWorker seam perspectives" · query_summaries: "product-surface planning lane #13158 claim"