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	15240
title	Amend ADR 0029: claim arbitration, gesture outcome states, vessel lifecycle
state	Open
labels	documentationenhancementaiarchitecture
assignees	[]
createdAt	1:07 PM
updatedAt	1:07 PM
githubUrl	https://github.com/neomjs/neo/issues/15240
author	neo-fable-clio
commentsCount	0
parentIssue	15239
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[ ] 15248 DragCoordinator teardown hygiene: exact-once cleanup across gesture terminals, [ ] 15246 Workspace-set composition, continuous remote preview, claim arbitration, [ ] 15245 Popup acquisition contract: platform defaults from the measured matrix, [ ] 15244 Dock tear-out: lift the proxy-to-popup opt-out into dock semantics

Amend ADR 0029: claim arbitration, gesture outcome states, vessel lifecycle

Open Backlog/active-chunk-6 documentationenhancementaiarchitecture

neo-fable-clio commented on 1:07 PM

Context

The first merge-ordered leaf of epic #15239 (graduated from D#15204 at cycle-4b). The Discussion's Step-Back (comment DC_kwDODSospM4BDXN_) established Decision Record: REQUIRED — amend ADR 0029: ADR 0005 §2.1/§5.4 fires on durable lifecycle-behavior change + multi-ticket decomposition, and independently ADR 0029's own line-36 amend-first guard fires because the ratified claim protocol replaces first-intersecting target resolution. No new ADR, no supersede — ADR 0029's premise survives; the amendment adds what the multi-window choreography needs.

The Problem

ADR 0029 (harness docking design) currently designs cross-window drag as semantic ops (§2.3) but leaves three load-bearing behaviors as implementation choices that D#15204's convergence proved must be contract:

Physical target resolution today is Window.getWindowAt() / DragCoordinator.getWindowAtExcept() first-intersecting-rect — overlapping windows resolve by registration order, not stable identity.
The gesture-to-effect boundary has no outcome states: CrossWindowDragTarget.onRemoteDrop() may return null yet DragCoordinator.onDragEnd() calls source onRemoteDropOut() unconditionally — a no-commit drop can retire the source gesture.
Vessel lifecycle (popup close on empty, close-vs-commit ordering) is undesigned.

Consuming implementation (epic leaves G1/G3/G4) cannot start until the amendment owns these — the epic's write-surface map sequences this PR before all of them.

The Architectural Reality

The amendment target is learn/agentos/decisions/0029-harness-docking-design.md. The ratified contracts to encode (D#15204 body, anchor 2026-07-16T09:15:31Z):

The claim protocol (from OQ3 [RESOLVED_TO_AC]): session-scoped gesture token; short-lived hit-claims keyed on stable workspace/zone identity (never windowId / registration order); validity/expiry; deterministic tie (earliest valid claim; stable-identity lexicographic final tiebreak), stale (ignored), no-claim (fail closed: no preview, no commit). The ≥3-window overlap witness (exactly one preview + one commit per gesture) is the contract's falsifier.
The outcome machine (from OQ5b [RESOLVED_TO_AC]): IN_SOURCE → DETACHED_MOVING → HOVERING_CLAIM → { COMMITTED_TARGET | TERMINAL_DETACHED | REJECTED | CANCELLED } with the four invariants: source cleanup/empty-vessel close only after COMMITTED_TARGET; reject/no-preview restores the source with zero model mutation; model commit precedes window close (close failure never rolls back or double-reintegrates); preview/claim/timer/activeTargetZone/registration/vessel cleanup idempotent exact-once.
Vessel admission truth (cycle-4c, DC_kwDODSospM4BDXXd): windowOpen returns a BOOLEAN — a blocked popup never throws; the vessel section binds the full admission state machine on that truth.
Boundary constraints: placement hints stay additive on dockLayout.v2; ADR 0034's Electron shell may improve vessel materialization, never fork placement/arbitration semantics.

The Fix

One docs-only PR amending ADR 0029: an "Amendment (2026-07)" section (or integrated §2.3/§2.5 extensions per the ADR's own structure) carrying the three contracts above verbatim-in-substance, the admission truth, the additive-hints constraint, and the merge-order note (amendment precedes consuming implementation). The PR Resolves this leaf and Refs #15239.

Contract Ledger

Target Surface	Source of Authority	Behavior	Fallback / Edge Case	Docs	Evidence
`learn/agentos/decisions/0029-harness-docking-design.md` (amendment section)	D#15204 graduation (§6.2 quorum, cycle-4b) + ADR 0005 §2.1/§5.4	encodes the claim protocol, the outcome machine + four invariants, vessel lifecycle/admission (Boolean truth), additive-hints constraint	amendment-not-supersede: existing §§ stay authoritative where untouched	the ADR itself	PR diff review against the D#15204 body anchors; the ≥3-window witness lands with G3's implementation leaf, not here

Decision Record impact

amends ADR 0029 (successor-risk audit N/A — amend-in-place, no supersession, premise preserved).

Decision Record

Required: this ticket IS the required record's delivery vehicle (per D#15204's graduated Decision-Record line).

Acceptance Criteria

The amendment text carries the claim protocol with all determinism cases (tie / stale / no-claim) and the stable-identity requirement.
The outcome machine with its four invariants is encoded, including the named no-commit defect it forbids (onRemoteDrop() null must not trigger source retirement).
Vessel lifecycle: close = post-commit render-target effect; commit-precedes-close; the Boolean admission truth stated.
The additive dockLayout.v2 hints constraint + the ADR 0034 non-fork boundary stated.
Merge-order note: this amendment lands before G1/G3/G4 consuming implementation.
Docs-only diff (no runtime change); cross-family review.

Out of Scope

Any consuming implementation (G1/G3/G4 leaves) · the OQ2 spike (its own leaf) · re-litigating the graduated contracts (the revalidationTrigger on #15239 governs reopening).

Parent #15239 (epic) · D#15204 (source; body anchors cited above) · ADR 0029 / ADR 0005 / ADR 0034 · #13028 / #8160 (the landed primitives the contracts extend).

Live latest-open sweep: latest 20 at 2026-07-16T10:56Z (+ last-step re-check of latest 10); no equivalent. A2A claim sweep: no competing lane-claim in the herd window (wake daemon disabled; operator-directed session).

Origin Session ID: c5d7cd6b-4e01-45fd-aa59-5ccbc0e5f091 Retrieval Hint: "ADR 0029 amendment claim arbitration outcome machine vessel lifecycle merge-ordered"