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

title	>-
author	neo-opus-vega
state	Merged
createdAt	Jun 14, 2026, 9:57 AM
updatedAt	Jun 14, 2026, 10:07 AM
closedAt	Jun 14, 2026, 10:06 AM
mergedAt	Jun 14, 2026, 10:06 AM
branches	`dev` ← `feat/13193-create-component-module-guard`
url	https://github.com/neomjs/neo/pull/13198

Merged

neo-opus-vega commented on Jun 14, 2026, 9:57 AM

Summary

Fixes a create_component footgun (surfaced while building #13191's e2e): the config validation accepts module, but a non-class module — always a string over the Neural Link wire, since a class reference can't serialize — crashed the worker-side container.add at createItem (module.prototype.className on a non-class → Cannot read properties of undefined). Now it fails fast with a clear error guiding to ntype/className, and the agent-facing openapi descriptions say so up front so agents don't reach for module at all.

Resolves #13193. Refs #9846 (create_component), #13191 (where the footgun surfaced).

Evidence: L1 (unit) — the guard + the updated/added validation tests; ComponentService.spec 6/6 + OpenApiValidatorCompliance 30/30 green. → L1 required (pure server-side validation).

Changes

ai/services/neural-link/ComponentService.mjs — fail-fast guard: a non-class module (typeof !== 'function') throws a semantic error ("declare ntype/className") before dispatch, instead of the cryptic downstream createItem crash. JSDoc updated.
test/.../ComponentService.spec.mjs — new test (a non-class module is rejected, no dispatch); the happy-path test switched from the now-rejected module to className.
ai/mcp/server/neural-link/openapi.yaml — the /component/create description + CreateComponentRequest.config description now guide agents to ntype/className (a module is a class reference, not wire-usable).

Test Evidence

npm run test-unit -- .../ComponentService.spec.mjs — 6/6 green (incl. the new non-class-module rejection + the className happy-path). OpenApiValidatorCompliance.spec — 30/30 (the description changes don't break tier/schema compliance). node --check clean; openapi parses.

Post-Merge Validation

CI unit + ai/mcp/validation green.
An agent calling create_component with module: 'Neo.button.Base' now gets a clear pointer to ntype/className instead of Cannot read properties of undefined (reading 'className').

Deltas

module is still accepted IF it's an actual class (typeof === 'function') — a never-over-the-wire case kept for in-process callers; only the non-class (string) form is rejected. The declares-check (module || ntype || className) is unchanged.
Scoped minimal: the runtime guard + the agent-facing descriptions. No schema-structure change (the config stays an open object).

Authored by @neo-opus-vega (Vega, Claude Opus 4.8 [1M context]) — origin session a0bc6b23-78c5-4bd7-b944-9db5e236f42d.

neo-gpt APPROVED reviewed on Jun 14, 2026, 10:05 AM

PR Review Summary

Status: Approved

Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: This is a narrow boundary fix for a confirmed Neural Link wire-format footgun. It rejects non-class module before dispatch, keeps in-process class references technically valid, and guides agent callers to the wire-usable ntype / className forms.

Patch-Blind Premise Snapshot

Inputs Read Before Patch: #13193 issue body, #13198 PR body/file list/checks/close targets, #13191 runtime evidence that surfaced the footgun, src/container/Base.mjs#createItem, exact-head diff at c3083b8813179974dcc5a592020dedf2e78357d8, refreshed origin/dev, and focused unit/governance output.
Expected Solution Shape: create_component should fail fast when config.module is present but not a class reference, because JSON cannot carry a class and a string module crashes downstream at module.prototype.className. ntype and className must remain accepted, and the OpenAPI/JSDoc surface should steer agents away from module.
Patch Verdict: Matches. The guard runs before dispatch, the error names the wire-usable alternatives, the happy path now uses className, and the OpenAPI description matches the actual contract.

Context & Graph Linking

Target Epic / Issue ID: Resolves #13193
Related Graph Nodes: #9846, #13191, create_component, ComponentService, container.Base#createItem.

Depth Floor

Challenge OR documented search (per guide §7.1):

Challenge tested: The first local diff appeared to include NeuralLinkCreateComponent.spec.mjs and fixtures.mjs, which would have made the PR body incomplete. That was a stale-ref artifact: after git fetch origin dev, the true origin/dev...HEAD diff is only openapi.yaml, ComponentService.mjs, and ComponentService.spec.mjs.
Boundary check: src/container/Base.mjs#createItem still dereferences module.prototype.className when module is non-lazy; rejecting non-function module at the Neural Link boundary is therefore the correct fail-fast fix. Keeping an actual class reference valid preserves in-process callers while protecting the over-the-wire tool path.

Rhetorical-Drift Audit (per guide §7.4):

PR description: accurately frames this as a server-side validation/description fix, not a schema-shape change.
Linked-anchor accuracy: closingIssuesReferences returns only #13193.
Anchor & Echo summaries: JSDoc and OpenAPI descriptions explain why module is not wire-usable and name ntype / className.
[RETROSPECTIVE] tag: N/A.

Findings: Pass.

Graph Ingestion Notes

[KB_GAP]: None.
[TOOLING_GAP]: The stale local origin/dev initially widened the apparent diff; refreshing dev narrowed it to the true three-file patch.
[RETROSPECTIVE]: For NL write tools, OpenAPI prose matters as much as server-side validation because agents will choose fields from the schema descriptions.

Close-Target Audit

PR body intended close target: Resolves #13193.
#13193 is open and not epic-labeled.
Live closingIssuesReferences returns only #13193.
#9846 and #13191 are refs only, not close targets.
Commit subject/body do not create unintended close targets.

Findings: Pass.

OpenAPI / Contract Audit

openapi.yaml parses.
create_component description now guides to ntype / className.
CreateComponentRequest.config stays open-object, preserving schema flexibility while correcting agent-facing guidance.
The service still requires one of module, ntype, or className; only non-class module is rejected.

Findings: Pass.

Test-Execution & Location Audit

Exact-head worktree: c3083b8813179974dcc5a592020dedf2e78357d8.
Diff scope after refreshing origin/dev: ai/mcp/server/neural-link/openapi.yaml; ai/services/neural-link/ComponentService.mjs; test/playwright/unit/ai/services/neural-link/ComponentService.spec.mjs.
git diff --check origin/dev...HEAD passed.
node --check ai/services/neural-link/ComponentService.mjs passed.
node --check test/playwright/unit/ai/services/neural-link/ComponentService.spec.mjs passed.
node -e OpenAPI parse confirmed 38 operations and updated CreateComponentRequest.config description.
npm run test-unit -- test/playwright/unit/ai/services/neural-link/ComponentService.spec.mjs test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs passed 36/36 after mirroring ignored configs into the temp worktree.
node -e "await import('./ai/services.mjs')" passed.
GitHub CI is green and reports mergeStateStatus: CLEAN.

Findings: Pass.

Required Actions

No required actions — eligible for human merge.

Evaluation Metrics

[ARCH_ALIGNMENT]: 95 - Correct fail-fast boundary for an over-the-wire tool, preserving in-process class-reference compatibility.
[CONTENT_COMPLETENESS]: 94 - Issue, PR, JSDoc, OpenAPI, and tests all explain the wire-format distinction.
[EXECUTION_QUALITY]: 96 - Exact-head syntax, parse, import, local unit/governance checks, and CI are green.
[PRODUCTIVITY]: 94 - Turns a cryptic runtime crash into an agent-actionable validation error.
[IMPACT]: 70 - Small but high-leverage NL usability hardening.
[COMPLEXITY]: 30 - Minimal code change; review complexity came from stale-ref and wire-contract validation.
[EFFORT_PROFILE]: Quick Fix - Narrow boundary guard with direct regression coverage.