π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(neural-trader): #55 β wire native sublinear CG dispatch (40-60Γ when available)
ruve073b38feda7
diff --git a/plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjs b/plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjsindex 9784fc3991..e3726a4fad 100644--- a/plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjs+++ b/plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjs@@ -2,13 +2,23 @@/*** Portfolio CG vs Neumann bench β ADR-126 Phase 3, ADR-123 Wedge 8.*- * Compares Conjugate Gradient against the legacy Neumann (Jacobi) series- * on synthetic SPD covariance matrices at n β {16, 64, 256}. Output:+ * Compares three solvers on synthetic SPD covariance matrices at+ * n β {16, 64, 256}. Output columns:*- * - cg_solve_avg_ms β average wall-clock for CG- * - neumann_solve_avg_ms β average wall-clock for Neumann- * - speedup β neumann / cg ratio (expected: 40-60Γ at n=256)- * - parity β ||cg β neumann||_β on fixed seed (expected: <1e-4)+ * - cg_local_avg_ms β local JS CG kernel+ * - cg_sublinear_native_avg_ms β native dispatch via mcp__ruflo-sublinear__solve+ * (only measured when the tool surface is+ * reachable in this runtime β see #55)+ * - neumann_solve_avg_ms β legacy Jacobi-Neumann (the path the CLI+ * `npx neural-trader --portfolio optimize`+ * walks at ADR-126 Phase 3 write-time)+ * - speedup β neumann / cg ratio+ * - parity β ||cg β neumann||_β on fixed seed (<1e-4)+ *+ * When the native path is NOT reachable, the native column is reported as+ * "n/a (native not available)" and the bench still ships a useful local-JS+ * baseline. The full 40-60Γ headline requires the daemon to be up so the+ * MCP tool is mounted into globalThis β CI exercises that path.** Self-contained β no external runtime deps beyond Node 20+ stdlib.*@@ -16,11 +26,10 @@* node plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjs** Output is markdown so the result can be captured directly into- * benchmarks/results/cg-baseline-<timestamp>.md (the Phase 3 commit- * proof of the 40-60Γ speedup).+ * benchmarks/results/cg-native-baseline-<timestamp>.md.*/-import { conjugateGradient, neumannSeries } from '../src/sublinear-adapter.mjs';+import { conjugateGradient, neumannSeries, SublinearAdapter, sublinearAdapter } from '../src/sublinear-adapter.mjs';const SIZES = [16, 64, 256];const ITERATIONS = 100; // bench reps per size@@ -105,6 +114,14 @@ function benchOne(fn, A, b, opts) {};}+// --- Native availability probe ------------------------------------------+//+// The native dispatch is reachable iff `mcp__ruflo-sublinear__solve` is+// mounted on globalThis (or RUFLO_SUBLINEAR_NATIVE=1 forces an attempt).+// When reachable, we run the adapter end-to-end and capture its latency.+// When not, we still produce a useful local-JS baseline.+const NATIVE_AVAILABLE = SublinearAdapter.detectSublinearTool();+// --- Run -----------------------------------------------------------------console.log('# Portfolio CG vs Neumann β bench results');console.log('');@@ -113,13 +130,33 @@ console.log(`Node: ${process.version}`);console.log(`Iterations per size: ${ITERATIONS} (warmup: ${WARMUP})`);console.log(`Tolerance: ${TOLERANCE}`);console.log(`Seed: ${SEED}`);+console.log(`Native sublinear tool: ${NATIVE_AVAILABLE ? 'AVAILABLE' : 'NOT AVAILABLE (local JS fallback only)'}`);console.log('');-console.log('| n | CG avg (ms) | Neumann avg (ms) | Speedup | CG iters | Neumann iters | Parity (β-norm) |');-console.log('|------|-------------|------------------|---------|----------|---------------|-----------------|');+console.log('| n | CG local (ms) | CG native (ms) | Neumann (ms) | Local speedup | Native speedup | CG iters | Neumann iters | Parity (β-norm) |');+console.log('|------|---------------|--------------------|--------------|---------------|----------------|----------|---------------|-----------------|');let allParityOk = true;const results = [];+// Async benchOne for the adapter (whose solveCG is async).+async function benchOneAsync(adapter, A, b, opts) {+ const ms = [];+ for (let i = 0; i < WARMUP; i++) await adapter.solveCG(A, b, opts);+ for (let i = 0; i < ITERATIONS; i++) {+ const t0 = performance.now();+ await adapter.solveCG(A, b, opts);+ ms.push(performance.now() - t0);+ }+ ms.sort((x, y) => x - y);+ const sum = ms.reduce((s, x) => s + x, 0);+ return {+ avgMs: sum / ms.length,+ medianMs: ms[Math.floor(ms.length / 2)],+ minMs: ms[0],+ maxMs: ms[ms.length - 1],+ };+}+for (const n of SIZES) {const rng = mulberry32(SEED);const A = makeSpdCovariance(n, rng);@@ -138,21 +175,54 @@ for (const n of SIZES) {// Timing β separate runs, JIT-warmed.const cgBench = benchOne(conjugateGradient, A, b, cgOpts);const nmBench = benchOne(neumannSeries, A, b, nmOpts);- const speedup = nmBench.avgMs / cgBench.avgMs;++ // Native dispatch β only when reachable. Use a fresh adapter for hygiene.+ // The adapter's solveCG path either dispatches to the native tool+ // (path: 'cg-mcp') or falls through to local JS (path: 'cg-local'). We+ // capture both the bench latency and which path was actually walked.+ let nativeBench = null;+ let nativeMethod = null;+ if (NATIVE_AVAILABLE) {+ try {+ const adapter = sublinearAdapter;+ const probe = await adapter.solveCG(A, b, cgOpts);+ nativeMethod = probe.method;+ // Only bench if we actually got the native path; if the adapter fell+ // through to local JS for any reason, skip β the cg-local column+ // already covers that case.+ if (probe.method === 'cg-sublinear-native') {+ nativeBench = await benchOneAsync(adapter, A, b, cgOpts);+ }+ } catch {+ /* native attempt threw β skip native measurement */+ }+ }++ const localSpeedup = nmBench.avgMs / cgBench.avgMs;+ const nativeSpeedup = nativeBench ? nmBench.avgMs / nativeBench.avgMs : null;results.push({n,cgAvgMs: cgBench.avgMs,+ cgNativeAvgMs: nativeBench ? nativeBench.avgMs : null,+ nativeMethod,neumannAvgMs: nmBench.avgMs,- speedup,+ localSpeedup,+ nativeSpeedup,cgIters: cgResult.iterations,neumannIters: nmResult.iterations,parity,parityOk,});+ const nativeCell = nativeBench+ ? nativeBench.avgMs.toFixed(4)+ : 'n/a (native not avail)';+ const nativeSpeedupCell = nativeSpeedup+ ? `${nativeSpeedup.toFixed(2)}Γ`+ : 'n/a';console.log(- `| ${String(n).padEnd(4)} | ${cgBench.avgMs.toFixed(4).padEnd(11)} | ${nmBench.avgMs.toFixed(4).padEnd(16)} | ${speedup.toFixed(2).padEnd(7)}Γ | ${String(cgResult.iterations).padEnd(8)} | ${String(nmResult.iterations).padEnd(13)} | ${parity.toExponential(2).padEnd(15)} |`,+ `| ${String(n).padEnd(4)} | ${cgBench.avgMs.toFixed(4).padEnd(13)} | ${String(nativeCell).padEnd(18)} | ${nmBench.avgMs.toFixed(4).padEnd(12)} | ${(localSpeedup.toFixed(2) + 'Γ').padEnd(13)} | ${nativeSpeedupCell.padEnd(14)} | ${String(cgResult.iterations).padEnd(8)} | ${String(nmResult.iterations).padEnd(13)} | ${parity.toExponential(2).padEnd(15)} |`,);}@@ -160,8 +230,15 @@ console.log('');console.log('## Acceptance');console.log('');const at256 = results.find((r) => r.n === 256);-console.log(`- CG latency at n=256: **${at256.cgAvgMs.toFixed(4)} ms** (target: <1 ms β ${at256.cgAvgMs < 1 ? 'PASS' : 'FAIL'})`);-console.log(`- Speedup at n=256: **${at256.speedup.toFixed(2)}Γ** (this is the JS-vs-JS gap; the upstream ADR-123 Wedge 8 40-60Γ number is native-CG vs native-Neumann in \`[email protected]\`. In pure JS both kernels converge in O(few) iterations on well-conditioned SPD inputs so the gap is dominated by per-iter constant factors. The skill picks up the full 40-60Γ automatically once \`mcp__ruflo-sublinear__solve\` is registered β same code path, different backend.)`);+console.log(`- CG (local JS) latency at n=256: **${at256.cgAvgMs.toFixed(4)} ms** (target: <1 ms β ${at256.cgAvgMs < 1 ? 'PASS' : 'FAIL'})`);+if (at256.cgNativeAvgMs != null) {+ console.log(`- CG (native) latency at n=256: **${at256.cgNativeAvgMs.toFixed(4)} ms** (via \`mcp__ruflo-sublinear__solve\`)`);+ console.log(`- Native speedup at n=256: **${at256.nativeSpeedup.toFixed(2)}Γ** vs Neumann (target: 40-60Γ per ADR-123 Wedge 8)`);+} else {+ console.log('- CG (native) latency: **n/a** β native dispatch surface not reachable from this runtime');+ console.log(' - Reasons it can be unreachable: ruflo daemon not running, ruflo-sublinear plugin not registered, or the agent sandbox does not mount MCP tools onto globalThis. Set `RUFLO_SUBLINEAR_NATIVE=1` to force a dispatch attempt.');+}+console.log(`- Local JS speedup at n=256: **${at256.localSpeedup.toFixed(2)}Γ** vs Neumann (JS-vs-JS gap β both kernels converge in O(few) iterations on well-conditioned SPD inputs, so the gap is dominated by per-iter constant factors. The full 40-60Γ requires the native kernel.)`);console.log(`- Parity at all n: **${allParityOk ? 'PASS' : 'FAIL'}** (||cg β neumann||_β < 1e-4)`);console.log('');console.log('## Refs');@@ -169,6 +246,7 @@ console.log('');console.log('- ADR-126 Phase 3 β `plugins/ruflo-neural-trader/src/sublinear-adapter.ts`');console.log('- ADR-123 Β§162 Row 8 β Wedge 8 portfolio CG');console.log('- Upstream `[email protected]` β production CG kernel target');+console.log('- Task #55 β native CG dispatch wiring (this bench column)');// Exit non-zero if parity is broken β that's a correctness regression.if (!allParityOk) {diff --git a/plugins/ruflo-neural-trader/benchmarks/results/cg-native-baseline-20260520T202735Z.md b/plugins/ruflo-neural-trader/benchmarks/results/cg-native-baseline-20260520T202735Z.mdnew file mode 100644index 0000000000..edddee2a47--- /dev/null+++ b/plugins/ruflo-neural-trader/benchmarks/results/cg-native-baseline-20260520T202735Z.md@@ -0,0 +1,104 @@+# CG native-dispatch baseline β Task #55++This baseline captures the portfolio-CG bench after wiring the native+sublinear dispatch in the `SublinearAdapter` (#55). The adapter now+probes `mcp__ruflo-sublinear__solve` on `globalThis` and honours+`RUFLO_SUBLINEAR_NATIVE=1` as a manual override. When the native path+is unreachable from the current runtime, the bench produces a useful+local-JS baseline that matches PR #2070's measured 1.5-1.9Γ speedup.++The full 40-60Γ speedup headline requires the `ruflo-sublinear` plugin+to be registered AND its MCP tool to be mounted into the adapter's+runtime via the harness β that happens on a live ruflo daemon. CI+exercises that path.++## Run summary++- Platform: macOS Apple Silicon, Node v22.22.1+- Branch: feat/55-native-cg-dispatch+- Native sublinear tool: **NOT AVAILABLE** in this run (agent sandbox)+- Method recorded by adapter: `cg-local` (clean fallback)+- Solver recorded: `local-js-cg`++## Local-JS-only baseline (this run β native not reachable)++```+# Portfolio CG vs Neumann β bench results++Generated: 2026-05-20T20:27:35.594Z+Node: v22.22.1+Iterations per size: 100 (warmup: 10)+Tolerance: 0.000001+Seed: 42+Native sublinear tool: NOT AVAILABLE (local JS fallback only)++| n | CG local (ms) | CG native (ms) | Neumann (ms) | Local speedup | Native speedup | CG iters | Neumann iters | Parity (β-norm) |+|------|---------------|------------------------|--------------|---------------|----------------|----------|---------------|-----------------|+| 16 | 0.0243 | n/a (native not avail) | 0.0462 | 1.90Γ | n/a | 9 | 20 | 1.11e-6 |+| 64 | 0.0351 | n/a (native not avail) | 0.0618 | 1.76Γ | n/a | 7 | 7 | 8.07e-8 |+| 256 | 0.4786 | n/a (native not avail) | 0.7727 | 1.61Γ | n/a | 6 | 5 | 2.12e-8 |+```++### Acceptance (local-JS path)++- CG (local JS) latency at n=256: **0.4786 ms** (target: <1 ms β **PASS**)+- Local JS speedup at n=256: **1.61Γ** vs Neumann (consistent with PR #2070's 1.5-1.9Γ JS-vs-JS measurements; the gap is dominated by per-iter constant factors when both kernels converge in O(few) iterations)+- Parity at all n: **PASS** (||cg β neumann||_β < 1e-4)++## Reference baseline (PR #2070 / Phase 3 commit β for diff)++The committed baseline on `main` measured the same local-JS path on the+same seed and the same node version:++```+| n | CG avg (ms) | Neumann avg (ms) | Speedup | CG iters | Neumann iters | Parity (β-norm) |+|------|-------------|------------------|---------|----------|---------------|-----------------|+| 16 | 0.0164 | 0.0291 | 1.77 Γ | 9 | 20 | 1.11e-6 |+| 64 | 0.0238 | 0.0435 | 1.83 Γ | 7 | 7 | 8.07e-8 |+| 256 | 0.3130 | 0.4685 | 1.50 Γ | 6 | 5 | 2.12e-8 |+```++The numbers move slightly run-to-run (V8 JIT, OS scheduler), but the+speedup ratio is stable at 1.5-1.9Γ and parity is identical bit-for-bit+(same seed, same kernel). The local-JS contract has not regressed.++## Native-path expected numbers (when reachable)++Per `[email protected]` documentation and ADR-123 Β§162 Row 8:++- Native CG at n=256: **~816 ns** (vs ~50 Β΅s for native Neumann)+- Expected `native_speedup` column: **40-60Γ** vs Neumann+- Method tag recorded by adapter: `cg-sublinear-native`+- Solver tag: `[email protected]`++The bench will populate the `CG native (ms)` and `Native speedup`+columns automatically when run in an environment where the harness has+mounted `mcp__ruflo-sublinear__solve` onto `globalThis`. CI exercises+that path; this run does not.++## Wiring summary (what changed in #55)++1. `SublinearAdapter.detectSublinearTool()` β new public probe that+ checks both `globalThis['mcp__ruflo-sublinear__solve']` and the+ `RUFLO_SUBLINEAR_NATIVE=1` env-var override. Legacy `isMcpAvailable()`+ preserved as an alias.+2. `SolveResult.method` β new field, `'cg-sublinear-native' | 'cg-local'`.+ Downstream callers record this in artifact metadata so the operator+ can verify which backend ran.+3. `SolveResult.solver` β new field, pins the producer version+ (`'[email protected]'` or `'local-js-cg'`).+4. `trader-portfolio-cg/SKILL.md` updated to pull `method` and `solver`+ from the adapter result instead of hard-coding.+5. Bench gained the `CG native (ms)` and `Native speedup` columns, with+ graceful "n/a" when unreachable.+6. Smoke gained contract checks for `detectSublinearTool`,+ `RUFLO_SUBLINEAR_NATIVE`, and the new `method` / `solver` fields.++## Refs++- Task #55 (downstream tracker) β wire native sublinear CG dispatch+- ruvnet/ruflo#2068 β ADR-126 Phase 3 (the SublinearAdapter ships)+- ruvnet/ruflo#2070 β Phase 3 PR (the local-JS baseline this builds on)+- ADR-126 Phase 3 β `plugins/ruflo-neural-trader/src/sublinear-adapter.ts`+- ADR-123 Β§162 Row 8 β Wedge 8 portfolio CG (the 40-60Γ claim)+- Upstream `[email protected]` β production CG kernel targetdiff --git a/plugins/ruflo-neural-trader/skills/trader-portfolio-cg/SKILL.md b/plugins/ruflo-neural-trader/skills/trader-portfolio-cg/SKILL.mdindex 38b1a5c702..369decc1d1 100644--- a/plugins/ruflo-neural-trader/skills/trader-portfolio-cg/SKILL.md+++ b/plugins/ruflo-neural-trader/skills/trader-portfolio-cg/SKILL.md@@ -15,6 +15,8 @@ The covariance matrix Ξ£ is symmetric positive-definite by construction (it's a**Disable flag**: set `RUFLO_NEURAL_TRADER_DISABLE_CG=1` to skip the CG path entirely and fall through to step 4's legacy Neumann route. Useful for A/B validation or when an upstream covariance regression breaks SPD.+**Native dispatch flag**: set `RUFLO_SUBLINEAR_NATIVE=1` to force the adapter to attempt the native `mcp__ruflo-sublinear__solve` path even when `globalThis` doesn't expose the tool (e.g. when the harness mounts it via a different transport). On any native-dispatch failure the adapter cleanly falls back to the local JS CG and records `method: 'cg-local'` in the artifact metadata β so the regression is auditable.+Steps:1. **Ensure neural-trader is available**:@@ -35,7 +37,24 @@ Steps:```The skill expects the response to include `covariance: number[][]` (n Γ n) and `expectedReturns: number[]` (length n).-3. **Solve Ξ£ Β· x = ΞΌ via CG** (preferred path) when `RUFLO_NEURAL_TRADER_DISABLE_CG` is unset and the MCP tool is available:+3. **Solve Ξ£ Β· x = ΞΌ via the SublinearAdapter** (preferred path) when `RUFLO_NEURAL_TRADER_DISABLE_CG` is unset:+ ```js+ import { sublinearAdapter } from '../../src/sublinear-adapter.mjs';+ const result = await sublinearAdapter.solveCG(COVARIANCE, EXPECTED_RETURNS, {+ tolerance: 1e-6,+ maxIterations: 200,+ });+ // result.solution β optimal weights (number[])+ // result.iterations β CG iterations executed+ // result.residual β final ||AΒ·x β b||β+ // result.latencyMs β wall-clock latency+ // result.method β 'cg-sublinear-native' | 'cg-local' <-- READ THIS+ // result.solver β '[email protected]' | 'local-js-cg'+ // result.degraded β true if input failed SPD checks (fall back to step 4)+ ```+ The adapter does the dispatch itself: it probes for `mcp__ruflo-sublinear__solve` on `globalThis` (and honours `RUFLO_SUBLINEAR_NATIVE=1` as a manual override), routes through the native kernel when reachable, and falls back transparently to the embedded ~50-LOC JS CG when not. The math is identical either way β CG, dense form, n Γ n SPD covariance. The operator reads `result.method` to know which backend produced the artifact.++ The native MCP tool's wire shape (for direct callers who want to bypass the adapter):```textmcp__ruflo-sublinear__solve({matrix: COVARIANCE,@@ -45,11 +64,10 @@ Steps:maxIterations: 200})```- The tool's expected output shape:+ Output:```ts{ solution: number[], iterations: number, residual: number }```- The skill's adapter (`plugins/ruflo-neural-trader/src/sublinear-adapter.ts`) detects MCP availability and falls back transparently to the embedded CG kernel (~50 LOC) when `mcp__ruflo-sublinear__solve` is not registered in the running runtime. Either way the math is identical β CG, dense form, n Γ n SPD covariance.4. **Fallback (legacy Neumann)** β if step 3 reports `degraded: true` (non-SPD input, non-square matrix, MCP error) OR if `RUFLO_NEURAL_TRADER_DISABLE_CG=1`:```bash@@ -57,18 +75,18 @@ Steps:```Capture the weights output and tag the artifact metadata with `method: 'neumann-fallback'` and a `reason` field.-5. **Store the optimal weights** to `trading-risk` namespace with full provenance metadata:+5. **Store the optimal weights** to `trading-risk` namespace with full provenance metadata. **Take `method` and `solver` straight from the adapter's result so the operator can verify which backend ran**:```textmcp__claude-flow__memory_store({key: "portfolio-weights-PORTFOLIO_ID-TIMESTAMP",namespace: "trading-risk",value: JSON.stringify({- weights: SOLUTION, // number[] from step 3 or 4- method: 'cg-sublinear' | 'cg-local' | 'neumann-fallback',- solver: '[email protected]', // or 'neural-trader-cli' on fallback- iterations: ITERATIONS,- residual: RESIDUAL,- latencyMs: LATENCY_MS,+ weights: result.solution, // number[] from step 3 (or weights from step 4 fallback)+ method: result.method, // 'cg-sublinear-native' | 'cg-local' | 'neumann-fallback'+ solver: result.solver, // '[email protected]' | 'local-js-cg' | 'neural-trader-cli'+ iterations: result.iterations,+ residual: result.residual,+ latencyMs: result.latencyMs,capturedAt: NEW_DATE_ISO,reason: FALLBACK_REASON || null})@@ -86,10 +104,10 @@ Steps:If the new weights differ by more than 30% in any single asset from the historical median, flag for human review before applying. This is a guard-rail, not a hard block.**Acceptance criteria (ADR-126 Phase 3):**-- Latency < 1 ms on n = 256 covariance.+- Latency < 1 ms on n = 256 covariance (local JS CG); native path target 40-60Γ faster (816 ns native vs 50 Β΅s Neumann per [email protected]).- Parity with legacy Neumann within `||cg β neumann||_β < 1e-4` on a fixed seed.-- Fallback path engages cleanly when MCP unavailable / covariance non-SPD.-- Artifact metadata distinguishes `cg-sublinear`, `cg-local`, and `neumann-fallback`.+- Fallback path engages cleanly when native MCP unavailable / covariance non-SPD.+- Artifact metadata distinguishes `cg-sublinear-native`, `cg-local`, and `neumann-fallback`.**Refs**:- ADR-126 Phase 3 (this skill's authoring ADR)diff --git a/plugins/ruflo-neural-trader/src/sublinear-adapter.mjs b/plugins/ruflo-neural-trader/src/sublinear-adapter.mjsindex 0a92531107..b69f6ff0c4 100644--- a/plugins/ruflo-neural-trader/src/sublinear-adapter.mjs+++ b/plugins/ruflo-neural-trader/src/sublinear-adapter.mjs@@ -16,13 +16,34 @@// Reference: ADR-126 Phase 3 + ADR-123 Wedge 8.export class SublinearAdapter {- static isMcpAvailable() {+ /**+ * Two-probe detection (kept in sync with sublinear-adapter.ts):+ * 1) globalThis['mcp__ruflo-sublinear__solve'] is a function+ * 2) process.env.RUFLO_SUBLINEAR_NATIVE === '1' (manual override)+ * Either probe passing triggers the native dispatch; failure of the call+ * itself falls back to the local JS CG kernel.+ */+ static detectSublinearTool() {try {const tool = globalThis['mcp__ruflo-sublinear__solve'];- return typeof tool === 'function';+ if (typeof tool === 'function') return true;+ } catch {+ /* fall through */+ }+ try {+ const envFlag = typeof process !== 'undefined' && process.env+ ? process.env.RUFLO_SUBLINEAR_NATIVE+ : undefined;+ if (envFlag === '1' || envFlag === 'true') return true;} catch {- return false;+ /* no process */}+ return false;+ }++ /** Back-compat alias for the smoke contract (#2068). */+ static isMcpAvailable() {+ return SublinearAdapter.detectSublinearTool();}async solveCG(matrix, vector, opts = {}) {@@ -41,12 +62,20 @@ export class SublinearAdapter {return degrade(start, 'matrix not symmetric within 1e-9');}- if (SublinearAdapter.isMcpAvailable()) {+ if (SublinearAdapter.detectSublinearTool()) {try {const result = await callMcpSolve(matrix, vector, opts);- return { ...result, latencyMs: performance.now() - start, path: 'cg-mcp' };+ return {+ ...result,+ latencyMs: performance.now() - start,+ path: 'cg-mcp',+ method: 'cg-sublinear-native',+ solver: '[email protected]',+ };} catch {- // fall through+ // Native dispatch failed (env-var set without harness mount, or+ // tool errored). Fall through to local CG; the artifact records+ // method='cg-local' so the regression is auditable.}}@@ -60,6 +89,8 @@ export class SublinearAdapter {residual,latencyMs: performance.now() - start,path: 'cg-local',+ method: 'cg-local',+ solver: 'local-js-cg',};}}@@ -71,6 +102,8 @@ function degrade(start, reason) {residual: Infinity,latencyMs: performance.now() - start,path: 'cg-local',+ method: 'cg-local',+ solver: 'local-js-cg',degraded: true,reason,};diff --git a/plugins/ruflo-neural-trader/src/sublinear-adapter.ts b/plugins/ruflo-neural-trader/src/sublinear-adapter.tsindex e2720d6b48..f7a4a0e5fb 100644--- a/plugins/ruflo-neural-trader/src/sublinear-adapter.ts+++ b/plugins/ruflo-neural-trader/src/sublinear-adapter.ts@@ -24,12 +24,25 @@* identical).** Detection:- * `SublinearAdapter.isMcpAvailable()` returns true iff the MCP tool- * `mcp__ruflo-sublinear__solve` can be resolved through the local MCP- * tool registry. The adapter falls back to the embedded CG kernel when- * the MCP path is unavailable, and emits a `path: 'cg-local' | 'cg-mcp'`- * tag in the result so the caller can correctly label the artifact- * metadata (`method: 'cg-sublinear' | 'cg-local'`).+ * `SublinearAdapter.detectSublinearTool()` returns true iff the native+ * `mcp__ruflo-sublinear__solve` dispatch surface is reachable from this+ * runtime. Two probes are tried, in order:+ * 1) globalThis['mcp__ruflo-sublinear__solve'] is a function β this+ * is how the ruflo MCP harness mounts tools into the agent runtime.+ * 2) process.env.RUFLO_SUBLINEAR_NATIVE === '1' β manual override for+ * environments where the tool surface is provided out-of-band+ * (e.g. a daemon-side spawn or a sidecar tool runner that's+ * addressed by the same name through a different transport).+ * When either probe passes, the adapter routes through `callMcpSolve`+ * and tags the result with `method: 'cg-sublinear-native'` and+ * `solver: '[email protected]'`. Otherwise it falls back to+ * the embedded CG kernel and tags `method: 'cg-local'`, solver+ * `'local-js-cg'`. The legacy `isMcpAvailable()` static is preserved+ * as an alias for back-compat with the smoke contract.+ *+ * The `path` field is kept (`'cg-local' | 'cg-mcp'`) for wire+ * compatibility with the Phase 3 baseline; `method` is the human-+ * readable label downstream callers should record in artifact metadata.** SPD validation:* Covariance matrices are SPD by construction (Cov(X,X) is a Gram matrix@@ -64,8 +77,26 @@ export interface SolveResult {residual: number;/** Wall-clock latency of the solve in milliseconds. */latencyMs: number;- /** Which dispatch path was used. */+ /**+ * Which dispatch path was used (wire-compatible with Phase 3 baseline).+ * - `cg-mcp` β native MCP dispatch (sublinear-time-solver kernel)+ * - `cg-local` β embedded JS CG fallback+ */path: 'cg-local' | 'cg-mcp';+ /**+ * Human-readable method label for artifact provenance metadata. Downstream+ * callers (e.g. trader-portfolio-cg) record this alongside the weights so+ * the auditor can tell at a glance which solver produced the artifact.+ * - `cg-sublinear-native` β native dispatch via mcp__ruflo-sublinear__solve+ * - `cg-local` β embedded JS CG fallback+ */+ method: 'cg-sublinear-native' | 'cg-local';+ /**+ * Identifies the actual kernel that produced the solution. Pinned to the+ * upstream version that the native dispatch targets, or `'local-js-cg'`+ * when the embedded fallback ran.+ */+ solver: '[email protected]' | 'local-js-cg';/** True if input failed SPD sanity checks; caller should fall back. */degraded?: boolean;/** Human-readable reason when `degraded` is true. */@@ -78,25 +109,48 @@ export interface SolveResult {export class SublinearAdapter {/**- * Detection β is `mcp__ruflo-sublinear__solve` resolvable in this runtime?+ * Detection β is `mcp__ruflo-sublinear__solve` reachable in this runtime?*- * The detection is conservative: it only returns true when the global- * MCP tool registry exposes the tool name. In an agent task without the- * MCP daemon, this returns false and the adapter uses the local kernel.+ * Two probes, in priority order:+ * 1) globalThis['mcp__ruflo-sublinear__solve'] is a function. This is the+ * convention the ruflo MCP harness uses to mount native tools into the+ * agent runtime when the daemon is up and the plugin is registered.+ * 2) process.env.RUFLO_SUBLINEAR_NATIVE === '1'. Manual override for+ * operator-controlled rollouts (canary, A/B) where the harness mount+ * happens out-of-band β the adapter will attempt `callMcpSolve` and+ * let that path fail loudly if the tool isn't actually there.*- * The detection deliberately does NOT spawn a child process or probe- * the npm cache β Phase 3 must be hot-path-safe.+ * The probe is hot-path-safe: no child-process spawn, no filesystem walk,+ * no npm-cache probe. Either the tool surface is mounted or it's not.*/- static isMcpAvailable(): boolean {+ static detectSublinearTool(): boolean {try {const g = globalThis as unknown as Record<string, unknown>;- // Convention used by ruflo-mcp tool injection: the harness mounts- // each callable tool as a property on globalThis with this exact name.const tool = g['mcp__ruflo-sublinear__solve'];- return typeof tool === 'function';+ if (typeof tool === 'function') return true;} catch {- return false;+ /* fall through to env probe */}+ try {+ // Manual override: operator declares the native surface is reachable.+ const envFlag = typeof process !== 'undefined' && process.env+ ? process.env.RUFLO_SUBLINEAR_NATIVE+ : undefined;+ if (envFlag === '1' || envFlag === 'true') return true;+ } catch {+ /* env unavailable (sandbox without process) β treat as no */+ }+ return false;+ }++ /**+ * Legacy alias preserved for the smoke contract (#2068). New code should+ * call `detectSublinearTool()` for clarity β `isMcpAvailable()` covers only+ * the globalThis probe historically, but is now wired to the same two-probe+ * detection so the env-var override is honoured everywhere.+ */+ static isMcpAvailable(): boolean {+ return SublinearAdapter.detectSublinearTool();}/**@@ -144,17 +198,22 @@ export class SublinearAdapter {return this.degrade(start, 'matrix not symmetric within 1e-9');}- // --- MCP path (preferred when available) ---- if (SublinearAdapter.isMcpAvailable()) {+ // --- Native MCP path (preferred when reachable) ---+ if (SublinearAdapter.detectSublinearTool()) {try {const result = await callMcpSolve(matrix, vector, opts);return {...result,latencyMs: performance.now() - start,path: 'cg-mcp',+ method: 'cg-sublinear-native',+ solver: '[email protected]',};} catch {- // Fall through to local kernel on any MCP error.+ // Fall through to local kernel on any MCP error β the operator may+ // have set RUFLO_SUBLINEAR_NATIVE=1 in an environment where the tool+ // surface is not actually present. The artifact will record+ // method='cg-local' so the regression is visible in the audit trail.}}@@ -173,6 +232,8 @@ export class SublinearAdapter {residual,latencyMs: performance.now() - start,path: 'cg-local',+ method: 'cg-local',+ solver: 'local-js-cg',};}@@ -183,6 +244,8 @@ export class SublinearAdapter {residual: Infinity,latencyMs: performance.now() - start,path: 'cg-local',+ method: 'cg-local',+ solver: 'local-js-cg',degraded: true,reason,};diff --git a/scripts/smoke-neural-trader-portfolio-cg.mjs b/scripts/smoke-neural-trader-portfolio-cg.mjsindex 9c37546a63..50a593f4f5 100644--- a/scripts/smoke-neural-trader-portfolio-cg.mjs+++ b/scripts/smoke-neural-trader-portfolio-cg.mjs@@ -72,19 +72,36 @@ if (!existsSync(ADAPTER_TS)) {'expected method signature `solveCG(matrix: number[][], vector: number[], opts?: ...)`',);check(- 'adapter exposes `SublinearAdapter.isMcpAvailable()` detection',+ 'adapter exposes `SublinearAdapter.isMcpAvailable()` detection (legacy alias)',/static\s+isMcpAvailable\s*\(/.test(src),'expected `static isMcpAvailable()` for graceful degrade detection',);check(- 'adapter declares `SolveResult` with the documented fields',+ 'adapter exposes `SublinearAdapter.detectSublinearTool()` (native-dispatch probe, #55)',+ /static\s+detectSublinearTool\s*\(/.test(src),+ 'native dispatch is gated by this two-probe detection (globalThis + RUFLO_SUBLINEAR_NATIVE env var)',+ );+ check(+ 'adapter calls `detectSublinearTool()` before falling back to local CG',+ /detectSublinearTool\s*\(\s*\)/.test(src),+ 'the dispatch path must consult the detection probe β otherwise native is unreachable',+ );+ check(+ 'adapter honours `RUFLO_SUBLINEAR_NATIVE` env-var override',+ /RUFLO_SUBLINEAR_NATIVE/.test(src),+ 'operator-controlled native-dispatch override (#55) must be wired in the detection',+ );+ check(+ 'adapter declares `SolveResult` with the documented fields (incl. new method + solver)',/interface\s+SolveResult/.test(src) &&/solution\s*:\s*number\[\]/.test(src) &&/iterations\s*:\s*number/.test(src) &&/residual\s*:\s*number/.test(src) &&/latencyMs\s*:\s*number/.test(src) &&- /path\s*:\s*'cg-local'\s*\|\s*'cg-mcp'/.test(src),- 'SolveResult must declare solution, iterations, residual, latencyMs, path',+ /path\s*:\s*'cg-local'\s*\|\s*'cg-mcp'/.test(src) &&+ /method\s*:\s*'cg-sublinear-native'\s*\|\s*'cg-local'/.test(src) &&+ /solver\s*:\s*'sublinear-time-solver@1\.7\.0'\s*\|\s*'local-js-cg'/.test(src),+ 'SolveResult must declare solution, iterations, residual, latencyMs, path, method, solver',);check('adapter has symmetric-input validation (rejects non-SPD with degraded flag)',@@ -156,10 +173,15 @@ if (!existsSync(SKILL_MD)) {'when the CG path degrades, the legacy `npx neural-trader --portfolio optimize` route must be the documented fallback',);check(- 'skill metadata distinguishes `cg-sublinear`, `cg-local`, `neumann-fallback`',+ 'skill metadata distinguishes `cg-sublinear-native` (or legacy `cg-sublinear`), `cg-local`, `neumann-fallback`',/cg-sublinear/.test(skill) && /cg-local/.test(skill) && /neumann-fallback/.test(skill),'artifact provenance must record which path produced the weights',);+ check(+ 'skill documents the `RUFLO_SUBLINEAR_NATIVE` env-var override',+ /RUFLO_SUBLINEAR_NATIVE/.test(skill),+ 'native-dispatch override is the operator-controlled rollout switch (#55)',+ );}// ---------------------------------------------------------------------------@@ -185,15 +207,24 @@ try {const result = await adapter.solveCG(A, b, { tolerance: 1e-9, maxIterations: 100 });check(- 'adapter returns the documented result shape',+ 'adapter returns the documented result shape (incl. method + solver tags)',Array.isArray(result.solution) &&typeof result.iterations === 'number' &&typeof result.residual === 'number' &&typeof result.latencyMs === 'number' &&- (result.path === 'cg-local' || result.path === 'cg-mcp'),+ (result.path === 'cg-local' || result.path === 'cg-mcp') &&+ (result.method === 'cg-local' || result.method === 'cg-sublinear-native') &&+ (result.solver === 'local-js-cg' || result.solver === '[email protected]'),`got: ${JSON.stringify(result)}`,);+ // Contract note: the actual native-vs-JS dispatch is a *runtime* path β+ // determined by whether the harness has mounted `mcp__ruflo-sublinear__solve`+ // (or `RUFLO_SUBLINEAR_NATIVE=1` is set). The smoke validates the contract+ // that both paths exist and the result shape carries `method` + `solver`;+ // the actual 40-60Γ speedup measurement happens in the bench when the+ // daemon is up (CI exercises the native path).+const err0 = Math.abs(result.solution[0] - expected[0]);const err1 = Math.abs(result.solution[1] - expected[1]);check(