What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	18308
title	Hard-cut dock topology persistence to keyed workspace records
state	Closed
labels	documentationenhancementairefactoringarchitecturecoredashboard
assignees	neo-gpt-emmy
createdAt	Sep 4, 2026, 8:17 PM
updatedAt	Sep 4, 2026, 10:19 PM
githubUrl	https://github.com/neomjs/neo/issues/18308
author	neo-gpt
commentsCount	1
parentIssue	18303
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[x] 18316 Add Workstation multi-window undo, redo, save, and reload, [x] 18272 An N-slot topology commit restores N documents and one view: no consumer has a sibling projection to converge, [x] 18284 Two independent Workstation roots share one drag namespace, so a cross-root drag commits into the wrong document, [x] 18315 Hydrate cold dock topologies and rebind warm reloads, [x] 18314 Unify Dock and Neural Link undo on the group cursor, [x] 18313 Record observed popup placement as a transaction participant, [x] 18312 Commit multi-workspace dock transactions atomically, [x] 18310 Add immutable per-group transaction history and cursor, [x] 18309 Bind transaction groups across window generations
closedAt	Sep 4, 2026, 10:19 PM

Hard-cut dock topology persistence to keyed workspace records

Closed v13.2.0/archive-v13-2-0-chunk-19 documentationenhancementairefactoringarchitecturecoredashboard

neo-gpt commented on Sep 4, 2026, 8:17 PM

Context

D#18224 resolved that one Workspace document and one multi-window topology are different durable artifacts. The accepted ADR and three sibling documents still describe positional windowDocuments[], while the converged design requires stable workspace keys. Zero backwards compatibility is explicit.

The Problem

neo.dock.layout.v1 currently mixes one Workspace layout with topology mode through captureScope and positional sibling documents. Registration order therefore participates in identity, the Neural Link contract promises a field that must disappear, and the generic Document name hides that every consumer treats it as one Workspace participant. Updating only code or only ADR prose would leave a shipped authority lying between merges.

The Architectural Reality

neo.dock.zone.v1 remains one WorkspaceDocument. neo.dock.layout.v1 and neo.dock.layoutCollection.v1 remain one Workspace's named layouts. Multi-window durable state gets its own keyed neo.dock.topology.v1 and neo.dock.topologyCollection.v1. The hard rename covers 24 static imports plus 3 dynamic imports and 503 Document. references across 31 files.

The Fix

In one freeze: amend ADR 0029; truth-sync DockZoneModel.md, NeuralLinkCapabilityMatrix.md, and the DockLayouts guide; rename model/Document.mjs / class / bindings to WorkspaceDocument with no alias; introduce the keyed topology envelope; remove topology-mode captureScope, positional windowDocuments[], and their positional readers in TopologyReconciler, Persistence, and DockService.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Workspace document identity	ADR 0029 + D#18224 criterion 12	`WorkspaceDocument`; `neo.dock.zone.v1` unchanged	none; old class/import fails	ADR + model guide	27-site zero-alias census
Workspace layout envelope	existing layout library	`neo.dock.layout.v1` remains single-workspace	reject topology fields	ADR + guide	parser positive/negative controls
Topology envelope	D#18224 criterion 12	keyed `workspaces`, placement hints, layout ids, aggregate fingerprint	unsupported/positional input rejected	all four authority surfaces	round-trip + old-field red control
Neural Link perspective contract	capability matrix + DockService	returns the new topology shape without `windowDocuments`	structured unsupported-schema refusal	capability matrix	exact tool contract arm

Decision Record impact

Amends ADR 0029.

Decision Record

Required: ADR 0029 amendment lands in this PR before every consuming leaf.

Discussion Criteria Mapping

Owns D#18224 criteria 5 and 12 plus OQ5's hard rename.

Acceptance Criteria

Document.mjs becomes WorkspaceDocument.mjs; all 24 static and 3 dynamic import sites move, all class/binding references agree, and no compatibility alias/re-export remains.
neo.dock.zone.v1, neo.dock.layout.v1, and neo.dock.layoutCollection.v1 retain their single-workspace meanings.
neo.dock.topology.v1 and neo.dock.topologyCollection.v1 use keyed workspace records and reject positional windowDocuments / topology captureScope.
ADR 0029, DockZoneModel.md, NeuralLinkCapabilityMatrix.md, DockLayouts guide, and all three shipped source readers change in the same PR.
Positive round-trip controls cover both single-workspace and topology envelopes; old positional/topology-layout inputs red with named structured refusals.
Generated outputs are updated only through their generators.

Out of Scope

Group runtime identity, history/cursor behavior, popup materialization, UI controls, or a migration reader.

Avoided Traps

No silent redefinition of layout.v1; no docs-first or code-first split; no alias; no third perspective mode inside the Workspace library.

Part of #18303. Source: D#18224. Blocks every consuming implementation leaf.

Origin Session ID: 01a06b6d-3323-7fa0-a10b-bbc4871c8780

Retrieval Hint: D18224 hard cut WorkspaceDocument topology.v1 windowDocuments ADR 0029

Creation freshness: live latest-open and all-status A2A sweeps found no equivalent leaf; #18272 is projection behavior and is reused separately.