DockLayouts now has distinct model and persistence packages, while the current adoption guide compresses persistence and perspectives into one decision. The refactor made the ownership boundaries clearer in code and larger in conceptual surface.
The Problem
Readers cannot currently answer, from one guide, what is committed document truth, what is a semantic operation, what is projected per window, what remains runtime-only, how perspectives wrap documents, or how restore fails closed. Re-deriving those rules from Document, Operations, Persistence, topology reconciliation, and perspective code invites parallel state stores.
The Architectural Reality
model/Document.mjs, Operations.mjs, Persistence.mjs, TopologyDiff.mjs, TopologyReconciler.mjs, persistence/PerspectiveLibrary.mjs, and RestorePlanner.mjs own separate parts of the state lifecycle. ADR 0029 keeps serializable App-worker documents authoritative and excludes DOM/window/runtime objects from persistence.
The Fix
Create learn/guides/uibuildingblocks/DockLayoutsStateAndPersistence.md: a deep conceptual guide to documents, semantic operations, topology changes, persistence envelopes, perspectives, restore planning, and fail-closed recovery.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
State guide
ADR 0029 + current model/persistence classes
Teach the committed/projected/runtime boundary and why it exists
Revalidate after refactors
New guide
Current source + real capture/restore
Persistence story
Persistence + perspective + restore owners
Explain wrapper validation and fail-closed restore without copying schemas
Link reference authority
Same guide
Valid/invalid live receipts
Registration
Existing guide siblings
One discoverable UI-building-blocks guide
No generated-output edits
tree + SEO inputs
lint + rendered portal
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains accepted state authority.
Acceptance Criteria
The guide clears the full guide-authoring bar: source/tool-grounded narrative, reader-owned benefits, lived maintainer voice, and at least one render-verified flowchart TD.
The guide separates explanation from reference: no inlined API/schema/test catalog, and no ticket or PR ids in guide prose.
The new source guide is registered in learn/tree.json and the SEO PRIORITIES input; generated sitemap/LLM outputs remain untouched.
Current-source consistency, guide lint, tree lint, portal rendering, and an independent cross-family whole-guide review are recorded in the PR.
The guide distinguishes document, operation, projection, runtime interaction, perspective, and restore-plan ownership.
One capture → mutate → restore story is exercised against the current subsystem, including an invalid/refused restore.
The guide explains why pixels, DOM geometry, window ids, and reveal state do not enter durable JSON.
Schema/operation enumerations stay in reference authority rather than being copied into prose.
Out of Scope
Changing schemas, adding migrations, duplicating JSDoc, or replacing the Adoption guide.
Avoided Traps
Do not describe a screenshot as state truth, present perspectives as raw documents, or make persistence a generic serialization tutorial.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Retrieval Hint: query_raw_memories("DockLayouts guide series post-refactor final API")
Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.
Context
DockLayouts now has distinct model and persistence packages, while the current adoption guide compresses persistence and perspectives into one decision. The refactor made the ownership boundaries clearer in code and larger in conceptual surface.
The Problem
Readers cannot currently answer, from one guide, what is committed document truth, what is a semantic operation, what is projected per window, what remains runtime-only, how perspectives wrap documents, or how restore fails closed. Re-deriving those rules from
Document,Operations,Persistence, topology reconciliation, and perspective code invites parallel state stores.The Architectural Reality
model/Document.mjs,Operations.mjs,Persistence.mjs,TopologyDiff.mjs,TopologyReconciler.mjs,persistence/PerspectiveLibrary.mjs, andRestorePlanner.mjsown separate parts of the state lifecycle. ADR 0029 keeps serializable App-worker documents authoritative and excludes DOM/window/runtime objects from persistence.The Fix
Create
learn/guides/uibuildingblocks/DockLayoutsStateAndPersistence.md: a deep conceptual guide to documents, semantic operations, topology changes, persistence envelopes, perspectives, restore planning, and fail-closed recovery.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains accepted state authority.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Out of Scope
Changing schemas, adding migrations, duplicating JSDoc, or replacing the Adoption guide.
Avoided Traps
Do not describe a screenshot as state truth, present perspectives as raw documents, or make persistence a generic serialization tutorial.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Origin Session ID: 309a78d7-2d95-4f23-bdfc-69d2ae393a5d
Retrieval Hint:
query_raw_memories("DockLayouts guide series post-refactor final API")Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.