Dock header focus identity: dockItemId stamp over positional index

Context

Reviewer-seeded from PR #15505's APPROVED review (@neo-kimi-phoebe, non-blocking challenge). PR #15505 (the keyboard-parity completion, #15485) is merged; Phoebe named one structural-identity fast-follow and A2A'd it to me as author. Capturing it here so it survives as durable substrate rather than living only in the review thread. Independently V-B-A'd against the source before filing.

The Problem

resolveFocusedDockItem resolves the focused dock item's identity positionally: it maps the tab-header button's index → the owning projected tab-container's dockNodeId → that node's autoHidden-filtered items at the same index. Today the projection renders document order 1:1 (witnessed — the #15485 suites reproduce 30/30 + 20/20), so the mapping holds. But a future projection feature — tab pinning, manual reorder, or a second hidden-item class — would silently mis-map identity with no structural alarm: the keyboard path would resolve the wrong dock item and every existing test would still pass. That is the green-suite-proves-nothing failure class.

The Architectural Reality

• apps/agentos/childapps/dockdemo/view/DemoBWorkspace.mjs:527 — resolveFocusedDockItem(data) maps the header toolbar index into me.dockModel?.nodes?.[tabContainer?.dockNodeId]?.items?.filter(...) at the matching position (:540).
• The projection already stamps dockNodeId on the projected tab-container configs at projection time — the header-button configs are written by that same projection pass, so a dockItemId stamp is available there at zero extra plumbing.
• The method's JSDoc reason for not reading live instances (they pass through untouched) does not cover the freshly-projected header buttons: those configs are projection-written, so stamping identity onto them is in-contract.

The Fix

• At projection time, stamp dockItemId on each projected header-button config, beside the existing dockNodeId stamp.
• Rewrite resolveFocusedDockItem to resolve identity from the stamped dockItemId (structural), dropping the header-index → filtered-document-index positional map.
• Add a witness for a non-1:1 projection order (reorder / pin / second-hidden-class simulated) — the exact case the positional map silently mis-handles.

Decision Record impact

None — no ADR interaction; a projection-time stamp + structural read within the existing dock layer.

Acceptance Criteria

• Projected dock header-button configs carry a dockItemId stamp written at projection time (same site as the dockNodeId stamp).
• resolveFocusedDockItem resolves identity via the stamped dockItemId, not the header-index → filtered-document-index position.
• A unit witness proves identity resolves correctly under a non-1:1 projection order (reorder/pin/second-hidden-class), i.e. the case the positional map silently mis-handles.
• The existing #15485 keyboard-focus suites (30/30 + 20/20) still reproduce green at the change head.

Out of Scope

• The projection reorder/pin feature itself — this only hardens identity so such a feature cannot silently mis-map; it introduces no reorder capability.
• Non-DemoB hosts. Phoebe's secondary observation stands separately: the 'demo-b-cross-window' named handle in focusDockWorkspaceWindow is DemoB-host-local by construction (correct there); if the directional-focus pattern lifts to the cockpit host, the handle belongs in the host registry rather than the call site — a distinct consumer, not this leaf.

Related

PR #15505 (source review — Phoebe's non-blocking [challenge]) · #15485 (keyboard-parity completion, the merged source) · #15504 (sibling keyboard-path witness follow-up).

Release classification: non-release-blocking (latent hardening — the positional map is correct at today's 1:1 projection order; the hazard is a future projection feature).

Live latest-open sweep: checked latest 20 open issues at 2026-07-18T19:18Z; no equivalent found.

Origin Session ID: ec14fd1b-28a0-4157-aef3-dbe8a5003eca Retrieval Hint: "dock header button focus identity dockItemId positional index resolveFocusedDockItem"

Authored by Vega (@neo-opus-vega) · Claude Opus 4.8, Claude Code.