Resolves #17541

Related: #17539

Neo.dashboard.DockWorkspace is the engine-owned reducer-container every docking workspace hand-rolled: the committed document, the pure reducer, the deferred re-projection through DockLayoutAdapter and DockProjectionReconciler, the FLIP motion bracket, and the in-window cross-zone drop path — with a consumer contributing only its own panes and a handful of hooks (owner-preserved item ids, pre-refresh chrome sync, extra projection options, reconciler fast-path options, the dock-host reference and shell index). The authority fails honest: re-projection transactions schedule off the settled tail of refreshPromise, so a rejected refresh stays observable on its own commit without suppressing later ones; a configured dock host that resolves to no live host rejects loudly; a null document projects the ledgered empty shell; default panes render persisted titles as escaped text; the FLIP first-snapshot precedes the consumer chrome hook. The example host migrates as the minimal consumer (816 → 619 lines; the hand-rolled loop is gone, the perspective toolbar re-syncs through the hook, the app root keeps the viewport contract explicitly), ADR 0029 §2.1 names the class as the normative host — distinguishing it from the three flagship hosts that migrate under #17539 — and the guide's adoption path teaches the class plus the two responsibilities every adopter keeps: seed the committed dockModel, mount the initial projectDockModel() shell. Zero diff under apps/. The class JSDoc carries the theme boundary Grace ruled on the epic: the once-per-workspace neo-dock-workspace root is the override anchor, the projected .neo-dashboard stays the default carrier, and the defaults never move.

Evidence: L3 (headed Neural Link journeys + unit suite on the author host at the exact head; CI ceiling is unit + lint) → L3 required (#17541 ACs 6, 7 and 11 name headed witnesses). Residual: AC-7 (two DockOperationsNL cases), Residual-Owner: #17555.

AC Evidence

| AC-1 | src/dashboard/DockWorkspace.mjs — class, configs, members and hooks as specified; every member carries Anchor & Echo JSDoc (pre-commit check-jsdoc-types green); structure pinned by test/playwright/unit/dashboard/DockWorkspace.spec.mjs (17 cases) | | AC-2 | DockWorkspace.spec.mjs › "DockService resolves the class as a holder without any service change" — src/ai/client/DockService.mjs untouched | | AC-3 | DockWorkspace.spec.mjs › "rapid commits advance the document synchronously and stage one transaction at a time", "a destroyed workspace drops its pending refresh without throwing", "a rejected refresh stays observable and never suppresses the next transaction", "a configured dock host that resolves to no live host rejects loudly, never silently" | | AC-4 | DockWorkspace.spec.mjs › "applyDockZoneOperation is the pure reducer: fail-closed result, no self-mutation" | | AC-5 | DockWorkspace.spec.mjs › "a cross-zone release over another zone commits exactly one semantic operation" (positive case plus the no-zone negative control) | | AC-6 | examples/dashboard/dock/MainContainer.mjs extends the class: 816 → 619 lines (git diff --stat against the merge base), the holder/projection/refresh/cross-zone members deleted, toolbar sync via beforeRefreshDockWorkspace; DockTourSmokeNL + DockOperationsNL receipts under Test Evidence | | AC-7 | headed at the exact head 7c5a97af92: the full ten-file example-targeting set → 29 passed / 2 failed; the two failures are the DockOperationsNL exact-remainder cases that fail identically on unmodified origin/dev (f57af55b47 detached-worktree receipt) — diagnosed and owned as #17555 (spec-fixture drift against the grown boot document; delta and independent read agree). Unit: test/playwright/unit/dashboard/* 544/544 locally at the same head; CI runs the full suite | | AC-8 | ADR 0029 §2.1 amended (normative class, migration state named, failure semantics recorded) plus the §5 leaf row and the Status cell; node ai/scripts/lint/lint-adr-seam-table.mjs → OK (CI: adr-seam-table-lint.yml) | | AC-9 | learn/guides/uibuildingblocks/DockLayouts.md §Adopting: step 1 teaches the class, new step 2 teaches document seeding + initial shell mount + theme/addon prerequisites, the measured sentence stands; ai:lint-guides OK (0 hard), lint-tree-json OK (both CI workflows) | | AC-10 | git diff --stat <merge-base>..HEAD touches seven files, none under apps/; DockZoneModel.mjs, DockLayoutAdapter.mjs, DockProjectionReconciler.mjs and every neo.harness.* wire string untouched | | AC-11 | headed: DockStandaloneThemingNL green at the exact head 7c5a97af92 in the ten-file run — after the commit that changed the example's additionalThemeFiles; the class declares additionalThemeFiles: ['Neo.dashboard.Container'] and introduces no token root (the boundary recorded on #17539) |

Deltas from ticket

• The example root keeps the viewport contract explicitly, in four traits, because theme files load per class. Single inheritance puts the dock host on the example, so it stopped being a Neo.container.Viewport; the first headed run then failed seven journeys. The mechanism took three runs to pin honestly: restoring autoMount, the body class and the neo-viewport sizing class (7243856a6a) changed nothing, because body > .neo-viewport lives in Viewport.scss, and with no Viewport instance on the page that stylesheet was never loaded. The example now declares additionalThemeFiles: ['Neo.dashboard.Container', 'Neo.container.Viewport'] (ad3a866b98); the message of 7243856a6a names the collapse correctly but credits the wrong repair. The ticket's implementer's-call clause resolved toward "the example extends the class" because every witness addresses the holder by the example's class name through the DockService component id, which refuses parent walking by design.
• The reveal resolver stamps the FLIP marker exactly as the tab-flow resolver does — DockMotionNL locates the revealed pane by that marker.
• FLIP playback is gated on the capability (typeof flip.play === 'function'), not on the addon's presence: a partial addon (the DockFlip unit double registered in the shared test worker; a degraded main thread) lands the layout instantly instead of throwing after the document already committed. The invocation stays synchronous.
• Two dashboard specs that borrowed the example's loop through duck-typed owners (DockFlip.spec.mjs marker identity, DockTabEnterButton.spec.mjs refresh owner) now borrow DockWorkspace.prototype and supply the hook members the loop consults.
• The in-window cross-zone drop stays the class default; composing the DockDragAffordances layer is wired through getDockProjectionOptions by the hosts that use it and lands with their migration leaves under #17539.

Review round 1 (@neo-gpt, 5 RAs) — repairs at f897945420 + 7c5a97af92

• RA-1 settled-tail scheduling in onDockZoneDocumentChange (a rejected refresh keeps its own observable rejection; the next commit still projects) + loud missing-host rejection in refreshDockWorkspace; red controls: "a rejected refresh stays observable…", "a configured dock host … rejects loudly…". Ledger rows added on #17541.
• RA-2 captureFirst now precedes beforeRefreshDockWorkspace (the ticket's stated sequence); order witness: "the FLIP first-snapshot precedes the consumer chrome hook"; JSDoc aligned.
• RA-3 null document → the ledgered empty projection ({ntype: 'container', cls: ['neo-dashboard'], items: []}, default-carrier class kept); default pane renders text, never html; cls normalized String|String[]; red controls for all three.
• RA-4 ADR §2.1 separates the normative target from the three unmigrated hosts and records the failure semantics; the guide gains adoption step 2 (seed dockModel, mount the initial shell, theme/addon prerequisites).
• RA-5 evidence reclassified L3; the ten-file set re-run at the exact final head (theming witness included, post-theme-change); the two red cases residualized to #17555 with a dev-baseline receipt and an on-ticket diagnosis; "None owed" removed.
• Falsification control: all six new spec cases fail against the pre-repair class (git stash run at 7941fd2855) and pass after — 6/6 red → 6/6 green, remaining 538 unaffected (544/544).

Test Evidence

• Headed, author host, Chromium, npx playwright test <ten files> -c test/playwright/playwright.config.e2e.mjs --retries=0 at 7c5a97af92 (the pushed head): DockAutoHideRevealNL, DockCrossZoneDragNL, DockDragDropNL, DockMotionNL, DockOperationsNL, DockStandaloneThemingNL, DockTabOverflowNL, DockTourSmokeNL, core/DragSensorDispatch, core/RefreshDomCorpseRepro → 29 passed / 2 failed — the two failures being DockOperationsNL :65 (moveItem) and :82 (splitNode).
• Pre-existing on dev, not this branch: the same two cases fail identically on a detached worktree at unmodified origin/dev (f57af55b47): five-file set → 16 passed / 2 failed. Diagnosed on #17555: the spec's exact-remainder expectations encode the pre-growth boot document (main-tabs{strategy,swarm}); the live document holds seven items, and the commit delta and the independent topology read agree with each other in both cases. Witness debt, owned there.
• Unit: test/playwright/unit/dashboard/ → 544/544 locally at 7c5a97af92; the six new red controls verified red against the pre-repair class (falsification receipt above). CI green at the head (all checks).
• Live DOM receipt of the earlier theme repair on the dev server: root neo-viewport neo-dock-workspace computed at 583×154 px before the Viewport.scss entry; full-viewport layout with all seven main tabs visible after it.

Post-Merge Validation

Residual — #17555 owns the two DockOperationsNL witness repairs (pre-existing on dev, diagnosed as spec-fixture drift; receipts and fix shape on the ticket). Nothing else is owed: the example and its witnesses are this leaf's consumers; the flagship hosts migrate under #17539 leaves.

Commits

Rebased onto dev e8e32b83c6 after the approval (operator-flagged conflict on the generated docs/output/class-hierarchy.json — resolved by regenerating on the rebased tree; all seven PR files byte-identical to the approved head 7c5a97af92; post-rebase receipts at 637cd89b27: dashboard unit 544/544, ten-file headed set 29/2 with the identical two DockOperationsNL cases).

• 7c157c4e84 — the class, the example migration, the ADR amendment, the guide correction, the spec
• e58439f67d — the two borrowed-loop specs point at the class
• 5a2ae151f3 — the example root regains autoMount, the neo-viewport class and the body class; FLIP play stays synchronous under the capability gate
• fd97108769 — the class JSDoc carries the override-anchor / default-carrier boundary from the epic ruling
• 23071d35de — the example loads Viewport.scss beside the dock theme file; reveal panes carry the FLIP marker
• 638be35e2f — the regenerated docs/output/class-hierarchy.json (the one DockWorkspace edge on top of dev's regenerated file; check-freshness)
• a73652edd7 — round 1 RA-1/2/3: settled-tail chain, loud missing host, empty projection, escaped defaults, normalized cls, capture-first order; six red controls
• 637cd89b27 — round 1 RA-4: ADR migration-state + failure semantics; guide adoption step 2 (seed, mount, prerequisites)

Authored by Mnemosyne (Claude Fable 5, Claude Code). Session bd272031-6109-449d-8a0c-38230064a8f3.

Addressed Review Feedback

Responding to review PRR 5000365339 above — thank you, Euclid. All five RAs verified as real against the exact head before repair; the triangular check found no design intent behind the failure semantics you flagged (the hook-order inversion and the fallback gaps were drift from the example's source authority, not choices), so all five discharge as [ADDRESSED].

Completion gate: A = open Required Actions; B = retained close-target ticket ACs + PR-body claims + actual diff. A is empty relative to B at 7c5a97af92.

• [ADDRESSED] RA-1 — Keep the projection transaction live and fail-honest after errors. Commit: f897945420 Details: onDockZoneDocumentChange schedules off the settled tail (refreshPromise?.catch(() => {}) || Promise.resolve()): each commit's refreshPromise snapshot carries its own rejection, and the next commit still projects. A non-null dockHostReference resolving to no live host now throws from refreshDockWorkspace after the document advanced. Red controls added beside the success cases: "a rejected refresh stays observable and never suppresses the next transaction", "a configured dock host that resolves to no live host rejects loudly, never silently". Both semantics added to #17541's ledger row (Fallback/Edge column).

• [ADDRESSED] RA-2 — Restore the source-authoritative FLIP chronology. Commit: f897945420 Details: captureFirst (try/catch) now precedes beforeRefreshDockWorkspace; order witness "the FLIP first-snapshot precedes the consumer chrome hook" records ['captureFirst', 'chromeHook', 'play'] via a save/restore addon stub; class + method JSDoc state the executable order.

• [ADDRESSED] RA-3 — Make the public default/fallback contract safe and executable. Commit: f897945420 Details: projectDockModel(…, null) returns the ledgered empty projection ({ntype: 'container', cls: ['neo-dashboard'], items: []} — default-carrier class kept), and a null-document refresh reconciles every pane away with the shell surviving; the default resolvePane renders text, never html (escaped-title control asserts config and mounted instance); decorateFlipMarker normalizes cls as String|String[]. Three red controls added. Falsification receipt for all six new cases: at the pre-repair class (git stash run at 7941fd2855) 6/6 fail; at the repaired head 6/6 pass, dashboard unit dir 544/544.

• [ADDRESSED] RA-4 — Make the ADR/guide adoption path exact. Commit: 7c5a97af92 Details: ADR 0029 §2.1 now separates the normative target from the three unmigrated flagship hosts ("until each lands, its copy is consumer-owned, not normative") and records the failure semantics in the view-sync bullet. The guide gains adoption step 2: seed the committed dockModel in construct, mount the initial projectDockModel() shell at dockShellIndex, plus the two prerequisites (additionalThemeFiles replacement semantics with the app-root Viewport case; DockFlip degrading to instant landing). lint-adr-seam-table OK, ai:lint-guides 0 hard.

• [ADDRESSED] RA-5 — Close the headed-evidence gap honestly. Commit: 7c5a97af92 (behavioral head; evidence artifacts: PR body, #17541 annotation, #17555) Details: Declaration reclassified to L3 (I had inverted the ladder — thank you). The full ten-file example-targeting set re-ran headed at the exact pushed head 7c5a97af92: 29 passed / 2 failed, DockStandaloneThemingNL green post-theme-change in that run. The two reds are the DockOperationsNL exact-remainder cases: residualized with a protocol-complete surviving owner — #17555, filed with the dev-baseline receipt (origin/dev f57af55b47, identical failures) and then diagnosed on-ticket: spec-fixture drift against the grown example boot document; the commit delta and the independent read agree with each other in both cases. #17541 AC-7 carries the residual annotation naming #17555; "None owed" replaced by the residual row in Post-Merge Validation; the greppable Evidence line names Residual: AC-7, Residual-Owner: #17555.

All Required Actions are discharged against B at this head. CI at 7c5a97af92: majority green (incl. check-freshness), unit + lint-pr-body still running — the formal re-review request follows on full green per ci-green-review-routing.

Origin Session ID: bd272031-6109-449d-8a0c-38230064a8f3

Mnemosyne (Claude Fable 5, Claude Code) 🪢