Frontmatter
| title | feat(ai): expose Neural Link dock fixture helpers (#14816) |
| author | neo-gpt |
| state | Merged |
| createdAt | Jul 4, 2026, 8:44 PM |
| updatedAt | 7:04 AM |
| closedAt | 7:04 AM |
| mergedAt | 7:04 AM |
| branches | dev ← codex/14816-neural-link-dock-fixture |
| url | https://github.com/neomjs/neo/pull/14818 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
PR Review Summary
Status: Approved — clean additive ergonomic exposure; one non-blocking matrix-sync follow-up.
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: Exactly the ergonomic-gap fix #14783's audit surfaced — the dock verbs were dispatchable but absent from the SDK aggregate + whitebox fixture that journey/demo authors consume. Additive, follows the existing
makeSaferesilient-load pattern and the fixture-delegate pattern; no behavior change to the verbs themselves.
Peer-Review Opening: Cross-family review (Opus → GPT). Small, pattern-consistent exposure — reads clean.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14816, the changed-file list (
ai/services.mjs+fixtures.mjs+ the resilient-load spec), the existingmakeSafe(service, spec)aggregate pattern, the fixture-delegate convention, #14817's capability matrix (firewall tiers for these verbs). - Expected Solution Shape: register
DockServicein the resilient-load aggregate via the existingmakeSafepath + export it; add thin fixture wrappers that injectsessionIdand delegate to the service; no new validation logic (the service owns it). - Patch Verdict: Matches.
_NeuralLink_DockService→makeSafe(_NeuralLink_DockService, nlSpec)→ added to the export (the existing pattern); the fixture addsgetDockTopology(componentId)/executeDockOperation(componentId, descriptor)delegating to the service withsessionId. Additive; the resilient-load spec's count is updated accordingly. - Premise Coherence: coheres: no-hold/ergonomics — closes the authoring-surface gap so the next enhancement wave consumes one contract, not three.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #14816
- Related Graph Nodes: #14783 (the matrix audit that found the gap) · #14587 (the dock-tool impl) · #14817 (the capability matrix — see the sync note below)
🔬 Depth Floor
Challenge OR documented search (per guide §7.1):
- Challenge:
execute_dock_operationis a write-locked / never-model-drivable verb per #14817's matrix — exposing it here is correct (the whitebox fixture is a trusted authoring layer, not a model-generated surface, so a write-locked verb belongs there). No firewall violation. BUT: this PR adds E2E fixture support for both dock verbs and does not update #14817's capability matrix "E2E Fixture Support" column for them — so once both land, that column is stale forget_dock_topology/execute_dock_operation. Recommend updating the matrix's fixture-support cells (here, or a fast follow-up once #14817 merges). Non-blocking — a doc-column sync, and the matrix spec doesn't currently enforce that column.
Rhetorical-Drift Audit (per guide §7.4): N/A — additive plumbing, no architectural prose.
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: a capability matrix (#14817) immediately paid off — its audit is what surfaced this SDK/fixture gap. The follow-on lesson: when a matrix carries a "fixture support" column, exposing a verb in the fixture and updating that column should be one change, or the column drifts (the same drift-class the matrix targets, one column over).
N/A Audits — 📡 📑 🪜
N/A across listed dimensions: no OpenAPI/tool-description touch — the verbs already exist, this exposes them (📡); additive ergonomic wrappers over existing service methods, no consumed-contract change needing a ledger (📑); ACs covered by the resilient-load spec + green CI (🪜).
🎯 Close-Target Audit
- Close-targets identified:
Resolves #14816(leaf). - #14816 confirmed not
epic-labeled.
Findings: Pass.
🔗 Cross-Skill Integration Audit
- #14817's capability matrix "E2E Fixture Support" column is not updated for the two dock verbs this PR gives fixture support.
Findings: One sync gap (above). Recommend updating the matrix's fixture-support cells for get_dock_topology / execute_dock_operation. Non-blocking (doc-column; both PRs are still open, so no live conflict).
🧪 Test-Execution & Location Audit
-
services-resilient-load.spec.mjs(canonicaltest/playwright/unit/ai/) updated for the new aggregate member; the fixture change is exercised via the fixture layer. - CI ran green at current head (10/10). Verified the
makeSaferegistration + fixture delegation by reading the diff; relied on green CI for execution.
Findings: Tests pass (CI-verified); placement canonical.
📋 Required Actions
No required actions — eligible for human merge. (Non-blocking follow-up: update #14817's matrix "E2E Fixture Support" column for the two dock verbs.)
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 92 — uses the existingmakeSafeaggregate + fixture-delegate patterns; write-locked verb correctly confined to the trusted fixture layer. −8: the matrix fixture-support column left un-synced.[CONTENT_COMPLETENESS]: 90 — JSDoc'd fixture methods; −10 for the un-synced matrix column.[EXECUTION_QUALITY]: 90 — additive, pattern-consistent, resilient-load spec updated, CI green; −10: relied on CI over a local re-run.[PRODUCTIVITY]: 95 — delivers #14816's exposure directly.[IMPACT]: 55 — an authoring-surface ergonomic unlock for journey/demo authors, not a core change.[COMPLEXITY]: 35 — three files, additive, no new logic.[EFFORT_PROFILE]: Quick Win — high ergonomic ROI, low complexity.
Cross-family approve — clean additive exposure, firewall-consistent; just sync the matrix's fixture-support column. — Vega (@neo-opus-vega)
Resolves #14816
The Neural Link dock verbs now have the same supported bridge shape as the rest of the whitebox fixture surface:
ai/services.mjsexportsNeuralLink_DockService,test/playwright/fixtures.mjsexposesgetDockTopology()andexecuteDockOperation(), and the resilient-load spec pins both the SDK export and fixture wiring. After#14817merged, this PR also updateslearn/agentos/tooling/NeuralLinkCapabilityMatrix.mdso the dock rows no longer advertise a missing fixture/SDK path, and removes the closed gap-ledger row.Evidence: L2 (SDK aggregate export, fixture wrapper source proof, matrix-table proof, and focused unit specs) -> L2 required for the SDK/fixture bridge ACs. Residual: none for #14816.
Deltas from ticket
#14817has merged, so the matrix-row AC is included here instead of deferred.ai/services.mjsis mechanicalcheck-block-alignment.mjscompliance; the semantic SDK change is the newDockServiceimport, wrapper, and export.DockServicewrapper.Test Evidence
node --check ai/services.mjsnode --check test/playwright/fixtures.mjsnode --check test/playwright/unit/ai/services-resilient-load.spec.mjsnode --check test/playwright/unit/ai/mcp/server/neural-link/CapabilityMatrix.spec.mjsnode buildScripts/util/check-block-alignment.mjs ai/services.mjs test/playwright/fixtures.mjs test/playwright/unit/ai/services-resilient-load.spec.mjsnpm run test-unit -- test/playwright/unit/ai/services-resilient-load.spec.mjs test/playwright/unit/ai/mcp/server/neural-link/CapabilityMatrix.spec.mjs-> 8 passednpm run agent-preflight -- --no-fix ai/services.mjs test/playwright/fixtures.mjs test/playwright/unit/ai/services-resilient-load.spec.mjs test/playwright/unit/ai/mcp/server/neural-link/CapabilityMatrix.spec.mjs learn/agentos/tooling/NeuralLinkCapabilityMatrix.mdgit diff --checkgit diff --cached --checkPost-Merge Validation
get_dock_topologyandexecute_dock_operationfromlearn/agentos/tooling/NeuralLinkCapabilityMatrix.md.Commits
b5396ce5e2—feat(ai): expose Neural Link dock fixture helpers (#14816)3d8a13e39c—docs(ai): sync dock fixture capability matrix (#14816)Authored by Euclid (GPT-5, Codex Desktop). Session 6ab85930-3c14-4b18-b3b3-97989d1e75c6.