Context
Undo history and reload persistence have different lifetimes. Warm F5 happens while the SharedWorker Group survives and should rebind without replay. Cold boot starts a new Group, hydrates one durable topology snapshot, and has empty history. Popup creation is user-activation gated and restore must not depend on permission.
The Problem
Current consumers persist partial live-layout state per window and identify additional documents positionally. Reload can leave two live root Workspaces, bind the popup to the orphan, or require popup permission before semantic restore exists. Cold selection among multiple saved roots is implicit.
The Architectural Reality
A Group topology library owns keyed Workspace documents, placement hints, active layout identity, and fingerprint. It is distinct from the single-Workspace PerspectiveLibrary and from session history. TopologyLibrary-class persistence belongs beside the existing dock persistence siblings; warm rebind belongs to the Group carrier, cold materialization to the root controller.
The Fix
Persist/select keyed topology snapshots; define cold active-layout selection; create a new Group with empty history; hydrate all semantic participants before presentation; open popup slots only behind user activation; preserve headless participants and fallback affordances on refusal. Warm reload claims the surviving (groupId, workspaceKey) and moves the same Workspace/panes into the new document without a write or popup recreation. Retire a zero-binding Group only after durable persistence and a bounded reconnect lease.
Structural Placement
A new topology persistence class matches src/dashboard/dock/persistence/PerspectiveLibrary.mjs; sibling-file-lift applies in that directory. Generic lease/binding logic stays in the Group.
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| topology library |
keyed topology schema leaf |
named/active snapshots per logical root |
fail closed on unknown schema |
guide/JSDoc |
round-trip collection arms |
| warm reload |
D#18224 criterion 13 |
rebind same Group/Workspace/history, no write |
duplicate live binder forks |
JSDoc |
F5 identity/cursor arm |
| cold boot |
D#18224 criterion 13 |
new Group, one selected snapshot, empty history |
explicit selection/new blank topology |
guide |
two-saved-root selection arm |
| popup materialization |
browser activation boundary |
semantic hydrate first; user-activated windows second |
headless participants + open-as-window/fallback |
guide |
blocked-popup control |
| retirement lease |
bounded connect-window precedent |
retire only after durable snapshot and zero references |
headless-dirty + retry on persistence failure |
JSDoc |
lease/late-connect/failure arms |
Decision Record impact
Implements amended ADR 0029 topology persistence and lifecycle.
Decision Record
Required prerequisite: the hard-cut ADR/wire leaf.
Discussion Criteria Mapping
Owns criterion 4 and the hydrate/materialization/retirement half of criterion 13.
Acceptance Criteria
Out of Scope
Projection of sibling views, undo command routing, or cross-application Group bridging.
Avoided Traps
No replay-on-boot; no popup-first hydrate; no implicit only-snapshot choice; no unbounded lease; no lossy retirement; no per-window localStorage authority.
Related
Part of #18303. Blocked by the hard-cut and Group identity leaves. Enables #18272 and the Workstation journey.
Origin Session ID: 01a06b6d-3323-7fa0-a10b-bbc4871c8780
Retrieval Hint: D18224 warm F5 rebind cold topology hydrate popup activation headless dirty
Creation freshness: live latest-open and all-status A2A sweeps found no equivalent hydrate/rebind leaf; #18272 owns projection after adoption.
Context
Undo history and reload persistence have different lifetimes. Warm F5 happens while the SharedWorker Group survives and should rebind without replay. Cold boot starts a new Group, hydrates one durable topology snapshot, and has empty history. Popup creation is user-activation gated and restore must not depend on permission.
The Problem
Current consumers persist partial live-layout state per window and identify additional documents positionally. Reload can leave two live root Workspaces, bind the popup to the orphan, or require popup permission before semantic restore exists. Cold selection among multiple saved roots is implicit.
The Architectural Reality
A Group topology library owns keyed Workspace documents, placement hints, active layout identity, and fingerprint. It is distinct from the single-Workspace PerspectiveLibrary and from session history.
TopologyLibrary-class persistence belongs beside the existing dock persistence siblings; warm rebind belongs to the Group carrier, cold materialization to the root controller.The Fix
Persist/select keyed topology snapshots; define cold active-layout selection; create a new Group with empty history; hydrate all semantic participants before presentation; open popup slots only behind user activation; preserve headless participants and fallback affordances on refusal. Warm reload claims the surviving
(groupId, workspaceKey)and moves the same Workspace/panes into the new document without a write or popup recreation. Retire a zero-binding Group only after durable persistence and a bounded reconnect lease.Structural Placement
A new topology persistence class matches
src/dashboard/dock/persistence/PerspectiveLibrary.mjs; sibling-file-lift applies in that directory. Generic lease/binding logic stays in the Group.Contract Ledger
headless-dirty+ retry on persistence failureDecision Record impact
Implements amended ADR 0029 topology persistence and lifecycle.
Decision Record
Required prerequisite: the hard-cut ADR/wire leaf.
Discussion Criteria Mapping
Owns criterion 4 and the hydrate/materialization/retirement half of criterion 13.
Acceptance Criteria
headless-dirtyGroup and retries rather than discarding the only truth.Out of Scope
Projection of sibling views, undo command routing, or cross-application Group bridging.
Avoided Traps
No replay-on-boot; no popup-first hydrate; no implicit only-snapshot choice; no unbounded lease; no lossy retirement; no per-window localStorage authority.
Related
Part of #18303. Blocked by the hard-cut and Group identity leaves. Enables #18272 and the Workstation journey.
Origin Session ID: 01a06b6d-3323-7fa0-a10b-bbc4871c8780
Retrieval Hint:
D18224 warm F5 rebind cold topology hydrate popup activation headless dirtyCreation freshness: live latest-open and all-status A2A sweeps found no equivalent hydrate/rebind leaf; #18272 owns projection after adoption.