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	16364
title	Implement the two-path install tier: Body default, Brain opt-in
state	Closed
labels	enhancementaiarchitecture
assignees	neo-kimi-iris
createdAt	Aug 2, 2026, 4:12 PM
updatedAt	Aug 2, 2026, 11:42 PM
githubUrl	https://github.com/neomjs/neo/issues/16364
author	neo-kimi-iris
commentsCount	0
parentIssue	16204
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 2, 2026, 11:42 PM

Implement the two-path install tier: Body default, Brain opt-in

Closed Backlog/active-chunk-12 enhancementaiarchitecture

neo-kimi-iris commented on Aug 2, 2026, 4:12 PM

Context

Follow-up of #16204 (the devDependency census, PR #16354), implementing the install-tier boundary the census ticket accepted: two documented install paths — Body by default, Brain opt-in. The census established the evidence base (#16204 issuecomment-5158183571): the native-compile subset is exactly one package (better-sqlite3), and its host-edge importer surface is exactly the two files #16180 and #16202 already own.

Live latest-open sweep at 2026-08-02T14:12Z (20 newest) + A2A in-flight claim scan (15 newest): no equivalent found.

The Problem

Every contributor cloning neomjs/neo compiles better-sqlite3 natively — including Body-only contributors who never run a Brain workload and never will. That compile is the stated Windows pain and a major reason the parity work existed. The census proved the compile subset is one package and mapped every direct importer: container-plane 8, host-edge 2, ad-hoc-script 17, test 30.

What does not exist is a tier: one install path that gives Body contributors everything they need (build tools, Body tests, shared tooling) without the native compile, and one documented opt-in that adds the Brain set for the swarm, CI, and Brain workers.

The Architectural Reality

package.json — dependencies: {} (empty, correct); devDependencies: 45 at filing; 41 after sibling #16363 shipped (PR #16369). The Brain set per the census: better-sqlite3 + chromadb (+ @chroma-core/default-embed, the runtime-resolved default embedder with no direct repo importer).
Falsified form, recorded: a nested ai/package.json does NOT tier the test tree — test/playwright/unit/ai/** resolves imports up to root node_modules, not ai/node_modules. The mechanism must handle the 30 test importers explicitly.
The test-side seam already exists: the Playwright unit config separates brain from body projects (unit-brain vs the rest). Brain specs import better-sqlite3 directly, so without the package they cannot even be collected — the gate must live at the project/fixture level, never per-spec test.skip (30 retrofit sites is the optionalDependencies fallacy in miniature).
Falsified alternatives (from the census ticket): (a) optionalDependencies + capability gating — bare imports of absent optionals throw; 56 direct call sites to retrofit; every miss is a runtime crash. (c) one tier, accept the compile — forfeits the stated Windows win.
Intake addendum (2026-08-02): the census (re-run live at 6c317b9048) confirms zero body/build importers for the Brain set, and surfaced 2 of 30 test importers sitting outside the brain seam — test/playwright/unit/hooks/{codexContextHook,kimiTurnPresenceHook}.spec.mjs statically import better-sqlite3 (graph-fixture builders). Handled by a named config match (the config's own idiom), not by per-spec edits. Also verified: prepare lifecycle (husky + initServerConfigs.mjs) imports no Brain package; chromadb's only dep is semver (shared); @chroma-core/default-embed pulls @huggingface/transformers (large prebuilt closure, no compile).

The Fix

Implement the accepted boundary:

Choose the mechanism (root package.brain.json merged by a small install script, a second documented npm install step keyed off an opt-in manifest, or an equivalent the implementer defends) — the mechanism is the implementation detail; the boundary above is the decision this ticket must not re-open.
Base path: npm install gives Body contributors build + Body tests + shared tooling, no native compile.
Brain path: one documented command adds the Brain set; the brain Playwright project runs only where that set is installed (project/fixture-level gate).
Docs: the two paths land in the contributor-facing docs (deployment guide — #16040 is a natural consumer).

Acceptance Criteria

A fresh-clone base install completes without compiling better-sqlite3 (receipt: install log on a platform where it previously compiled; Windows receipt strongly preferred — that is the pain being bought back).
The Brain opt-in is one documented command; after it, the brain unit project runs green.
The brain project is uncollectable-safe in the base install: running the unit suite with only the base set skips the brain project at the project level with a clear message — no collection crash, no per-spec edits.
CI runs the full matrix in the brain-enabled environment (no contributor-visible coverage lost).
Contributor docs name both paths and who needs which.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
`package.json › devDependencies.{better-sqlite3, chromadb, @chroma-core/default-embed}`	#16204 census (re-run live at intake)	Removed from the base manifest; identical pins move to `package.brain.json`	n/a (removal)	GETTING_STARTED	Tier-guard spec (absence assertion); fresh base-install log (AC1)
`package.brain.json` (new root manifest)	This ticket	New file carrying exactly the Brain-set pins; consumed by `buildScripts/util/installBrain.mjs`, never by npm directly	Malformed JSON → installer fails with a named parse error	Installer JSDoc + GETTING_STARTED	Spec: parse + required-pin assertions
`package.json › scripts["install-brain"]`	This ticket	`node ./buildScripts/util/installBrain.mjs` → `npm install --no-save <pins>` into root `node_modules`; `--dry-run` prints without executing	Plain `npm install` / `npm ci` prunes the Brain set (verified: npm 11.12.1 prunes extraneous) → re-run the command; documented	GETTING_STARTED + installer stdout	Spec: dry-run command shape; AC2 brain-green run
`test/playwright/playwright.config.unit.mjs › projects`	This ticket + the census test-seam	`buildProjects({brainPresent})` gates `unit-brain*` + `chroma-setup/teardown`; probe = Brain-set presence under root `node_modules`; `brainHookTestMatch` adds the 2 out-of-seam hook specs	Brain set absent → projects excluded with one clear line naming the skip + remedy; never a collection crash	Inline config comment + GETTING_STARTED	Spec: `buildProjects(false/true)` shapes; AC3 base-suite run shows the skip line
`.github/workflows/test.yml › Install dependencies step`	AC4	`npm ci` then `npm run install-brain` (all suites)	Installer failure fails the job (fail-closed)	Step comment	This PR's own CI run green
`package-lock.json`	This ticket	The 3 roots + their unique transitive closure surgically removed; shared deps retained; format-preserving edit	Round-trip parse + native-format match verified	n/a	`npm ci` exit 0 on base; AC1 receipt
`.npmignore`	Package hygiene	`package.brain.json` excluded from the published tarball	n/a	n/a	`npm pack --dry-run` listing
`.github/GETTING_STARTED.md`	AC5	Two install paths documented (Body default; Brain opt-in) + the prune caveat	n/a	The file itself	Review
`ai/deploy/Dockerfile` (review addendum R0)	The plane is a Brain environment	Arms the tier via `installBrain.mjs --ignore-scripts` after the full-tree COPY, before `npm rebuild better-sqlite3`	Scripts stay off; config materialization stays explicit	Dockerfile comment	`integration-unified` + `integration-parity` green at `78650e4b71`
`harness/pack.mjs › buildOrganismManifest` (review addendum R1)	Dependency-authority migration	Declared versions compose BOTH tier manifests (`brainPackageJson` option; call site reads `package.brain.json` when present)	Undeclared-in-both → hard error (fail loud, never a broken artifact)	Function JSDoc	`pack.spec.mjs` two-tier witness
`ai/scripts/diagnostics/devDependencyCensus.mjs` (review addendum R1)	Dependency-authority migration	Census reads both tier manifests; rows + totals carry `tier`	Absent brain manifest → base-only census	Module JSDoc + report totals	Census spec totals + tier vocabulary; `better-sqlite3` sighted as `brain`
`playwright.config.unit.mjs › CI admission` (review addendum R3)	RA-3 fail-closed	`assertBrainTierForEnvironment` throws under CI on absent/partial tier (all three roots probed)	Local base install stays skip-with-named-line	Config comment	Admission witnesses (both directions + partial install)
`buildScripts/util/installBrain.mjs › launcher` (review addendum R4)	Windows seam	`npm.cmd` on win32 via `shell: true` (the `build/all.mjs` idiom)	POSIX behavior unchanged	`resolveNpmCommand`	Spec: launcher resolver
`package.brain.json › versions` (review addendum R2 — superseded by T1 below)	Determinism	EXACT root pins (no ranges) — the determinism contract completed via the committed closure (row T1)	—	`$comment`	Spec: pin-shape
`package-lock.brain.json` (terminal addendum T1)	#16392, delivered in this PR	Committed exact closure (128 entries); installer resolves ONLY from it; manifest/lock disagreement is a named drift error	Missing/stale lock → named error + regeneration command	Installer JSDoc + GETTING_STARTED	Spec: exactness + root coverage + drift + missing-lock
`playwright.config.unit.mjs › hasBrainTier` (terminal addendum T2)	Terminal review T2	Probes consumable entrypoints per root (incl. the compiled `better_sqlite3.node` artifact), not directory names	Pruned/corrupt husk → not armed; load-based probes rejected (transformers load cost)	Config JSDoc	Witness: empty dirs / entrypoints-without-artifact / armed
Root `prepare` Windows portability (pre-existing, out of scope here)	#16393	Routed to successor — it blocks native Windows on dev today, independent of the tier	—	—	The successor ticket

Out of Scope

The five zero-usage removals — sibling ticket #16363 (shipped as PR #16369: 4 of 5 removed; mermaid retained on the portal-asset evidence).
The two host-edge importer removals — owned by #16180 (wake path) and #16202 (NL recorder); this ticket's mechanism must not depend on their landing order (either order works; note it in the PR).
chromadb client removal — it is a Brain-tier keep (container-side managers use the sanctioned JS client).

#16204 — the census (evidence + the accepted boundary; PR #16354)
#16363 — the removal sibling
#16180 / #16202 — host-edge importer owners
#16040 — deployment-guide consumer

Origin Session ID: session_5c970912-b750-4835-ad51-fbb3d2bc4ebe

Retrieval Hint: query_raw_memories("install tier Brain Body better-sqlite3 native compile brain project gate")

tobiu referenced in commit c47565e - "feat(build): two-path install tier — Body default, Brain opt-in (#16364) (#16389) on Aug 2, 2026, 11:42 PM

tobiu closed this issue on Aug 2, 2026, 11:42 PM