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	16515
title	Measured debt census of the ai folder: duplication, boundaries, placement
state	Closed
labels	enhancementaiarchitecture
assignees	neo-fable
createdAt	Aug 4, 2026, 10:41 PM
updatedAt	Aug 8, 2026, 1:46 PM
githubUrl	https://github.com/neomjs/neo/issues/16515
author	neo-fable
commentsCount	6
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 7, 2026, 2:49 PM

Measured debt census of the ai folder: duplication, boundaries, placement

Closed Backlog/active-chunk-12 enhancementaiarchitecture

neo-fable commented on Aug 4, 2026, 10:41 PM

Context

Operator assessment during the same friction→gold discussion (2026-08-04): "imho the debt inside the ai folder is extreme." Concurred with first receipts measured live; this ticket converts the assessment into an instrument so follow-up work is evidence-ranked instead of vibes-ranked. Live latest-open sweep at filing: latest 15 checked, no equivalent census lane; #16488/#16495 are single-boundary instances the census will contextualize, not duplicates.

The Problem

ai/ is 682 .mjs files / ~228k lines, and the visible sediment starts at its root: FIVE config-ish entries (config.mjs, config.template.mjs, configBase.mjs, ConfigProvider.mjs, planeConfig.mjs), agent/ + demo-agents/ + Agent.mjs, services/ + services.mjs, docs/ + a root sdk-manifest.md. Known systemic classes with prior receipts: module-scope heavy imports making the SDK boundary non-load-bearing (#16488: chromadb at module scope forces a Brain-tier package to merely load; ~20 external readers block the clean init refactor), placement drift severe enough that the structural-pre-flight skill exists because of ai/ misfilings (PR #11008 lineage), and the ADR-0019 forbidden-pattern catalog existing at all. First duplication family already measured and ticketed: four lock/lease implementations (#16514).

The debt's cost is not size — it is that boundaries are not load-bearing, so every change's blast radius is unknowable without archaeology.

The Architectural Reality

Instruments exist: npm run --silent ai:structure-map -- --files --loc (the placement gate), rg for pattern families, ADR-0019 as the config-authority lens, learn/agentos ADRs as the placement authority.
Hard constraint: a downstream production plane deploys from this tree — the census is READ-ONLY; no moves, no renames, no import changes ride this lane. Prescriptions become tickets, each individually deployment-safe.

The Fix

A census artifact (ticket comment series or one learn/agentos-adjacent report, driver's call) with four measured chapters:

Duplication families — pattern census (locks/leases done → #16514; candidates: retry/backoff shapes, atomic-write/tmp-rename, config readers, health/receipt emitters, path resolution), each with file list + call-site count + rule-of-three verdict.
Boundary violations — module-scope imports crossing the SDK/service boundary (the #16488 class, full set), import cycles, ai/→src/ and reverse reaches outside sanctioned entrypoints.
Placement drift — files whose home contradicts the structure-map/ADR authority (the scripts-vs-daemons-vs-services axis), root-level sediment disposition (incl. the five config entries — audited UNDER ADR-0019's SSOT lens, which may bless some of them; the census records WHY per entry).
Ranked follow-up set — each finding priced (blast radius × fix cost × deployment risk) and shaped into pool tickets; the ranking IS the deliverable that makes every later move cheaper.

Acceptance Criteria

All four chapters published with reproducible commands per claim (every number re-derivable by any peer).
Zero tracked-file mutations from this lane (read-only census; deployment redline untouched).
Follow-up tickets filed for the top-ranked findings (rule-of-three families and boundary classes at minimum), each one-PR-shaped or an explicitly licensed split.
The ADR-0019 lens applied to every config-surface claim (critical gate: read the ADR before authoring that chapter).

Out of Scope

Executing any consolidation/move (each rides its own ticket).
#16488/#16495/#16514 themselves (in flight; the census references and ranks around them).

Decision Record impact

none by the census itself; individual findings may propose amends cases, each carried by its own follow-up ticket.

#16514 (first family, filed from the same discussion), #16488, #16495, ADR-0019, the structural-pre-flight skill lineage (PR #11008).

Origin Session ID: 1913de09-6dc0-4d1e-a9a3-b51c33b46cdc

Retrieval Hint: query_raw_memories("ai folder debt census duplication families boundary violations placement drift read-only")