@graphrefly/graphrefly 0.47.2 → 0.48.0

package/dist/solutions/index.d.cts

@@ -1,5 +1,5 @@
 export { k as agentLoop, l as agentMemory } from '../agents-C0Ji9ldU.cjs';
-export { r as harnessLoop, s as refineLoop, t as spawnable } from '../spawnable-5mDY501F.cjs';
+export { r as harnessLoop, s as refineLoop, t as spawnable } from '../spawnable-B2IlW60f.cjs';
 export { g as guardedExecution } from '../guarded-execution-C-3hnP6A.cjs';
 export { resilientPipeline } from '../presets/resilience/index.cjs';
 import '@graphrefly/pure-ts/extra';
@@ -19,5 +19,5 @@ import '../audit-C_bPfkqS.cjs';
 import '../retry-DWuhjvsA.cjs';
 import '../backoff-Bnb9OoPh.cjs';
 import '../status-U-rUI79b.cjs';
-import '../rate-limiter-DpVbSYdH.cjs';
+import '../rate-limiter-DC26FM8J.cjs';
 import '../breaker-ugSdq54q.cjs';

package/dist/solutions/index.d.ts

@@ -1,5 +1,5 @@
 export { k as agentLoop, l as agentMemory } from '../agents-C9zexT7I.js';
-export { r as harnessLoop, s as refineLoop, t as spawnable } from '../spawnable-D3lR0oQu.js';
+export { r as harnessLoop, s as refineLoop, t as spawnable } from '../spawnable-tttFz2Nh.js';
 export { g as guardedExecution } from '../guarded-execution-BcdtxeBk.js';
 export { resilientPipeline } from '../presets/resilience/index.js';
 import '@graphrefly/pure-ts/extra';
@@ -19,5 +19,5 @@ import '../audit-BAXb3VOg.js';
 import '../retry-BDbRZ_gx.js';
 import '../backoff-Bnb9OoPh.js';
 import '../status-U-rUI79b.js';
-import '../rate-limiter-CEALq4N1.js';
+import '../rate-limiter-DyWpwpQP.js';
 import '../breaker-C9skL3d8.js';

package/dist/solutions/index.js

@@ -1,47 +1,47 @@
 import "../chunk-3CEXCBN6.js";
+import {
+  harnessLoop,
+  refineLoop,
+  spawnable
+} from "../chunk-YBJVKMTM.js";
 import {
   guardedExecution
-} from "../chunk-FVINAAKA.js";
+} from "../chunk-NBK6QQMG.js";
 import {
   resilientPipeline
-} from "../chunk-WGDEBIP4.js";
+} from "../chunk-X6ESZDR6.js";
 import {
   agentMemory
-} from "../chunk-R6ZCSXKX.js";
-import {
-  harnessLoop,
-  refineLoop,
-  spawnable
-} from "../chunk-PTWADEH3.js";
+} from "../chunk-23MAWVOJ.js";
 import {
   agentLoop
-} from "../chunk-FQSQONOU.js";
-import "../chunk-CEVNQ74M.js";
+} from "../chunk-65OM4XLQ.js";
 import "../chunk-OIWU3NYV.js";
-import "../chunk-PKPO3JTZ.js";
-import "../chunk-KRFGO5QH.js";
-import "../chunk-6MRSX3YK.js";
-import "../chunk-DDTS7F5O.js";
-import "../chunk-EP4WVQLX.js";
-import "../chunk-T7SP3EYR.js";
+import "../chunk-AQAKDE7F.js";
+import "../chunk-3YGXPUHW.js";
+import "../chunk-MQMTRKY3.js";
+import "../chunk-B5Y5GPD5.js";
+import "../chunk-LTSI7ULC.js";
+import "../chunk-ZW32BPXV.js";
+import "../chunk-T2U6N3FV.js";
+import "../chunk-T5URUIIY.js";
 import "../chunk-GUNIRPEJ.js";
-import "../chunk-N65E26UL.js";
-import "../chunk-QFE5BQH7.js";
-import "../chunk-MS3WPRJR.js";
-import "../chunk-7AVQIGF6.js";
-import "../chunk-NPRP3MCV.js";
-import "../chunk-QMBYUVRL.js";
-import "../chunk-FMPF42Q4.js";
-import "../chunk-BXGZFGZ4.js";
-import "../chunk-IOJDYUA7.js";
-import "../chunk-OXD5LFQP.js";
-import "../chunk-5GVURVIG.js";
-import "../chunk-N6MNJNHB.js";
+import "../chunk-XEWV254I.js";
+import "../chunk-3REMCHSS.js";
+import "../chunk-K4ZYJ4EM.js";
+import "../chunk-DHDCOOJU.js";
 import "../chunk-F7EKHR32.js";
 import "../chunk-JA67ZQG2.js";
 import "../chunk-KUFXLAEY.js";
 import "../chunk-TSBFTJKM.js";
 import "../chunk-P5LBT622.js";
+import "../chunk-QMBYUVRL.js";
+import "../chunk-FMPF42Q4.js";
+import "../chunk-C5QD5DQX.js";
+import "../chunk-V46JWFGV.js";
+import "../chunk-G7H6PN7P.js";
+import "../chunk-MMHGYX44.js";
+import "../chunk-N6MNJNHB.js";
 import "../chunk-AZDQPQ3V.js";
 export {
   agentLoop,

package/dist/{spawnable-5mDY501F.d.cts → spawnable-B2IlW60f.d.cts}

@@ -209,7 +209,17 @@ interface RefineLoopOptions extends ConvergenceOptions {
  * / `this._iteration` instead of factory-local closures.
  */
 declare class RefineLoopGraph<T> extends Graph {
-    readonly best: Node<T | null>;
+    /**
+     * Best candidate so far. **SENTINEL until the first iteration settles** —
+     * `loop.best.cache` is `undefined` (not `null`) before any iteration
+     * produces a best, and a degenerate empty-candidate iteration leaves the
+     * prior best in place rather than wiping it. Consumers guard with
+     * `=== undefined` (spec §3 SENTINEL), not `== null`. (Anti-pattern sweep
+     * 2026-05-18: dropped the `initial: null` eager-placeholder; `null` is
+     * reserved for the per-iteration {@link Iteration.best} data field where an
+     * empty batch is a valid domain value.)
+     */
+    readonly best: Node<T>;
     /**
      * Best score so far. Pseudo-private (`_score`) to avoid colliding with any
      * future `Graph.prototype.score` method (B5d forward-compat hazard
@@ -502,7 +512,18 @@ declare class HarnessGraph<A = unknown> extends Graph {
      * (use {@link unrouted}), and the internal `triage-output` fan-in.
      */
     readonly queueTopics: ReadonlyMap<QueueRoute, TopicGraph<TriagedItem>>;
-    /** Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`. */
+    /**
+     * Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`.
+     *
+     * **Ownership (EC10/EC15).** Owned by the harness: it is mounted as a
+     * child subgraph (`harness.mount("strategy", strategy)`), so its disposal
+     * cascades from `harness.destroy()` via the mount lifecycle. Do **not**
+     * call `strategy.destroy()` independently — the harness's `triage-input`
+     * node and (when `opts.priority` is set) `buildPriorityScores` hold
+     * cross-graph deps on `strategy.entries`; destroying the strategy out of
+     * band staleness those nodes while the rest of the loop keeps running.
+     * Read/subscribe freely; let the harness own the lifecycle.
+     */
     readonly strategy: StrategyModelGraph;
     /** Global retry count across all items (circuit breaker). Reactive — subscribable. */
     readonly totalRetries: Node<number>;

package/dist/{spawnable-D3lR0oQu.d.ts → spawnable-tttFz2Nh.d.ts}

@@ -209,7 +209,17 @@ interface RefineLoopOptions extends ConvergenceOptions {
  * / `this._iteration` instead of factory-local closures.
  */
 declare class RefineLoopGraph<T> extends Graph {
-    readonly best: Node<T | null>;
+    /**
+     * Best candidate so far. **SENTINEL until the first iteration settles** —
+     * `loop.best.cache` is `undefined` (not `null`) before any iteration
+     * produces a best, and a degenerate empty-candidate iteration leaves the
+     * prior best in place rather than wiping it. Consumers guard with
+     * `=== undefined` (spec §3 SENTINEL), not `== null`. (Anti-pattern sweep
+     * 2026-05-18: dropped the `initial: null` eager-placeholder; `null` is
+     * reserved for the per-iteration {@link Iteration.best} data field where an
+     * empty batch is a valid domain value.)
+     */
+    readonly best: Node<T>;
     /**
      * Best score so far. Pseudo-private (`_score`) to avoid colliding with any
      * future `Graph.prototype.score` method (B5d forward-compat hazard
@@ -502,7 +512,18 @@ declare class HarnessGraph<A = unknown> extends Graph {
      * (use {@link unrouted}), and the internal `triage-output` fan-in.
      */
     readonly queueTopics: ReadonlyMap<QueueRoute, TopicGraph<TriagedItem>>;
-    /** Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`. */
+    /**
+     * Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`.
+     *
+     * **Ownership (EC10/EC15).** Owned by the harness: it is mounted as a
+     * child subgraph (`harness.mount("strategy", strategy)`), so its disposal
+     * cascades from `harness.destroy()` via the mount lifecycle. Do **not**
+     * call `strategy.destroy()` independently — the harness's `triage-input`
+     * node and (when `opts.priority` is set) `buildPriorityScores` hold
+     * cross-graph deps on `strategy.entries`; destroying the strategy out of
+     * band staleness those nodes while the rest of the loop keeps running.
+     * Read/subscribe freely; let the harness own the lifecycle.
+     */
     readonly strategy: StrategyModelGraph;
     /** Global retry count across all items (circuit breaker). Reactive — subscribable. */
     readonly totalRetries: Node<number>;

package/dist/testing/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var testing_exports = {};
+__export(testing_exports, {
+  mockLLM: () => mockLLM
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/testing/mock-llm.ts
+var STAGE_KEYWORDS = [
+  ["execute", ["implementation agent", "produce a fix"]],
+  ["verify", ["qa reviewer", "verify whether"]],
+  ["triage", ["triage classifier", "intake item"]]
+];
+function detectStage(text, customStages) {
+  const lower = text.toLowerCase();
+  for (const [stage, keywords] of STAGE_KEYWORDS) {
+    if (keywords.some((kw) => lower.includes(kw))) return stage;
+  }
+  if (customStages) {
+    for (const stage of Object.keys(customStages)) {
+      if (lower.includes(stage.toLowerCase())) return stage;
+    }
+  }
+  return "unknown";
+}
+function mockLLM(script = {}) {
+  const calls = [];
+  const stageCounts = /* @__PURE__ */ new Map();
+  const stageIndices = /* @__PURE__ */ new Map();
+  function getResponse(stage) {
+    const stageScript = script.stages?.[stage];
+    if (!stageScript) return script.fallback ?? {};
+    const idx = stageIndices.get(stage) ?? 0;
+    const responses = stageScript.responses;
+    const response = responses[Math.min(idx, responses.length - 1)];
+    stageIndices.set(stage, idx + 1);
+    return response;
+  }
+  function invoke(messages) {
+    const text = messages.map((m) => m.content).join(" ");
+    const stage = detectStage(text, script.stages);
+    const count = stageCounts.get(stage) ?? 0;
+    stageCounts.set(stage, count + 1);
+    const responseData = getResponse(stage);
+    const response = {
+      content: typeof responseData === "string" ? responseData : JSON.stringify(responseData),
+      usage: { input: { regular: 0 }, output: { regular: 0 } }
+    };
+    calls.push({ stage, messages, response });
+    return Promise.resolve(response);
+  }
+  async function* stream() {
+    yield { type: "token", delta: "mock stream" };
+    yield { type: "usage", usage: { input: { regular: 0 }, output: { regular: 0 } } };
+    yield { type: "finish", reason: "stop" };
+  }
+  return {
+    provider: "mock",
+    calls,
+    get stageCounts() {
+      return stageCounts;
+    },
+    callsFor(stage) {
+      return calls.filter((c) => c.stage === stage);
+    },
+    reset() {
+      calls.length = 0;
+      stageCounts.clear();
+      stageIndices.clear();
+    },
+    invoke,
+    stream
+  };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/testing/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/index.ts","../../src/testing/mock-llm.ts"],"sourcesContent":["/**\n * `@graphrefly/graphrefly/testing` — public test utilities.\n *\n * Universal tier (browser + Node safe). Test-time helpers for exercising\n * GraphReFly AI / harness patterns without a real LLM wire call.\n *\n * @module\n */\n\nexport * from \"./mock-llm.js\";\n","/**\n * Scenario-scripted mock LLM adapter for harness and AI pattern testing.\n *\n * Detects the calling stage from prompt content and returns scripted responses.\n * Records all calls for assertions.\n *\n * @module\n */\n\nimport type { ChatMessage, LLMAdapter, LLMResponse } from \"../utils/ai/index.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** A single recorded call to the mock adapter. */\nexport interface MockCall {\n\tstage: string;\n\tmessages: readonly ChatMessage[];\n\tresponse: LLMResponse;\n}\n\n/** Per-stage response script. Cycles through responses on each call. */\nexport interface StageScript {\n\t/** Ordered responses — each call consumes the next; last one repeats. */\n\tresponses: unknown[];\n}\n\n/** Configuration for {@link mockLLM}. */\nexport interface MockScript {\n\t/** Stage-aware response scripts. Stage is detected from prompt keywords. */\n\tstages?: Record<string, StageScript>;\n\t/** Fallback response for unmatched prompts. */\n\tfallback?: unknown;\n}\n\n/** Extended LLM adapter with call recording and inspection. */\nexport interface MockLLMAdapter extends LLMAdapter {\n\t/** All calls recorded in order. */\n\treadonly calls: MockCall[];\n\t/** Per-stage call counts. */\n\treadonly stageCounts: ReadonlyMap<string, number>;\n\t/** Calls filtered by stage name. */\n\tcallsFor(stage: string): MockCall[];\n\t/** Reset all counters and call history. */\n\treset(): void;\n}\n\n// ---------------------------------------------------------------------------\n// Stage detection\n// ---------------------------------------------------------------------------\n\n/**\n * Default stage detection keywords (matched against lowercased prompt text).\n * Order matters: more specific phrases checked first to avoid substring\n * collisions (e.g. \"triaged issue\" in execute prompt matching \"triage\").\n */\nconst STAGE_KEYWORDS: [string, string[]][] = [\n\t[\"execute\", [\"implementation agent\", \"produce a fix\"]],\n\t[\"verify\", [\"qa reviewer\", \"verify whether\"]],\n\t[\"triage\", [\"triage classifier\", \"intake item\"]],\n];\n\nfunction detectStage(text: string, customStages?: Record<string, StageScript>): string {\n\tconst lower = text.toLowerCase();\n\n\t// Check built-in multi-word keywords first (more specific, avoids substring collisions\n\t// like \"triaged\" matching \"triage\")\n\tfor (const [stage, keywords] of STAGE_KEYWORDS) {\n\t\tif (keywords.some((kw) => lower.includes(kw))) return stage;\n\t}\n\n\t// Fall back to custom stage names as keywords\n\tif (customStages) {\n\t\tfor (const stage of Object.keys(customStages)) {\n\t\t\tif (lower.includes(stage.toLowerCase())) return stage;\n\t\t}\n\t}\n\n\treturn \"unknown\";\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a scenario-scripted mock LLM adapter.\n *\n * ```ts\n * const mock = mockLLM({\n *   stages: {\n *     triage:  { responses: [{ rootCause: \"missing-fn\", intervention: \"catalog-fn\", route: \"auto-fix\", priority: 80 }] },\n *     execute: { responses: [{ outcome: \"success\", detail: \"Fixed\" }] },\n *     verify:  { responses: [{ verified: false, findings: [\"err\"], errorClass: \"self-correctable\" },\n *                            { verified: true, findings: [\"ok\"] }] },\n *   },\n * });\n * ```\n */\nexport function mockLLM(script: MockScript = {}): MockLLMAdapter {\n\tconst calls: MockCall[] = [];\n\tconst stageCounts = new Map<string, number>();\n\tconst stageIndices = new Map<string, number>();\n\n\tfunction getResponse(stage: string): unknown {\n\t\tconst stageScript = script.stages?.[stage];\n\t\tif (!stageScript) return script.fallback ?? {};\n\n\t\tconst idx = stageIndices.get(stage) ?? 0;\n\t\tconst responses = stageScript.responses;\n\t\tconst response = responses[Math.min(idx, responses.length - 1)];\n\t\tstageIndices.set(stage, idx + 1);\n\t\treturn response;\n\t}\n\n\tfunction invoke(messages: readonly ChatMessage[]): Promise<LLMResponse> {\n\t\tconst text = messages.map((m) => m.content).join(\" \");\n\t\tconst stage = detectStage(text, script.stages);\n\n\t\tconst count = stageCounts.get(stage) ?? 0;\n\t\tstageCounts.set(stage, count + 1);\n\n\t\tconst responseData = getResponse(stage);\n\t\tconst response: LLMResponse = {\n\t\t\tcontent: typeof responseData === \"string\" ? responseData : JSON.stringify(responseData),\n\t\t\tusage: { input: { regular: 0 }, output: { regular: 0 } },\n\t\t};\n\n\t\tcalls.push({ stage, messages, response });\n\t\treturn Promise.resolve(response);\n\t}\n\n\tasync function* stream(): AsyncIterable<\n\t\timport(\"../utils/ai/adapters/core/types.js\").StreamDelta\n\t> {\n\t\tyield { type: \"token\", delta: \"mock stream\" };\n\t\tyield { type: \"usage\", usage: { input: { regular: 0 }, output: { regular: 0 } } };\n\t\tyield { type: \"finish\", reason: \"stop\" };\n\t}\n\n\treturn {\n\t\tprovider: \"mock\",\n\t\tcalls,\n\t\tget stageCounts() {\n\t\t\treturn stageCounts as ReadonlyMap<string, number>;\n\t\t},\n\t\tcallsFor(stage: string) {\n\t\t\treturn calls.filter((c) => c.stage === stage);\n\t\t},\n\t\treset() {\n\t\t\tcalls.length = 0;\n\t\t\tstageCounts.clear();\n\t\t\tstageIndices.clear();\n\t\t},\n\t\tinvoke,\n\t\tstream,\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyDA,IAAM,iBAAuC;AAAA,EAC5C,CAAC,WAAW,CAAC,wBAAwB,eAAe,CAAC;AAAA,EACrD,CAAC,UAAU,CAAC,eAAe,gBAAgB,CAAC;AAAA,EAC5C,CAAC,UAAU,CAAC,qBAAqB,aAAa,CAAC;AAChD;AAEA,SAAS,YAAY,MAAc,cAAoD;AACtF,QAAM,QAAQ,KAAK,YAAY;AAI/B,aAAW,CAAC,OAAO,QAAQ,KAAK,gBAAgB;AAC/C,QAAI,SAAS,KAAK,CAAC,OAAO,MAAM,SAAS,EAAE,CAAC,EAAG,QAAO;AAAA,EACvD;AAGA,MAAI,cAAc;AACjB,eAAW,SAAS,OAAO,KAAK,YAAY,GAAG;AAC9C,UAAI,MAAM,SAAS,MAAM,YAAY,CAAC,EAAG,QAAO;AAAA,IACjD;AAAA,EACD;AAEA,SAAO;AACR;AAoBO,SAAS,QAAQ,SAAqB,CAAC,GAAmB;AAChE,QAAM,QAAoB,CAAC;AAC3B,QAAM,cAAc,oBAAI,IAAoB;AAC5C,QAAM,eAAe,oBAAI,IAAoB;AAE7C,WAAS,YAAY,OAAwB;AAC5C,UAAM,cAAc,OAAO,SAAS,KAAK;AACzC,QAAI,CAAC,YAAa,QAAO,OAAO,YAAY,CAAC;AAE7C,UAAM,MAAM,aAAa,IAAI,KAAK,KAAK;AACvC,UAAM,YAAY,YAAY;AAC9B,UAAM,WAAW,UAAU,KAAK,IAAI,KAAK,UAAU,SAAS,CAAC,CAAC;AAC9D,iBAAa,IAAI,OAAO,MAAM,CAAC;AAC/B,WAAO;AAAA,EACR;AAEA,WAAS,OAAO,UAAwD;AACvE,UAAM,OAAO,SAAS,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG;AACpD,UAAM,QAAQ,YAAY,MAAM,OAAO,MAAM;AAE7C,UAAM,QAAQ,YAAY,IAAI,KAAK,KAAK;AACxC,gBAAY,IAAI,OAAO,QAAQ,CAAC;AAEhC,UAAM,eAAe,YAAY,KAAK;AACtC,UAAM,WAAwB;AAAA,MAC7B,SAAS,OAAO,iBAAiB,WAAW,eAAe,KAAK,UAAU,YAAY;AAAA,MACtF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,EAAE;AAAA,IACxD;AAEA,UAAM,KAAK,EAAE,OAAO,UAAU,SAAS,CAAC;AACxC,WAAO,QAAQ,QAAQ,QAAQ;AAAA,EAChC;AAEA,kBAAgB,SAEd;AACD,UAAM,EAAE,MAAM,SAAS,OAAO,cAAc;AAC5C,UAAM,EAAE,MAAM,SAAS,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;AAChF,UAAM,EAAE,MAAM,UAAU,QAAQ,OAAO;AAAA,EACxC;AAEA,SAAO;AAAA,IACN,UAAU;AAAA,IACV;AAAA,IACA,IAAI,cAAc;AACjB,aAAO;AAAA,IACR;AAAA,IACA,SAAS,OAAe;AACvB,aAAO,MAAM,OAAO,CAAC,MAAM,EAAE,UAAU,KAAK;AAAA,IAC7C;AAAA,IACA,QAAQ;AACP,YAAM,SAAS;AACf,kBAAY,MAAM;AAClB,mBAAa,MAAM;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/testing/index.d.cts

@@ -0,0 +1,59 @@
+import { a as ChatMessage, c as LLMResponse, L as LLMAdapter } from '../types-BB5Lw-pB.cjs';
+import '@graphrefly/pure-ts/core';
+import '@graphrefly/pure-ts/extra';
+
+/**
+ * Scenario-scripted mock LLM adapter for harness and AI pattern testing.
+ *
+ * Detects the calling stage from prompt content and returns scripted responses.
+ * Records all calls for assertions.
+ *
+ * @module
+ */
+
+/** A single recorded call to the mock adapter. */
+interface MockCall {
+    stage: string;
+    messages: readonly ChatMessage[];
+    response: LLMResponse;
+}
+/** Per-stage response script. Cycles through responses on each call. */
+interface StageScript {
+    /** Ordered responses — each call consumes the next; last one repeats. */
+    responses: unknown[];
+}
+/** Configuration for {@link mockLLM}. */
+interface MockScript {
+    /** Stage-aware response scripts. Stage is detected from prompt keywords. */
+    stages?: Record<string, StageScript>;
+    /** Fallback response for unmatched prompts. */
+    fallback?: unknown;
+}
+/** Extended LLM adapter with call recording and inspection. */
+interface MockLLMAdapter extends LLMAdapter {
+    /** All calls recorded in order. */
+    readonly calls: MockCall[];
+    /** Per-stage call counts. */
+    readonly stageCounts: ReadonlyMap<string, number>;
+    /** Calls filtered by stage name. */
+    callsFor(stage: string): MockCall[];
+    /** Reset all counters and call history. */
+    reset(): void;
+}
+/**
+ * Create a scenario-scripted mock LLM adapter.
+ *
+ * ```ts
+ * const mock = mockLLM({
+ *   stages: {
+ *     triage:  { responses: [{ rootCause: "missing-fn", intervention: "catalog-fn", route: "auto-fix", priority: 80 }] },
+ *     execute: { responses: [{ outcome: "success", detail: "Fixed" }] },
+ *     verify:  { responses: [{ verified: false, findings: ["err"], errorClass: "self-correctable" },
+ *                            { verified: true, findings: ["ok"] }] },
+ *   },
+ * });
+ * ```
+ */
+declare function mockLLM(script?: MockScript): MockLLMAdapter;
+
+export { type MockCall, type MockLLMAdapter, type MockScript, type StageScript, mockLLM };

package/dist/testing/index.d.ts

@@ -0,0 +1,59 @@
+import { a as ChatMessage, c as LLMResponse, L as LLMAdapter } from '../types-BB5Lw-pB.js';
+import '@graphrefly/pure-ts/core';
+import '@graphrefly/pure-ts/extra';
+
+/**
+ * Scenario-scripted mock LLM adapter for harness and AI pattern testing.
+ *
+ * Detects the calling stage from prompt content and returns scripted responses.
+ * Records all calls for assertions.
+ *
+ * @module
+ */
+
+/** A single recorded call to the mock adapter. */
+interface MockCall {
+    stage: string;
+    messages: readonly ChatMessage[];
+    response: LLMResponse;
+}
+/** Per-stage response script. Cycles through responses on each call. */
+interface StageScript {
+    /** Ordered responses — each call consumes the next; last one repeats. */
+    responses: unknown[];
+}
+/** Configuration for {@link mockLLM}. */
+interface MockScript {
+    /** Stage-aware response scripts. Stage is detected from prompt keywords. */
+    stages?: Record<string, StageScript>;
+    /** Fallback response for unmatched prompts. */
+    fallback?: unknown;
+}
+/** Extended LLM adapter with call recording and inspection. */
+interface MockLLMAdapter extends LLMAdapter {
+    /** All calls recorded in order. */
+    readonly calls: MockCall[];
+    /** Per-stage call counts. */
+    readonly stageCounts: ReadonlyMap<string, number>;
+    /** Calls filtered by stage name. */
+    callsFor(stage: string): MockCall[];
+    /** Reset all counters and call history. */
+    reset(): void;
+}
+/**
+ * Create a scenario-scripted mock LLM adapter.
+ *
+ * ```ts
+ * const mock = mockLLM({
+ *   stages: {
+ *     triage:  { responses: [{ rootCause: "missing-fn", intervention: "catalog-fn", route: "auto-fix", priority: 80 }] },
+ *     execute: { responses: [{ outcome: "success", detail: "Fixed" }] },
+ *     verify:  { responses: [{ verified: false, findings: ["err"], errorClass: "self-correctable" },
+ *                            { verified: true, findings: ["ok"] }] },
+ *   },
+ * });
+ * ```
+ */
+declare function mockLLM(script?: MockScript): MockLLMAdapter;
+
+export { type MockCall, type MockLLMAdapter, type MockScript, type StageScript, mockLLM };

package/dist/testing/index.js

@@ -0,0 +1,73 @@
+import "../chunk-AZDQPQ3V.js";
+
+// src/testing/mock-llm.ts
+var STAGE_KEYWORDS = [
+  ["execute", ["implementation agent", "produce a fix"]],
+  ["verify", ["qa reviewer", "verify whether"]],
+  ["triage", ["triage classifier", "intake item"]]
+];
+function detectStage(text, customStages) {
+  const lower = text.toLowerCase();
+  for (const [stage, keywords] of STAGE_KEYWORDS) {
+    if (keywords.some((kw) => lower.includes(kw))) return stage;
+  }
+  if (customStages) {
+    for (const stage of Object.keys(customStages)) {
+      if (lower.includes(stage.toLowerCase())) return stage;
+    }
+  }
+  return "unknown";
+}
+function mockLLM(script = {}) {
+  const calls = [];
+  const stageCounts = /* @__PURE__ */ new Map();
+  const stageIndices = /* @__PURE__ */ new Map();
+  function getResponse(stage) {
+    const stageScript = script.stages?.[stage];
+    if (!stageScript) return script.fallback ?? {};
+    const idx = stageIndices.get(stage) ?? 0;
+    const responses = stageScript.responses;
+    const response = responses[Math.min(idx, responses.length - 1)];
+    stageIndices.set(stage, idx + 1);
+    return response;
+  }
+  function invoke(messages) {
+    const text = messages.map((m) => m.content).join(" ");
+    const stage = detectStage(text, script.stages);
+    const count = stageCounts.get(stage) ?? 0;
+    stageCounts.set(stage, count + 1);
+    const responseData = getResponse(stage);
+    const response = {
+      content: typeof responseData === "string" ? responseData : JSON.stringify(responseData),
+      usage: { input: { regular: 0 }, output: { regular: 0 } }
+    };
+    calls.push({ stage, messages, response });
+    return Promise.resolve(response);
+  }
+  async function* stream() {
+    yield { type: "token", delta: "mock stream" };
+    yield { type: "usage", usage: { input: { regular: 0 }, output: { regular: 0 } } };
+    yield { type: "finish", reason: "stop" };
+  }
+  return {
+    provider: "mock",
+    calls,
+    get stageCounts() {
+      return stageCounts;
+    },
+    callsFor(stage) {
+      return calls.filter((c) => c.stage === stage);
+    },
+    reset() {
+      calls.length = 0;
+      stageCounts.clear();
+      stageIndices.clear();
+    },
+    invoke,
+    stream
+  };
+}
+export {
+  mockLLM
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/mock-llm.ts"],"sourcesContent":["/**\n * Scenario-scripted mock LLM adapter for harness and AI pattern testing.\n *\n * Detects the calling stage from prompt content and returns scripted responses.\n * Records all calls for assertions.\n *\n * @module\n */\n\nimport type { ChatMessage, LLMAdapter, LLMResponse } from \"../utils/ai/index.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** A single recorded call to the mock adapter. */\nexport interface MockCall {\n\tstage: string;\n\tmessages: readonly ChatMessage[];\n\tresponse: LLMResponse;\n}\n\n/** Per-stage response script. Cycles through responses on each call. */\nexport interface StageScript {\n\t/** Ordered responses — each call consumes the next; last one repeats. */\n\tresponses: unknown[];\n}\n\n/** Configuration for {@link mockLLM}. */\nexport interface MockScript {\n\t/** Stage-aware response scripts. Stage is detected from prompt keywords. */\n\tstages?: Record<string, StageScript>;\n\t/** Fallback response for unmatched prompts. */\n\tfallback?: unknown;\n}\n\n/** Extended LLM adapter with call recording and inspection. */\nexport interface MockLLMAdapter extends LLMAdapter {\n\t/** All calls recorded in order. */\n\treadonly calls: MockCall[];\n\t/** Per-stage call counts. */\n\treadonly stageCounts: ReadonlyMap<string, number>;\n\t/** Calls filtered by stage name. */\n\tcallsFor(stage: string): MockCall[];\n\t/** Reset all counters and call history. */\n\treset(): void;\n}\n\n// ---------------------------------------------------------------------------\n// Stage detection\n// ---------------------------------------------------------------------------\n\n/**\n * Default stage detection keywords (matched against lowercased prompt text).\n * Order matters: more specific phrases checked first to avoid substring\n * collisions (e.g. \"triaged issue\" in execute prompt matching \"triage\").\n */\nconst STAGE_KEYWORDS: [string, string[]][] = [\n\t[\"execute\", [\"implementation agent\", \"produce a fix\"]],\n\t[\"verify\", [\"qa reviewer\", \"verify whether\"]],\n\t[\"triage\", [\"triage classifier\", \"intake item\"]],\n];\n\nfunction detectStage(text: string, customStages?: Record<string, StageScript>): string {\n\tconst lower = text.toLowerCase();\n\n\t// Check built-in multi-word keywords first (more specific, avoids substring collisions\n\t// like \"triaged\" matching \"triage\")\n\tfor (const [stage, keywords] of STAGE_KEYWORDS) {\n\t\tif (keywords.some((kw) => lower.includes(kw))) return stage;\n\t}\n\n\t// Fall back to custom stage names as keywords\n\tif (customStages) {\n\t\tfor (const stage of Object.keys(customStages)) {\n\t\t\tif (lower.includes(stage.toLowerCase())) return stage;\n\t\t}\n\t}\n\n\treturn \"unknown\";\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a scenario-scripted mock LLM adapter.\n *\n * ```ts\n * const mock = mockLLM({\n *   stages: {\n *     triage:  { responses: [{ rootCause: \"missing-fn\", intervention: \"catalog-fn\", route: \"auto-fix\", priority: 80 }] },\n *     execute: { responses: [{ outcome: \"success\", detail: \"Fixed\" }] },\n *     verify:  { responses: [{ verified: false, findings: [\"err\"], errorClass: \"self-correctable\" },\n *                            { verified: true, findings: [\"ok\"] }] },\n *   },\n * });\n * ```\n */\nexport function mockLLM(script: MockScript = {}): MockLLMAdapter {\n\tconst calls: MockCall[] = [];\n\tconst stageCounts = new Map<string, number>();\n\tconst stageIndices = new Map<string, number>();\n\n\tfunction getResponse(stage: string): unknown {\n\t\tconst stageScript = script.stages?.[stage];\n\t\tif (!stageScript) return script.fallback ?? {};\n\n\t\tconst idx = stageIndices.get(stage) ?? 0;\n\t\tconst responses = stageScript.responses;\n\t\tconst response = responses[Math.min(idx, responses.length - 1)];\n\t\tstageIndices.set(stage, idx + 1);\n\t\treturn response;\n\t}\n\n\tfunction invoke(messages: readonly ChatMessage[]): Promise<LLMResponse> {\n\t\tconst text = messages.map((m) => m.content).join(\" \");\n\t\tconst stage = detectStage(text, script.stages);\n\n\t\tconst count = stageCounts.get(stage) ?? 0;\n\t\tstageCounts.set(stage, count + 1);\n\n\t\tconst responseData = getResponse(stage);\n\t\tconst response: LLMResponse = {\n\t\t\tcontent: typeof responseData === \"string\" ? responseData : JSON.stringify(responseData),\n\t\t\tusage: { input: { regular: 0 }, output: { regular: 0 } },\n\t\t};\n\n\t\tcalls.push({ stage, messages, response });\n\t\treturn Promise.resolve(response);\n\t}\n\n\tasync function* stream(): AsyncIterable<\n\t\timport(\"../utils/ai/adapters/core/types.js\").StreamDelta\n\t> {\n\t\tyield { type: \"token\", delta: \"mock stream\" };\n\t\tyield { type: \"usage\", usage: { input: { regular: 0 }, output: { regular: 0 } } };\n\t\tyield { type: \"finish\", reason: \"stop\" };\n\t}\n\n\treturn {\n\t\tprovider: \"mock\",\n\t\tcalls,\n\t\tget stageCounts() {\n\t\t\treturn stageCounts as ReadonlyMap<string, number>;\n\t\t},\n\t\tcallsFor(stage: string) {\n\t\t\treturn calls.filter((c) => c.stage === stage);\n\t\t},\n\t\treset() {\n\t\t\tcalls.length = 0;\n\t\t\tstageCounts.clear();\n\t\t\tstageIndices.clear();\n\t\t},\n\t\tinvoke,\n\t\tstream,\n\t};\n}\n"],"mappings":";;;AAyDA,IAAM,iBAAuC;AAAA,EAC5C,CAAC,WAAW,CAAC,wBAAwB,eAAe,CAAC;AAAA,EACrD,CAAC,UAAU,CAAC,eAAe,gBAAgB,CAAC;AAAA,EAC5C,CAAC,UAAU,CAAC,qBAAqB,aAAa,CAAC;AAChD;AAEA,SAAS,YAAY,MAAc,cAAoD;AACtF,QAAM,QAAQ,KAAK,YAAY;AAI/B,aAAW,CAAC,OAAO,QAAQ,KAAK,gBAAgB;AAC/C,QAAI,SAAS,KAAK,CAAC,OAAO,MAAM,SAAS,EAAE,CAAC,EAAG,QAAO;AAAA,EACvD;AAGA,MAAI,cAAc;AACjB,eAAW,SAAS,OAAO,KAAK,YAAY,GAAG;AAC9C,UAAI,MAAM,SAAS,MAAM,YAAY,CAAC,EAAG,QAAO;AAAA,IACjD;AAAA,EACD;AAEA,SAAO;AACR;AAoBO,SAAS,QAAQ,SAAqB,CAAC,GAAmB;AAChE,QAAM,QAAoB,CAAC;AAC3B,QAAM,cAAc,oBAAI,IAAoB;AAC5C,QAAM,eAAe,oBAAI,IAAoB;AAE7C,WAAS,YAAY,OAAwB;AAC5C,UAAM,cAAc,OAAO,SAAS,KAAK;AACzC,QAAI,CAAC,YAAa,QAAO,OAAO,YAAY,CAAC;AAE7C,UAAM,MAAM,aAAa,IAAI,KAAK,KAAK;AACvC,UAAM,YAAY,YAAY;AAC9B,UAAM,WAAW,UAAU,KAAK,IAAI,KAAK,UAAU,SAAS,CAAC,CAAC;AAC9D,iBAAa,IAAI,OAAO,MAAM,CAAC;AAC/B,WAAO;AAAA,EACR;AAEA,WAAS,OAAO,UAAwD;AACvE,UAAM,OAAO,SAAS,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG;AACpD,UAAM,QAAQ,YAAY,MAAM,OAAO,MAAM;AAE7C,UAAM,QAAQ,YAAY,IAAI,KAAK,KAAK;AACxC,gBAAY,IAAI,OAAO,QAAQ,CAAC;AAEhC,UAAM,eAAe,YAAY,KAAK;AACtC,UAAM,WAAwB;AAAA,MAC7B,SAAS,OAAO,iBAAiB,WAAW,eAAe,KAAK,UAAU,YAAY;AAAA,MACtF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,EAAE;AAAA,IACxD;AAEA,UAAM,KAAK,EAAE,OAAO,UAAU,SAAS,CAAC;AACxC,WAAO,QAAQ,QAAQ,QAAQ;AAAA,EAChC;AAEA,kBAAgB,SAEd;AACD,UAAM,EAAE,MAAM,SAAS,OAAO,cAAc;AAC5C,UAAM,EAAE,MAAM,SAAS,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;AAChF,UAAM,EAAE,MAAM,UAAU,QAAQ,OAAO;AAAA,EACxC;AAEA,SAAO;AAAA,IACN,UAAU;AAAA,IACV;AAAA,IACA,IAAI,cAAc;AACjB,aAAO;AAAA,IACR;AAAA,IACA,SAAS,OAAe;AACvB,aAAO,MAAM,OAAO,CAAC,MAAM,EAAE,UAAU,KAAK;AAAA,IAC7C;AAAA,IACA,QAAQ;AACP,YAAM,SAAS;AACf,kBAAY,MAAM;AAClB,mBAAa,MAAM;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}