Cut DockLayouts anatomy and wire vocabulary to final form

Context

Epic #17836 is the implementation authority graduated from Discussion #17818. DockLayouts is a v13.2 greenfield surface: npm 13.1 shipped generic Container / Panel plus only three experimental Dock* foundation files, not the present 28-module subsystem or its integrated consumers. The operator ruled out migration, compatibility facades, aliases, dual schemas, and old/new parallel implementations.

This leaf establishes the final Engine anatomy and wire language before semantic feature work continues. It must be one behavior-preserving, independently reviewable PR: mechanical/package/wire changes and the explicit retirement of pre-release compatibility code, without adding setActiveItem, resizeEdgeZone, or new consumer behavior.

Superseded predecessor

#17779 predates the later graduated greenfield architecture and is superseded as an implementation prescription: its flat-package placement, compatibility-alias option, frozen neo.harness.* wire family, and one-PR ownership/persistence migration conflict with D#17818. This leaf absorbs only the behavior-preserving PerspectiveLibrary name/authority merge required by the final anatomy. Its unlanded read-only projection Store, workspace-set ownership, and configurable transport ideas remain implementation input for the later semantic leaf; they are not parallel authority and do not enlarge this behavior-frozen PR.

The Problem

The current DockLayouts implementation is spread across 28 flat dock-specific modules under src/dashboard/, three execution-layer JavaScript satellites, and 22 SCSS files. Model, projection, interaction, persistence, and window choreography share one namespace; class paths, JSDoc targets, theme identities, SCSS mirrors, and neo.harness.* schema strings preserve pre-release history rather than one coherent product vocabulary.

This creates a live sequencing hazard. #17820 targets src/dashboard/DockSplitter.mjs, but the graduated architecture relocates that class and requires it to reuse the generic Neo.component.Splitter mechanism instead of creating a second live-resize engine. Until this leaf lands, dock-specific feature work can be built against the wrong path and inheritance model.

The Architectural Reality

The following contracts remain binding:

• generic src/dashboard/Container.mjs and Panel.mjs stay at the package root; apps/colors remains unchanged;
• ADR 0029’s worker-owned document truth, per-window projection/runtime state, dock-blind DragCoordinator, semantic-operation commit path, and JSON-first persistence remain in force;
• execution-layer code stays with its runtime owner: main-thread Flip under src/main/addon/, Neural-Link Dock Service under src/ai/client/, generic dashboard SortZone under src/draggable/dashboard/;
• persistence/PerspectiveLibrary becomes the sole collection/perspective authority by merging current DockPerspectiveStore with DockZoneModel collection statics;
• DockSplitter keeps its disambiguating name but consumes/subclasses generic Neo.component.Splitter for DragZone/live-resize/generation mechanics and uses GestureClaimArbiter; dock code owns only document descriptors and terminal semantic commit;
• no facade or compatibility re-export survives.

The cross-repository pre-cut protection is already live, not future work: Agent Institution dev pins neo.mjs to exact Engine SHA 17b59aad8f95c55c916fd6bb8bd6a0f43bd2d687 in package.json (Engine commit 2026-08-28 07:27Z, before this anatomy cut). The merge gate verifies that pin remains exact; the later consumer leaf replaces it only with the final rewritten Engine merge SHA.

Structural pre-flight selected src/dashboard/dock/{model,projection,interaction,persistence,window} from the exact current package census. ArchitectureOverview.md has no dashboard inventory row today, so this structurally significant move updates that map and links ADR 0029 in the same PR.

The Fix

Move and refactor the DockLayouts modules into the graduated package/namespace:

src/dashboard/
├── Container.mjs
├── Panel.mjs
└── dock/
    ├── Workspace.mjs
    ├── model/
    │   ├── Document.mjs
    │   ├── Operations.mjs
    │   ├── Persistence.mjs
    │   ├── PreviewContract.mjs
    │   ├── TopologyDiff.mjs
    │   └── TopologyReconciler.mjs
    ├── projection/
    │   ├── LayoutAdapter.mjs
    │   ├── Reconciler.mjs
    │   └── MotionSignal.mjs
    ├── interaction/
    │   ├── DockSplitter.mjs
    │   ├── Rail.mjs
    │   ├── RevealOverlay.mjs
    │   ├── RevealStateMachine.mjs
    │   ├── Preview.mjs
    │   ├── PreviewProducer.mjs
    │   ├── DragAffordances.mjs
    │   ├── DropIndicators.mjs
    │   ├── TabSortZone.mjs
    │   ├── TabEnterButton.mjs
    │   └── KeyboardCommands.mjs
    ├── persistence/
    │   ├── PerspectiveLibrary.mjs
    │   └── RestorePlanner.mjs
    └── window/
        ├── DragTarget.mjs
        ├── Participation.mjs
        ├── WorkspaceSet.mjs
        ├── TearOut.mjs
        ├── VesselConversion.mjs
        ├── VesselEmbodiment.mjs
        └── VesselPark.mjs

The tree above is binding for this leaf: every listed file must exist at that exact final path, and no additional DockLayouts module may remain outside it without amending Epic #17836.

The final namespace mirrors the tree: Neo.dashboard.dock.*, with responsibility subnamespaces below it. Short responsibility names replace redundant Dock* prefixes except interaction.DockSplitter.

Apply the same deterministic vocabulary to:

• every Engine import and class/JSDoc link;
• string-keyed additionalThemeFiles identities;
• structural SCSS and all five theme mirrors;
• Workstation and dashboard-example imports/configs;
• main-thread and Neural-Link satellite paths;
• unit/component/whitebox test imports and fixtures;
• ArchitectureOverview, ADR 0029, DockLayouts guides, and the landed model-contract guide.

Hard-cut the wire family:

• collapse current layout v1/v2 into final neo.dock.layout.v1;
• rename every retained positive identity into the graduated ten-concept neo.dock.* inventory;
• move all unsupported-version fixtures into the new family so they still prove version rejection;
• retain one old-family rejection control proving neo.harness.* is no longer accepted;
• delete all migration readers, including the four current v1 compatibility sites;
• introduce no alias, fallback parser, dual reader, or migration path.

Behavior remains frozen except for the explicit old-schema rejection and removal of compatibility branches. Existing semantic operations, projection results, cross-window choreography, auto-hide, persistence CRUD, and consumer behavior must remain equivalent under final names and homes.

Contract Ledger

Decision Record Impact

Decision Record impact: supersedes ADR 0029 §2.9’s persisted-schema migration clause for this unshipped greenfield surface; amends the ADR only where the graduated architecture explicitly changes names, ownership, and wire vocabulary.

ADR successor-risk: adr-amendment-required — the PR must update ADR 0029 before/with the hard cut. Other ADR 0029 contracts remain binding.

Decision Record

Required. Amend ADR 0029 to record the neo.dock.* family, layout-version collapse, negative controls, old-family rejection, deliberate absence of migration/compatibility, final package/namespace, and PerspectiveLibrary/DockSplitter ownership.

Acceptance Criteria

• Generic src/dashboard/Container.mjs and Panel.mjs remain at root; apps/colors requires zero source change.
• Every dock-specific Engine module has exactly one final home under src/dashboard/dock/{model,projection,interaction,persistence,window}; no dock-specific module remains flat at the package root.
• Every class namespace mirrors its final path; interaction.DockSplitter is the only deliberate Dock* qualifier inside the domain namespace.
• Main-thread Flip, Neural-Link Service, and generic dashboard SortZone remain in their execution-layer homes with only deterministic path/name updates.
• Current DockPerspectiveStore plus collection statics merge into the sole persistence/PerspectiveLibrary; all five measured consumers repoint and no parallel authority survives.
• Before re-parenting, add a dedicated DockSplitter equivalence spec against the current component.Base + direct-DragZone implementation. The same assertions must pass unchanged after adopting generic Neo.component.Splitter: inherited config/afterSet behavior, drag start/move/terminal, cancel/destruction, proxy/no-proxy fallback, generation fencing, and exactly one dock semantic commit. A positive control must fail if the generic mechanism is bypassed.
• Final DockSplitter consumes/subclasses generic Neo.component.Splitter, uses GestureClaimArbiter, and does not duplicate generic DragZone/live-resize/generation mechanics; the pre/post equivalence receipt proves dock behavior remains unchanged.
• The final seven runtime neo.dock.* identities and six new-family unsupported-version controls match corrected D#17818 OQ7; proposed-only windowPlacementHints, the retired perspective alias, and never-landed standalone topology are not wire identities; current layout v1/v2 collapse into neo.dock.layout.v1.
• One old-family negative control proves neo.harness.* is rejected; no alias, migration reader, compatibility parser, or dual schema remains.
• All four measured current v1 migration sites are deleted: DockZoneModel.mjs:49-52, DockZoneModel.mjs:956, DockZoneModel.mjs:1374, and DockPerspectiveStore.mjs:309 at the graduated source coordinate.
• Every Engine import, export, JSDoc link, string-keyed theme identity, SCSS structural/theme mirror, Workstation/example reference, and test fixture resolves only the final vocabulary.
• Existing unit, component, and whitebox E2E behavior witnesses remain green at final paths, including persistence, projection, cross-window, auto-hide, splitter terminal/cancel, and Workstation/example journeys. Deferred-evidence annotation (PR #17841 review RA-4, added by the claimer): the whitebox NL subset is external-Brain-runtime-gated post-split and cannot execute in this repo's CI or sandbox; #17844 owns running it at (or after) the merge SHA and posting receipts here. The unit and component tiers are green in-lane.
• learn/benefits/ArchitectureOverview.md gains the DockLayouts package row linked to ADR 0029; ADR 0029 and the DockLayouts/model guides describe the final architecture and wire family.
• The PR is behavior-frozen except explicit old-schema rejection and compatibility deletion; it does not introduce setActiveItem, resizeEdgeZone, or consumer feature changes.
• Before merge, verify Agent Institution dev still pins neo.mjs to exact pre-cut Engine SHA 17b59aad8f95c55c916fd6bb8bd6a0f43bd2d687; no floating branch or later Engine revision is admitted until the consumer leaf repoints to the exact rewritten merge SHA.

Out of Scope

• setActiveItem, resizeEdgeZone, edge splitter UX, reveal behavior changes, or new semantic operations;
• Agent Institution import/style/runtime migration to the rewritten Engine;
• live-preview feature implementation from #17820;
• new read-only projection Store, workspace-set ownership, or persistence-transport behavior from superseded #17779; the later semantic leaf must disposition those ideas after the final anatomy exists;
• moving generic Container/Panel/SortZone into the DockLayouts domain;
• migration tooling, compatibility facades, alias exports, diagnostics, ledgers, census artifacts, or proof-only deliverables;
• unrelated Qt-parity docking work.

Avoided Traps

• One mega behavior PR: anatomy/wire and new semantics remain separate review units.
• Path-only move: leaving old namespaces, theme strings, JSDoc targets, or wire values creates silent drift.
• Compatibility by habit: preserves an unshipped history and violates the greenfield ruling.
• Second perspective authority: reintroduces the parallel Store/Library hazard.
• Second splitter engine: duplicates the generic mechanism #17819 already established.
• Consumer break without a pin: makes the external repository uninstallable between merge boundaries.

Related

Parent: #17836
Blocks: #17820
Related: #13158
Related: #17539
Supersedes: #17779
Post-cut consumer leaf: neomjs/neo-agent-institution#39
Pre-cut consumer pin: Agent Institution package.json → Engine 17b59aad
Source: Discussion #17818

Origin Session ID: 01a03dec-efe5-71b3-8c19-e6b29187b970

Retrieval Hint: query_raw_memories("D#17818 anatomy wire hard cut neo.dock PerspectiveLibrary DockSplitter generic Splitter")

Creation freshness: checked the live created-descending latest 20 open Engine issues and the all-status latest 30 A2A messages at 2026-08-28T21:03Z; no equivalent anatomy/wire leaf or competing claim exists. Knowledge Base/local corpus returned the older docking authorities but no equivalent leaf; the known-stale local mirror was not treated as live authority.