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	16803
title	Tour-reset geometry admission must carry the reconciler outcome, not the request
state	Closed
labels	bugairefactoringarchitecture
assignees	neo-opus-ada
createdAt	Aug 9, 2026, 5:26 PM
updatedAt	Aug 9, 2026, 5:43 PM
githubUrl	https://github.com/neomjs/neo/issues/16803
author	neo-opus-ada
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 9, 2026, 5:43 PM

Tour-reset geometry admission must carry the reconciler outcome, not the request

Closed Backlog/active-chunk-14 bugairefactoringarchitecture

neo-opus-ada commented on Aug 9, 2026, 5:26 PM

Context

#16412 asks the two tour-reset call sites to stop declaring an unverified geometryOnly: true. Implementing it surfaced that the call site was never the right place to fix, and the ticket's prescription — derive the flag from a document compare — cannot be made correct. This leaf carries the shape that replaced it, so #16412 can keep its unmet recorded-tour criterion open rather than being closed by a partial delivery.

The Problem

A derived predicate at the call site duplicates a rule the consumer already owns, and duplicated it more weakly. Measured at e4082b2723: a four-category DockTopologyDiff test returns true for active-tab-only, split-orientation-only, structural child-order-only and auto-hide-only resets, every one of which DockProjectionReconciler.reconcileStableTopology refuses from its in-place path. A predicate that is weaker than its consumer's authority is worse than the literal it replaced, because it looks proven.

Strengthening the predicate does not fix the class — it reproduces it one axis later, and drifts again the next time the reconciler's admission rule changes.

The Architectural Reality

apps/workstation/view/Workspace.mjs — refreshDockWorkspace({geometryOnly}) forwards the flag both into DockProjectionReconciler.reconcileProjection and, afterwards, into DockFlip.play.
src/dashboard/DockProjectionReconciler.mjs — geometryOnly only gates whether reconcileStableTopology is attempted; it returns null on any node/type/ancestry/order/orientation delta and falls through to the staged transaction. Passing the flag here is safe by construction.
src/main/addon/DockFlip.mjs — play({geometryOnly}) declares something strictly stronger: "no topology swap can be pending".

One flag serves two different contracts. The reconciler reads it as a request; DockFlip reads it as a fact. Only the second can be wrong, and only after the reconciler has already decided.

The Fix

Report the path actually taken and forward that instead of the request:

reconcileProjection returns landedInPlace at both exits — true from the in-place branch, false from the staged transaction.
Workspace.refreshDockWorkspace destructures it and passes it to DockFlip.play.
The call sites go back to requesting geometryOnly: true, which is now honestly an admission request.
Any call-site predicate is deleted rather than strengthened.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`DockProjectionReconciler.reconcileProjection` return	`src/dashboard/DockProjectionReconciler.mjs`	Adds `landedInPlace` to both return shapes; all existing fields unchanged	Purely additive — existing destructuring consumers are unaffected	JSDoc at both returns	dashboard + workstation suites
`Workspace.refreshDockWorkspace` `options.geometryOnly`	`apps/workstation/view/Workspace.mjs`	Documented as an admission REQUEST, never a stable-topology claim	`operation === 'resizeSplit'` derivation untouched	JSDoc at the option	seam tests below
`DockFlip.play` `options.geometryOnly`	`src/main/addon/DockFlip.mjs`	Receives the reconciler's outcome; contract wording unchanged	Existing geometry guards remain the second line	play() JSDoc	seam tests below

Decision Record impact

none

Acceptance Criteria

reconcileProjection reports landedInPlace from both the in-place and staged exits
DockFlip.play receives that outcome; the caller's request never reaches it
A staged fallback is not reported as geometry-only even when geometry-only was requested
A proven in-place landing keeps its admission, so the change is not the trivially safe always-false
Both seam tests fail if DockFlip is never reached, rather than passing on a null capture
No call-site topology predicate remains in Workspace
resizeSplit derivation behaviour is unchanged
Dashboard and workstation suites green

Out of Scope

The recorded-tour reset receipt (#16412 AC4) — an e2e/on-camera artifact this seat cannot capture; it stays open on #16412
reconcileStableTopology's own admission rule, which is the authority this change defers to rather than modifies
The #16406 tab-drag defect

Avoided Traps

Strengthening the predicate. An exact topology projection covering identity/type/ancestry/order/orientation plus active and auto-hide state would pass today's counterexamples and still be a second copy of someone else's rule. The duplication is the defect, not its current precision.
Editing the failing call-site test green. The assertion expecting geometryOnly: false at the call site is removed because that contract moved downstream; keeping it would pin the superseded design.

Refs #16412 · #16403 (made the flag load-bearing) · #16391 (the landed-in-place discriminator) · #14650 (the dockZone.v1 diff vocabulary the rejected approach would have used)

Live latest-open sweep: checked latest 20 open issues at 2026-08-09T15:25:18Z; no equivalent found. A2A in-flight sweep: no claim on this scope.

Retrieval Hint: "tour reset geometryOnly landedInPlace reconciler outcome not request DockFlip admission"

tobiu referenced in commit 04d15fc - "fix(dashboard): DockFlip is told the reconciler outcome, not the request (#16803) (#16788) on Aug 9, 2026, 5:43 PM

tobiu closed this issue on Aug 9, 2026, 5:43 PM