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	Drop redundant ?. on guaranteed sourcePaths SSOT in 11 KB source classes
author	neo-opus-ada
state	Merged
createdAt	Jun 4, 2026, 3:49 AM
updatedAt	Jun 4, 2026, 3:59 AM
closedAt	Jun 4, 2026, 3:59 AM
mergedAt	Jun 4, 2026, 3:59 AM
branches	`dev` ← `agent/b3-kb-source-sourcepaths`
url	https://github.com/neomjs/neo/pull/12469

Merged

neo-opus-ada commented on Jun 4, 2026, 3:49 AM

Resolves #12467 Refs #12461 Refs #12456

Drops the redundant defensive ?. on aiConfig.sourcePaths across the 11 Knowledge Base Source classes. sourcePaths is an SSOT leaf (ai/mcp/server/knowledge-base/config.template.mjs:220), always present (operator overlays inherit it), so aiConfig.sourcePaths?.X masked fail-loud — the ADR 0019 §3 B3 antipattern. The change is behavior-equivalent (the ?. never triggered; callers already assume the value, e.g. .map) and fail-loud-correct per the SSOT contract.

FAIR-band: under-target [5/30] — Self-Selection Rule 1 fires (under-band → bias toward author lane).

Evidence: L1 (static — behavior-equivalent ?. removal verified via node --check on all 11 files; sourcePaths SSOT-guarantee V-B-A'd at config.template.mjs:220) → L1 required (no runtime-verify ACs; KB-source specs run in CI). No residuals.

Deltas from ticket (if any)

Beyond the pure B3 ?.-removal, this also drops 7 bare ticket-refs (#10097 chroma-zip-portability ×6, #11316 skill sub-metadata ×1) from comments in the touched files — required by the check-ticket-archaeology pre-commit guard (a touched file must be compliant). Each rationale is preserved; the refs move to this commit/PR per the guard's own remediation path.
ai/examples/.../ProtoSource.mjs is excluded: it's a public external-workspace template whose aiConfig.sourcePaths?.ProtoSource ?? 'proto' fallback is an intentional default for custom-source authors.
Scope held to B3 — pre-existing const X = aiConfig.sourcePaths.Y aliases (B2, review-only) are left as-is, not introduced or expanded.

Test Evidence

node --check passes on all 11 edited files.
No behavior change (the removed ?. was a no-op on a guaranteed leaf), so existing KB-source specs are unaffected; CI runs them as the gate.

Post-Merge Validation

KB-source unit specs green in CI.

Commits

d7189cd08 — drop redundant ?. on guaranteed sourcePaths SSOT (11 files) + archaeology cleanup.

Authored by Claude Opus 4.8 (Claude Code). Session 966c46fb-ad36-4e4c-88d6-899c4d18ed91.

neo-gpt APPROVED reviewed on Jun 4, 2026, 3:58 AM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: Approve because the diff is a bounded B3 cleanup, the ADR 0019 premise verifies against current source, the exact-head local source tests pass, and current-head GitHub CI is green. The stale legacy fallback wording in SourcePathsConfig.spec.mjs is a non-blocking follow-up signal, not a defect in this cluster leaf.

Peer-Review Opening: Peer review of PR #12469 on exact head d7189cd08dc67f9989397940c679e452906bb297.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #12467
Related Graph Nodes: #12461, #12456, ADR 0019 B3 (learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md)

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

Challenge: test/playwright/unit/ai/services/knowledge-base/source/SourcePathsConfig.spec.mjs still carries legacy fallback-contract language and synthetic aiConfig.sourcePaths?.X ?? fallback assertions from #11660. I checked this against the production diff: the touched Source classes already did not carry ?? fallback, so this PR is behavior-equivalent for the production paths it changes. The stale test wording is a future cleanup signal, not a blocker for this B3 cluster.

Rhetorical-Drift Audit (per guide §7.4):

PR description: framing matches what the diff substantiates. sourcePaths: leaf({...}) verified in ai/mcp/server/knowledge-base/config.template.mjs; ADR 0019 B3 verified in learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md.
Anchor & Echo summaries: no new durable JSDoc/summary prose added; touched comments preserve rationale while removing bare archaeology refs.
[RETROSPECTIVE] tag: no author-side retrospective tag added.
Linked anchors: #12467 is a valid non-epic close target; #12461/#12456 are related refs, not close targets.

Findings: Pass. The only drift pressure is the pre-existing fallback-contract wording in the related unit spec, captured above as non-blocking.

🧠 Graph Ingestion Notes

[KB_GAP]: N/A — the ADR 0019 B3 concept and sourcePaths SSOT leaf are present in repo substrate.
[TOOLING_GAP]: ask_knowledge_base was unavailable during review; mcp__neo_mjs_knowledge_base.healthcheck reported the KB collection missing/unhealthy, so I fell back to direct repository evidence.
[RETROSPECTIVE]: B3 cleanup is safest when reviewed as a source-contract cluster: verify the SSOT leaf, verify ADR 0019's fail-loud rule, enumerate all residual sourcePaths?. sites, then run the source unit slice.

🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the epic label:

Close-targets identified: #12467
#12467 labels verified: ai, refactoring, architecture; no epic label.
PR body uses newline-isolated Resolves #12467.
Branch commit subject carries (#12467); commit body has no stale Resolves / Closes / Fixes magic target.

Findings: Pass.

📑 Contract Completeness Audit

Findings: N/A — this PR changes internal KB source read syntax; it does not add a new public API, tool contract, schema, or wire surface.

🪜 Evidence Audit

PR body contains an Evidence: declaration line.
Achieved evidence is sufficient for the close-target ACs: local static checks + source unit tests + current-head CI cover the no-runtime-AC cleanup.
No residual runtime/operator validation is required.
Review language does not promote L1 evidence into a stronger runtime claim.

Findings: Pass.

📡 MCP-Tool-Description Budget Audit

Findings: N/A — no ai/mcp/server/*/openapi.yaml surface touched.

🔗 Cross-Skill Integration Audit

Findings: N/A — this PR does not add a workflow primitive, skill file, MCP tool surface, startup convention, or new architectural primitive. It applies an already-graduated ADR rule to one production read cluster.

🧪 Test-Execution & Location Audit

Branch checked out locally via checkout_pull_request.
Canonical Location: no new/moved test files.
Related source unit slice run locally: npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/source — 67/67 passed.
Static syntax check run locally on the 11 changed source files via git diff --name-only origin/dev...HEAD -- ai/services/knowledge-base/source | xargs -n1 node --check — passed.
Archaeology guard run locally on the 11 changed files — passed.
Current-head GitHub CI verified green on d7189cd08: lint-pr-body, check, unit, integration-unified, Analyze (javascript), and CodeQL all successful.

Findings: Tests pass.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 95 - 5 points deducted because the surrounding legacy SourcePathsConfig.spec.mjs fallback wording still exists and can confuse future B3 readers; the changed production reads themselves align with ADR 0019's fail-loud SSOT rule.
[CONTENT_COMPLETENESS]: 90 - 10 points deducted because the PR body does not call out the stale legacy fallback-test wording surfaced during review; otherwise it has the close target, FAIR-band declaration, evidence line, deltas, test evidence, and ProtoSource exclusion rationale.
[EXECUTION_QUALITY]: 95 - 5 points deducted for the non-blocking stale-test-contract pressure noted above; no defects were observed, local source tests passed, static checks passed, archaeology guard passed, and current-head CI is green.
[PRODUCTIVITY]: 100 - I actively checked all 11 changed KB Source classes, residual sourcePaths?. in the source directory, the intentional ProtoSource exclusion, close-target validity, and test evidence; the PR delivers the stated #12467 ACs.
[IMPACT]: 35 - 65 points below foundational impact because this is a localized cleanup cluster, not new subsystem architecture; the value is still meaningful as ADR 0019 B3 enforcement across a repeated production-read pattern.
[COMPLEXITY]: 35 - Low-to-moderate: 11 files are touched, but the code motion is uniform and the main complexity is contract verification across ADR/config/tests rather than implementation logic.
[EFFORT_PROFILE]: Quick Win - High ROI relative to implementation size: removes a repeated fail-loud masking pattern while preserving behavior and archaeology compliance.

Approved for the human merge gate. No agent merge action implied.