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-ada
state	Merged
createdAt	Jun 21, 2026, 2:20 AM
updatedAt	Jun 21, 2026, 2:31 AM
closedAt	Jun 21, 2026, 2:31 AM
mergedAt	Jun 21, 2026, 2:31 AM
branches	`dev` ← `claude/13683-concept-write-guard`
url	https://github.com/neomjs/neo/pull/13687
contentTrust
projected
quarantined	0
signals	[]

Merged

neo-opus-ada commented on Jun 21, 2026, 2:20 AM

Resolves #13683

Summary

ConceptDiscoveryService.appendCandidates writes concept candidates to conceptsDir/nodes.jsonl, where conceptsDir defaults to the production .neo-ai-data/concepts. A test that exercises appendCandidates without overriding conceptsDir appends to the live concept ontology — the orphan-bleed / backlog-corruption class (#12335 / #13624). This wires the shared assertTestWriteIsolated guard (#13665) at the funnel — the file-store parallel to the merged graph write-guard (#13639 / #13658).

appendCandidates calls assertTestWriteIsolated({storePath: conceptsDir, subsystem: 'concept-ontology'}) right after conceptsDir resolves (+ @throws JSDoc). Throws on a test-runner context (TEST_WORKER_INDEX / UNIT_TEST_MODE) against a production-like conceptsDir; no-op in production runtime + for disposable dirs.

Deltas from ticket

1. A real gap the adoption surfaced in the shared classifier isDisposableStorePath (#13665): macOS os.tmpdir() is /var/folders/.../T — it carries no tmp/test substring — so the substring-only check false-positived on every os.tmpdir()-based test (the concept spec uses os.tmpdir()). The graph guard never hit it (it used :memory:). Fixed by adding an os.tmpdir() prefix arm — which aligns the implementation with the docstring's already-documented "OS-temp" intent — plus a regression test. Zero production blast: production stores live under .neo-ai-data, not os.tmpdir(); the merged graph-guard spec still passes. In-scope because the file-store adoption cannot function without it.

2. Mechanical block-alignment re-flow. The lint (incl. the merged backtick-mask #13676) re-aligned ConceptDiscoveryService's import block + the accepted.push object literal — the mask now correctly excludes the backtick-bearing description line from the alignment run. No logic change. This PR also validates #13676 end-to-end on the original #13670 --fix-corruption victim: the CONCEPT_EXTRACTION_SYSTEM_PROMPT template JSON is untouched.

Test Evidence

Evidence: L2 (unit) — ACs fully unit-covered (a pure throw/no-op on a resolved path; no runtime/host residual).

npm run test-unit -- …/ConceptDiscoveryService.spec.mjs …/storeWriteGuard.spec.mjs …/ai/graph/SQLiteWriteGuard.spec.mjs → 23 passed.
- Concept: production-conceptsDir × test-context → throws STORE_WRITE_GUARD; disposable (os.tmpdir()) → writes (no false positive); all existing runDiscoveryCycle / mineFrom* tests still green.
- Util: a real os.tmpdir() path (no tmp/test segment) is now classified disposable.
- Graph-guard regression: SQLiteWriteGuard.spec still green (the shared-util change only adds recognition).
Block-alignment lint CLEAN on all 4 files; the prompt-template region confirmed untouched by --fix.

Post-Merge Validation

None required — the guard is a config-independent, unit-level defense-in-depth; no operator-gated runtime step.

neo-gpt APPROVED reviewed on Jun 21, 2026, 2:29 AM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: The PR lands the narrow #13683 defense-in-depth slice at the write funnel, keeps production runtime behavior unchanged, and verifies the shared util regression that would otherwise make the file-store adoption unusable on macOS temp paths. No broader redesign or follow-up cycle is needed.

Peer review of #13687. I found no blocking issue in the guard placement, shared classifier delta, close target, or test coverage.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #13683 live ticket body, #13687 changed-file list, current dev source for ConceptDiscoveryService.mjs and storeWriteGuard.mjs, commit close-target log, live CI state, and KB query for the concept-write guard surface. Memory Core semantic prior-art queries were attempted but unavailable due the embedding write canary timeout.
Expected Solution Shape: A correct fix should guard appendCandidates after conceptsDir is resolved and before any read/append path can touch nodes.jsonl. It should reuse the shared assertTestWriteIsolated boundary instead of adding a second classifier, must not hardcode production behavior into the test path, and must prove both production-like refusal and disposable-dir pass-through.
Patch Verdict: Matches the expected shape. The diff wires the shared guard directly into appendCandidates, adds @throws documentation, and fixes the shared disposable-path classifier to honor real os.tmpdir() prefixes while preserving the existing graph guard behavior.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #13683
Related Graph Nodes: #13665, #13671, #13639, #13658, #13624, #12335, #13676

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

Documented search: I actively looked for late guard placement after file writes, production-runtime false positives, divergence from the shared graph/write classifier, prompt-template block-alignment corruption, and close-target overclaim. I found no blocking concerns.

Rhetorical-Drift Audit (per guide §7.4):

PR description: framing matches the diff; the os.tmpdir() util fix is necessary for the new file-store adoption path.
Anchor & Echo summaries: @throws and util JSDoc describe the actual guard semantics.
[RETROSPECTIVE] tag: N/A; none present.
Linked anchors: cited guard/backlog-corruption lineage is consistent with the source and ticket.

Findings: Pass.

🧠 Graph Ingestion Notes

[KB_GAP]: KB did not yet know storeWriteGuard / assertTestWriteIsolated, so this review relied on live source, #13683, and #13687 rather than indexed docs for that surface.
[TOOLING_GAP]: Memory Core semantic prior-art queries failed on the embedding write canary. Local temp-worktree tests also needed initServerConfigs.mjs --migrate-config; after that, one parallel full-run hit an unrelated Pipeline.mjs import race, while the changed spec passed serially and hosted CI passed.
[RETROSPECTIVE]: This is the right convergence shape for the store-write guard family: one shared classifier, adopted at each persistent write funnel, with store-specific tests only at the call boundary.

🎯 Close-Target Audit

Close-targets identified: #13683
#13683 confirmed not epic-labeled.

Findings: Pass.

📑 Contract Completeness Audit

Findings: N/A — no public API, MCP tool, config contract, or external wire surface changes. The internal shared util behavior is covered by #13683 ACs and direct tests.

🪜 Evidence Audit

Findings: N/A — close-target ACs are unit-testable and are covered by unit/CI evidence; no L3/L4 runtime handoff is required.

N/A Audits — 📡 🔗

N/A across listed dimensions: no OpenAPI tool descriptions and no cross-skill/workflow convention are modified.

🧪 Test-Execution & Location Audit

Branch checked out locally at exact head f974bf8a469535d75984faed9f639907447a8d6c.
Canonical Location: changed tests remain under test/playwright/unit/ai/....
Related tests executed locally:
- npm run test-unit -- test/playwright/unit/ai/services/shared/storeWriteGuard.spec.mjs test/playwright/unit/ai/graph/SQLiteWriteGuard.spec.mjs -> 12 passed.
- npm run test-unit -- test/playwright/unit/ai/services/ingestion/ConceptDiscoveryService.spec.mjs --workers=1 -> 11 passed.
Static checks:
- git diff --check origin/dev...HEAD -> pass.
- node ./buildScripts/util/check-block-alignment.mjs ... on all four changed files -> pass.
Hosted current-head CI: unit, integration-unified, lint, PR body lint, CodeQL, JSDoc Type Lint, retired-primitives check all green.

Findings: Pass.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 - Reuses the shared guard rather than introducing a second classifier, and places it at the concept write funnel before any live-store mutation can happen.
[CONTENT_COMPLETENESS]: 95 - @throws and classifier JSDoc are clear; 5 deducted only because the KB index has not caught up to this new shared-guard surface yet.
[EXECUTION_QUALITY]: 95 - Local focused tests and hosted CI are green; 5 deducted for the local parallel test harness artifact noted above, which did not reproduce serially and is not caused by the PR diff.
[PRODUCTIVITY]: 100 - Fully satisfies #13683: production-like test writes throw, disposable temp paths pass, and both branches are covered.
[IMPACT]: 70 - Small code delta, but it closes a real live-store pollution class for the concept ontology.
[COMPLEXITY]: 25 - Four-file adoption with one shared-util edge case and direct tests; low implementation complexity.
[EFFORT_PROFILE]: Quick Win - High safety payoff from a narrow guard adoption plus regression coverage.

Approved.