@claude-flow/cli 3.11.0 → 3.12.0

package/dist/src/ruvector/router-parallel-recorder.js

@@ -0,0 +1,183 @@
+/**
+ * router-parallel-recorder.ts — Opt-in SelfEvolvingRouter parallel-logging
+ * recorder (ADR-150 Phase 2).
+ *
+ * Writes one JSON-line per PAIR of routing decisions (Thompson bandit pick
+ * + SelfEvolvingRouter pick + measured outcome) to a shared
+ * `.swarm/router-parallel.jsonl`. Designed to be matched by
+ * `plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs` which
+ * computes the 3-criteria AND-gate from ADR-150 review-round-1:
+ *
+ *   (a) qualityScore improvement > 2%
+ *   (b) usdPerDecision increase   < 1%
+ *   (c) p95 routing-decision latency increase < 5%
+ *
+ * ARCHITECTURAL CONSTRAINTS (ADR-150)
+ * -----------------------------------
+ * 1. REMOVABLE — `@metaharness/kernel` (which provides SelfEvolvingRouter)
+ *    is in optionalDependencies. This module's exports are pure-shape; the
+ *    `SerPick` carries pre-computed prediction fields. The caller is
+ *    responsible for dynamic-importing the kernel and computing the SER
+ *    pick — this module ONLY records the pair.
+ * 2. OPTIONAL — every write goes through the `CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1`
+ *    env gate. When unset (default), `recordPair()` is a no-op.
+ * 3. GRACEFUL DEGRADATION — every fs operation is try/caught at the
+ *    appendFileSync boundary. A failed write logs to stderr (gated by
+ *    DEBUG) but never throws — the routing decision continues.
+ * 4. CI GATE — the analyzer + recorder are both exercised by smoke
+ *    fixtures; no production data required for the contract to hold.
+ *
+ * SCHEMA (versioned, additive)
+ * ----------------------------
+ * One JSONL row per paired decision:
+ *   {
+ *     v: 1,
+ *     ts: ISO-8601,
+ *     task_hash: <FNV-1a-32 of task text>,
+ *     task?: <truncated to 500 chars when CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK=1>,
+ *     bandit: { pick, predictedQuality, predictedCostUsd, ... },
+ *     ser:    { pick, predictedQuality, predictedCostUsd, ... },
+ *     outcome?: { actualModel, actualQuality, actualUsd, actualLatencyMs }
+ *   }
+ *
+ * Outcomes can be filled in a separate `recordPairOutcome()` call (matched
+ * by task_hash) so the routing path doesn't have to wait for execution.
+ *
+ * @module router-parallel-recorder
+ */
+import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { taskHash } from './router-trajectory.js';
+let _cfg = null;
+function getConfig() {
+    if (_cfg !== null)
+        return _cfg;
+    _cfg = {
+        enabled: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1',
+        path: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH
+            ? resolvePath(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH)
+            : resolvePath('.swarm', 'router-parallel.jsonl'),
+        includeTaskText: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK === '1',
+        taskCharLimit: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK_LIMIT || '500', 10),
+        maxBytes: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_MAX_BYTES || String(10 * 1024 * 1024), 10),
+    };
+    return _cfg;
+}
+function rotate(cfg) {
+    try {
+        const backup = `${cfg.path}.1`;
+        if (existsSync(backup))
+            unlinkSync(backup);
+        renameSync(cfg.path, backup);
+    }
+    catch (e) {
+        if (process.env.DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('router-parallel: rotate failed:', e.message);
+        }
+    }
+}
+function appendRow(row) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
+    try {
+        const dir = dirname(cfg.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (existsSync(cfg.path)) {
+            try {
+                const st = statSync(cfg.path);
+                if (st.size >= cfg.maxBytes)
+                    rotate(cfg);
+            }
+            catch { /* stat race is fine */ }
+        }
+        appendFileSync(cfg.path, JSON.stringify(row) + '\n');
+    }
+    catch (e) {
+        if (process.env.DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('router-parallel: appendRow failed:', e.message);
+        }
+        // ADR-150 rule #3 — never throw, never block the routing path.
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Record one paired routing decision. Cheap — single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset (the
+ * default). Never throws.
+ *
+ * The caller dynamic-imports `@metaharness/kernel` (or any alternative
+ * predictor) and computes the SER pick BEFORE calling this. The recorder
+ * deliberately knows nothing about how either pick was computed — it just
+ * writes the pair.
+ */
+export function recordPair(args) {
+    const cfg = getConfig();
+    const hash = taskHash(args.task);
+    if (!cfg.enabled)
+        return { recorded: false, taskHash: hash };
+    const row = {
+        v: 1,
+        type: 'pair',
+        ts: new Date().toISOString(),
+        task_hash: hash,
+        bandit: args.bandit,
+        ser: args.ser,
+    };
+    if (cfg.includeTaskText) {
+        row.task = args.task.length > cfg.taskCharLimit
+            ? args.task.slice(0, cfg.taskCharLimit) + '…'
+            : args.task;
+    }
+    appendRow(row);
+    return { recorded: true, taskHash: hash };
+}
+/**
+ * Record the outcome of a previously-paired decision. Matched to its
+ * pair row by task_hash. Writes a separate JSONL row of type 'outcome'
+ * which the analyzer joins client-side (same pattern as the existing
+ * router-trajectory recorder).
+ *
+ * Returns the task_hash that was matched (caller can verify against
+ * what recordPair() returned).
+ */
+export function recordPairOutcome(args) {
+    const cfg = getConfig();
+    const hash = taskHash(args.task);
+    if (!cfg.enabled)
+        return { recorded: false, taskHash: hash };
+    const row = {
+        v: 1,
+        type: 'pair-outcome',
+        ts: new Date().toISOString(),
+        task_hash: hash,
+        bandit: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },
+        ser: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },
+        outcome: args.outcome,
+    };
+    appendRow(row);
+    return { recorded: true, taskHash: hash };
+}
+/**
+ * Status helper for diagnostics / smoke tests.
+ */
+export function parallelRecorderStatus() {
+    const cfg = getConfig();
+    return {
+        enabled: cfg.enabled,
+        path: cfg.path,
+        includeTaskText: cfg.includeTaskText,
+        taskCharLimit: cfg.taskCharLimit,
+        maxBytes: cfg.maxBytes,
+    };
+}
+/** @internal — test helper. */
+export function __resetParallelRecorderForTests() {
+    _cfg = null;
+}
+//# sourceMappingURL=router-parallel-recorder.js.map

package/dist/src/ruvector/router-parallel-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-parallel-recorder.js","sourceRoot":"","sources":["../../../src/ruvector/router-parallel-recorder.ts"],"names":[],"mappings":"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"}