@tangle-network/agent-eval 0.216.0 → 0.217.1

package/dist/findings-store-BMVQtEsm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings-store-BMVQtEsm.js","names":["messageOf"],"sources":["../src/analyst/chat-trace-engine.ts","../src/locked-jsonl-appender.ts","../src/analyst/findings-store.ts"],"sourcesContent":["/**\n * A `TraceAnalysisEngine` that runs entirely inside Node against a\n * caller-owned `ChatClient`.\n *\n * The other engine in this package, `createDspyRlmTraceEngine`, reaches the\n * DSPy RLM through a Python subprocess. That made every model-backed analyst\n * unreachable for a consumer that already owns a model seam and no Python:\n * `createTraceAnalyst` requires an engine, the only exported constructor\n * required a Python runner, so `buildDefaultAnalystRegistry()` registered the\n * deterministic analyst alone and `analystsFromRegistry` refused the result.\n *\n * This engine closes that path. It drives the same investigation contract —\n * bounded trace tools, a prose answer, a strict findings array — with native\n * function calls over the transport the caller already bound with\n * `createChatClient`. A caller holding a bare\n * `(request: LlmCallRequest) => Promise<LlmCallResult>` adapts it in one line:\n *\n *   createChatClient({ transport: 'custom', chat: call, defaultModel, maximumAttempts })\n *\n * agent-eval still executes no paid model and holds no provider credential.\n * Every call goes through `paidChat`, so the shared cost ledger reserves the\n * priced maximum before the call and settles the receipt after it.\n *\n * Shape of one investigation:\n *   1. Investigation turns. The model reads the trace store through the tools\n *      its analyst kind was given. A turn that requests no tool ends the\n *      phase; an exhausted iteration or tool budget also ends it.\n *   2. One report turn. The model returns `{ answer, findings }` as JSON,\n *      decoded by the same `decodeRawFindingArray` the Python bridge uses, so\n *      a row this engine accepts is a row that engine could report.\n */\n\nimport { z } from 'zod'\nimport { paidChat } from '../chat-json-call'\nimport type { CustomTokenPricing } from '../cost-ledger'\nimport { errorMessage as messageOf } from '../errors'\nimport {\n  extractJsonPayload,\n  type LlmCallRequest,\n  type LlmMessage,\n  type LlmThinkingMode,\n  type LlmToolCall,\n  type LlmToolDefinition,\n} from '../llm-client'\nimport type { TraceAnalysisToolDescriptor } from '../trace-analyst/tools'\nimport type { ChatClient } from './chat-client'\nimport {\n  DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS,\n  type TraceAnalysisEngine,\n  type TraceAnalysisEngineRequest,\n  type TraceAnalysisEngineResult,\n} from './engine'\nimport { decodeRawFindingArray } from './finding-codec'\nimport { RawAnalystFindingSchema } from './finding-signature'\n\n/** Bumped whenever this engine's execution behavior changes. */\nconst CHAT_TRACE_ENGINE_VERSION = '1.0.0'\nconst ENGINE_ID = 'chat-trace'\n\n/** Marker appended to a tool result cut down to the retained-output budget. */\nconst TRUNCATION_MARKER = '\\n…[truncated to the analyst maxOutputChars budget]'\n\nexport interface ChatTraceEngineOptions {\n  /**\n   * Caller-owned transport. Build it with `createChatClient`; agent-eval never\n   * receives the provider credential.\n   */\n  chat: ChatClient\n  /** Model for every call. Defaults to the client's `defaultModel`. */\n  model?: string\n  /** Endpoint rates used when the transport reports no billed amount. */\n  pricing?: CustomTokenPricing\n  /** Completion cap per turn. Default: {@link DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS}. */\n  maxOutputTokens?: number\n  /** Sampling temperature. Omitted from the request when absent. */\n  temperature?: number\n  /** Provider reasoning mode. Omitted when the provider default should apply. */\n  thinking?: LlmThinkingMode\n  /** Per-call deadline handed to the transport. */\n  requestTimeoutMs?: number\n  /**\n   * How the report turn asks for structured output.\n   *\n   * `json-object` sends JSON mode, which every OpenAI-compatible endpoint\n   * accepts, and relies on the finding grammar the analyst kind already puts\n   * in its instructions. `json-schema` sends the generated response schema as\n   * well, which stricter endpoints honour and older ones reject. Default:\n   * `json-object`.\n   */\n  reportFormat?: 'json-object' | 'json-schema'\n}\n\n/**\n * The report envelope. Its `findings` rows are generated from\n * `RawAnalystFindingSchema`, so the schema offered to a provider and the\n * decoder that accepts the answer cannot drift apart.\n */\nfunction buildReportJsonSchema(): { name: string; schema: Record<string, unknown> } {\n  const row = z.toJSONSchema(RawAnalystFindingSchema, { target: 'draft-7' }) as Record<\n    string,\n    unknown\n  >\n  delete row.$schema\n  return {\n    name: 'trace_analysis_report',\n    schema: {\n      type: 'object',\n      additionalProperties: false,\n      required: ['answer', 'findings'],\n      properties: {\n        answer: { type: 'string', description: 'Direct prose answer to the question.' },\n        findings: { type: 'array', items: row },\n      },\n    },\n  }\n}\n\nconst REPORT_JSON_SCHEMA = buildReportJsonSchema()\n\n/**\n * Run bounded recursive trace analysis in-process over a caller-owned chat\n * transport. No Python, no subprocess, no loopback proxy.\n */\nexport function createChatTraceEngine(options: ChatTraceEngineOptions): TraceAnalysisEngine {\n  const model = resolveModel(options)\n  const maxOutputTokens = options.maxOutputTokens ?? DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS\n  if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) {\n    throw new TypeError('chat trace engine maxOutputTokens must be a positive safe integer')\n  }\n  if (\n    options.temperature !== undefined &&\n    (!Number.isFinite(options.temperature) || options.temperature < 0)\n  ) {\n    throw new TypeError('chat trace engine temperature must be a non-negative finite number')\n  }\n  if (\n    options.requestTimeoutMs !== undefined &&\n    (!Number.isSafeInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)\n  ) {\n    throw new TypeError('chat trace engine requestTimeoutMs must be a positive safe integer')\n  }\n  const reportFormat = options.reportFormat ?? 'json-object'\n  if (reportFormat !== 'json-object' && reportFormat !== 'json-schema') {\n    throw new TypeError(`chat trace engine reportFormat must be json-object or json-schema`)\n  }\n\n  return {\n    id: ENGINE_ID,\n    description:\n      'In-process recursive trace analysis over a caller-owned ChatClient with native tool calls.',\n    model,\n    version: CHAT_TRACE_ENGINE_VERSION,\n    executionConfig: {\n      kind: ENGINE_ID,\n      model,\n      transport: options.chat.transport,\n      maximum_attempts: options.chat.maximumAttempts ?? null,\n      pricing: options.pricing ? { ...options.pricing } : null,\n      max_output_tokens: maxOutputTokens,\n      temperature: options.temperature ?? null,\n      thinking: options.thinking ?? null,\n      request_timeout_ms: options.requestTimeoutMs ?? null,\n      report_format: reportFormat,\n      report_schema_name: REPORT_JSON_SCHEMA.name,\n    },\n    analyze: (request) => analyze(request, { ...options, model, maxOutputTokens, reportFormat }),\n  }\n}\n\ninterface ResolvedOptions extends ChatTraceEngineOptions {\n  model: string\n  maxOutputTokens: number\n  reportFormat: 'json-object' | 'json-schema'\n}\n\nasync function analyze(\n  request: TraceAnalysisEngineRequest,\n  options: ResolvedOptions,\n): Promise<TraceAnalysisEngineResult> {\n  // One model call is spent on the report, so a budget of one call would buy\n  // an answer with no investigation behind it. Refuse instead of pretending.\n  if (request.limits.maxLlmCalls < 2) {\n    throw new Error(\n      `chat trace engine reserves one model call for the report, so maxLlmCalls must be at least 2 (analyst '${request.analystId}' declared ${request.limits.maxLlmCalls})`,\n    )\n  }\n  const toolsByName = new Map(request.tools.map((tool) => [tool.name, tool]))\n  if (toolsByName.size !== request.tools.length) {\n    throw new Error(`chat trace engine received duplicate tool names for '${request.analystId}'`)\n  }\n  const toolDefinitions: LlmToolDefinition[] = request.tools.map((tool) => ({\n    type: 'function',\n    function: { name: tool.name, description: tool.description, parameters: tool.parameters },\n  }))\n  const investigationTurns = Math.max(\n    1,\n    Math.min(request.limits.maxIterations, request.limits.maxLlmCalls - 1),\n  )\n\n  const messages: LlmMessage[] = [\n    { role: 'system', content: systemPrompt(request, investigationTurns) },\n  ]\n  if (request.taskInputs) {\n    messages.push({ role: 'user', content: renderTaskInputs(request.taskInputs) })\n  }\n  messages.push({ role: 'user', content: request.question })\n\n  request.log?.('trace analyst engine started', {\n    engine: ENGINE_ID,\n    model: options.model,\n    transport: options.chat.transport,\n    tools: request.tools.map((tool) => tool.name),\n    limits: request.limits,\n  })\n\n  const trajectory: unknown[] = []\n  const servedModels = new Set<string>()\n  let modelCalls = 0\n  let toolCalls = 0\n  let truncatedToolResults = 0\n  let toolBudgetExhausted = false\n  let turnsUsed = 0\n  let stoppedOnAnswer = false\n\n  for (let turn = 0; turn < investigationTurns; turn++) {\n    turnsUsed = turn + 1\n    const response = await callModel(request, options, {\n      messages,\n      tools: toolDefinitions,\n      toolChoice: 'auto',\n      purpose: 'investigation',\n    })\n    modelCalls += 1\n    servedModels.add(response.servedModel ?? 'unreported')\n    const requested = response.toolCalls ?? []\n    messages.push({\n      role: 'assistant',\n      content: response.content,\n      ...(requested.length > 0 ? { toolCalls: requested } : {}),\n    })\n    trajectory.push({\n      turn: turnsUsed,\n      phase: 'investigation',\n      content: response.content,\n      tool_calls: requested.map((call) => ({ id: call.id, name: call.name })),\n      finish_reason: response.finishReason ?? null,\n    })\n    if (requested.length === 0) {\n      stoppedOnAnswer = true\n      break\n    }\n    for (const call of requested) {\n      if (toolCalls >= request.limits.maxToolCalls) {\n        toolBudgetExhausted = true\n        // Every requested id still needs an answer: a provider rejects the\n        // next turn when one tool call is left unanswered.\n        messages.push(toolMessage(call, exhaustedToolBudget(request.limits.maxToolCalls)))\n        continue\n      }\n      toolCalls += 1\n      const executed = await executeTool(call, toolsByName, request)\n      if (executed.truncated) truncatedToolResults += 1\n      messages.push(toolMessage(call, executed.payload))\n      trajectory.push({\n        turn: turnsUsed,\n        phase: 'tool',\n        name: call.name,\n        ok: executed.ok,\n        truncated: executed.truncated,\n        result_chars: executed.payload.length,\n      })\n    }\n    if (toolBudgetExhausted) break\n  }\n\n  messages.push({ role: 'user', content: reportPrompt(options.reportFormat) })\n  const report = await callModel(request, options, {\n    messages,\n    purpose: 'report',\n    json: options.reportFormat,\n  })\n  modelCalls += 1\n  servedModels.add(report.servedModel ?? 'unreported')\n  trajectory.push({\n    turn: turnsUsed + 1,\n    phase: 'report',\n    content: report.content,\n    finish_reason: report.finishReason ?? null,\n  })\n\n  const parsed = parseReport(report.content, request.analystId, (index, reason) => {\n    request.log?.('finding rejected: report row failed schema validation', {\n      engine: ENGINE_ID,\n      index,\n      reason,\n    })\n  })\n\n  const result: TraceAnalysisEngineResult = {\n    answer: parsed.answer,\n    findings: parsed.findings,\n    trajectory,\n    modelCalls,\n    toolCalls,\n    runtime: {\n      engine: ENGINE_ID,\n      model: options.model,\n      transport: options.chat.transport,\n      report_format: options.reportFormat,\n      investigation_turns: turnsUsed,\n      investigation_stopped_on_answer: stoppedOnAnswer,\n      tool_budget_exhausted: toolBudgetExhausted,\n      truncated_tool_results: truncatedToolResults,\n      rejected_findings: parsed.rejectedFindings,\n      // A gateway can answer `model: X` from another model on HTTP 200, so the\n      // ids the provider echoed travel with the result as evidence.\n      served_models: [...servedModels].sort(),\n      task_inputs: request.taskInputs ? 'prompt-delivered' : 'none',\n    },\n  }\n  request.log?.('trace analyst engine completed', {\n    engine: ENGINE_ID,\n    model_calls: result.modelCalls,\n    tool_calls: result.toolCalls,\n    findings: result.findings.length,\n  })\n  return result\n}\n\ninterface ModelTurn {\n  content: string\n  toolCalls?: LlmToolCall[]\n  servedModel?: string | null\n  finishReason?: string | null\n}\n\nasync function callModel(\n  request: TraceAnalysisEngineRequest,\n  options: ResolvedOptions,\n  turn: {\n    messages: LlmMessage[]\n    tools?: LlmToolDefinition[]\n    toolChoice?: LlmCallRequest['toolChoice']\n    purpose: 'investigation' | 'report'\n    json?: 'json-object' | 'json-schema'\n  },\n): Promise<ModelTurn> {\n  const chatRequest: LlmCallRequest = {\n    model: options.model,\n    // The transport may mutate what it is handed; the conversation is ours.\n    messages: turn.messages.map((message) => ({ ...message })),\n    maxTokens: options.maxOutputTokens,\n    ...(turn.tools && turn.tools.length > 0\n      ? { tools: turn.tools, ...(turn.toolChoice ? { toolChoice: turn.toolChoice } : {}) }\n      : {}),\n    ...(turn.json ? { jsonMode: true } : {}),\n    ...(turn.json === 'json-schema' ? { jsonSchema: REPORT_JSON_SCHEMA } : {}),\n    ...(options.temperature === undefined ? {} : { temperature: options.temperature }),\n    ...(options.thinking === undefined ? {} : { thinking: options.thinking }),\n    ...(options.requestTimeoutMs === undefined ? {} : { timeoutMs: options.requestTimeoutMs }),\n  }\n  const paid = await paidChat({\n    chat: options.chat,\n    request: chatRequest,\n    ledger: request.costLedger,\n    channel: 'analyst',\n    phase: request.costPhase,\n    actor: request.analystId,\n    ...(request.costTags ? { tags: request.costTags } : {}),\n    ...(options.pricing ? { pricing: options.pricing } : {}),\n    ...(request.signal ? { signal: request.signal } : {}),\n  })\n  if (!paid.succeeded) {\n    // The transport already spent its own attempts. A failure here ends the\n    // investigation: continuing would report an answer the model never gave.\n    throw new Error(\n      `chat trace engine ${turn.purpose} call failed for '${request.analystId}': ${paid.error.message}`,\n      { cause: paid.error },\n    )\n  }\n  return {\n    content: paid.response.content,\n    ...(paid.response.toolCalls ? { toolCalls: paid.response.toolCalls } : {}),\n    ...(paid.response.servedModel === undefined ? {} : { servedModel: paid.response.servedModel }),\n    ...(paid.response.finishReason === undefined\n      ? {}\n      : { finishReason: paid.response.finishReason }),\n  }\n}\n\ninterface ExecutedTool {\n  ok: boolean\n  truncated: boolean\n  payload: string\n}\n\nasync function executeTool(\n  call: LlmToolCall,\n  toolsByName: ReadonlyMap<string, TraceAnalysisToolDescriptor>,\n  request: TraceAnalysisEngineRequest,\n): Promise<ExecutedTool> {\n  const descriptor = toolsByName.get(call.name)\n  if (!descriptor) {\n    return {\n      ok: false,\n      truncated: false,\n      payload: toolError(\n        `unknown tool '${call.name}'; available tools are ${[...toolsByName.keys()].sort().join(', ')}`,\n      ),\n    }\n  }\n  let args: unknown\n  try {\n    args = call.argumentsJson.trim() === '' ? {} : JSON.parse(call.argumentsJson)\n  } catch (error) {\n    return {\n      ok: false,\n      truncated: false,\n      payload: toolError(\n        `arguments for '${call.name}' were not JSON: ${messageOf(error)}. Send valid JSON arguments.`,\n      ),\n    }\n  }\n  try {\n    const value = await descriptor.handler(\n      args,\n      request.signal ? { signal: request.signal } : undefined,\n    )\n    return truncateToolPayload(JSON.stringify(value ?? null), request.limits.maxOutputChars)\n  } catch (error) {\n    // A bounded store refuses an oversized or malformed read by design. That\n    // refusal is the model's next instruction, not the run's failure.\n    if (request.signal?.aborted) throw error\n    request.log?.('trace tool failed', {\n      engine: ENGINE_ID,\n      analyst_id: request.analystId,\n      tool: call.name,\n      reason: messageOf(error),\n    })\n    return { ok: false, truncated: false, payload: toolError(messageOf(error)) }\n  }\n}\n\nfunction truncateToolPayload(payload: string, maxOutputChars: number): ExecutedTool {\n  if (payload.length <= maxOutputChars) return { ok: true, truncated: false, payload }\n  const keep = Math.max(0, maxOutputChars - TRUNCATION_MARKER.length)\n  return { ok: true, truncated: true, payload: `${payload.slice(0, keep)}${TRUNCATION_MARKER}` }\n}\n\nfunction toolMessage(call: LlmToolCall, content: string): LlmMessage {\n  return { role: 'tool', toolCallId: call.id, content }\n}\n\nfunction toolError(reason: string): string {\n  return JSON.stringify({ error: reason })\n}\n\nfunction exhaustedToolBudget(maxToolCalls: number): string {\n  return toolError(\n    `the trace-tool budget of ${maxToolCalls} calls is spent; answer from the evidence already read`,\n  )\n}\n\nfunction systemPrompt(request: TraceAnalysisEngineRequest, investigationTurns: number): string {\n  return [\n    request.instructions.trim(),\n    [\n      'HOW THIS INVESTIGATION RUNS:',\n      `- You have ${investigationTurns} investigation turns and at most ${request.limits.maxToolCalls} trace-tool calls.`,\n      '- Call the trace tools to read the store. Never state a trace fact you did not read.',\n      `- A tool result longer than ${request.limits.maxOutputChars} characters is truncated; narrow the query instead of asking again.`,\n      '- A tool result carrying an \"error\" field is feedback: fix the call or take another route.',\n      '- Answer with no tool call once you have the evidence. You are then asked for the final report.',\n    ].join('\\n'),\n  ].join('\\n\\n')\n}\n\nfunction reportPrompt(reportFormat: 'json-object' | 'json-schema'): string {\n  return [\n    'Report now. Do not call any more tools.',\n    'Return one JSON object with exactly two fields:',\n    '  \"answer\": a direct prose answer to the question.',\n    '  \"findings\": an array of findings in the schema above. Emit [] when there is nothing to report.',\n    reportFormat === 'json-object'\n      ? 'Return the object alone, with no surrounding prose and no code fence.'\n      : 'Return the object in the response schema you were given.',\n  ].join('\\n')\n}\n\nfunction renderTaskInputs(taskInputs: Readonly<Record<string, unknown>>): string {\n  // The engine contract forbids dropping structured inputs. This engine has no\n  // code environment to bind them as variables, so they are delivered whole as\n  // conversation material and the runtime record says which way they arrived.\n  return [\n    'TASK INPUTS — structured material delivered with the question, not fetched through tools:',\n    JSON.stringify(taskInputs, null, 2),\n  ].join('\\n')\n}\n\ninterface ParsedReport {\n  answer: string\n  findings: TraceAnalysisEngineResult['findings']\n  rejectedFindings: number\n}\n\nfunction parseReport(\n  content: string,\n  analystId: string,\n  onRejectedFinding: (index: number, reason: string) => void,\n): ParsedReport {\n  const envelope = coerceReportEnvelope(content, analystId)\n  if (typeof envelope.answer !== 'string' || !envelope.answer.trim()) {\n    throw new Error(`chat trace engine report for '${analystId}' carried no answer`)\n  }\n  // Findings are model output: one malformed row is model noise, not an engine\n  // fault, and the rest of the paid investigation must survive it.\n  const decoded = decodeRawFindingArray(envelope.findings)\n  if (decoded.topLevelError !== undefined) {\n    throw new Error(\n      `chat trace engine report for '${analystId}' had a malformed findings array: ${decoded.topLevelError}`,\n    )\n  }\n  for (const rejection of decoded.rejected) {\n    onRejectedFinding(\n      rejection.index,\n      `${rejection.code}${rejection.path ? ` at ${rejection.path}` : ''}: ${rejection.message}`,\n    )\n  }\n  return {\n    answer: envelope.answer,\n    findings: decoded.accepted,\n    rejectedFindings: decoded.rejected.length,\n  }\n}\n\nfunction coerceReportEnvelope(content: string, analystId: string): Record<string, unknown> {\n  let value: unknown\n  try {\n    value = JSON.parse(extractJsonPayload(content))\n  } catch (error) {\n    throw new Error(`chat trace engine report for '${analystId}' was not JSON: ${messageOf(error)}`)\n  }\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new Error(`chat trace engine report for '${analystId}' was not a JSON object`)\n  }\n  return value as Record<string, unknown>\n}\n\nfunction resolveModel(options: ChatTraceEngineOptions): string {\n  const model = options.model ?? options.chat.defaultModel\n  if (typeof model !== 'string' || !model.trim() || model !== model.trim()) {\n    throw new TypeError(\n      'chat trace engine needs a model: pass ChatTraceEngineOptions.model or bind defaultModel on the ChatClient',\n    )\n  }\n  return model\n}\n","/**\n * LockedJsonlAppender — mutex-serialized JSONL append helper for arbitrary\n * payloads. The reference-replay store does the same thing for typed\n * `ReferenceReplayRun` rows; this is the generic version used by\n * `MutationTelemetry`, `TrialTelemetry`, and any other consumer that wants\n * append-only durable telemetry without rolling its own lock.\n *\n * Locks are per absolute file path (process-local). Cross-process\n * concurrency is NOT addressed — that's an fcntl/flock problem.\n */\n\nimport { appendFileSync, existsSync, mkdirSync } from 'node:fs'\nimport { dirname } from 'node:path'\nimport { Mutex } from './concurrency'\n\nconst mutexes = new Map<string, Mutex>()\n\nfunction getMutex(path: string): Mutex {\n  let m = mutexes.get(path)\n  if (!m) {\n    m = new Mutex()\n    mutexes.set(path, m)\n  }\n  return m\n}\n\nexport class LockedJsonlAppender {\n  private readonly mutex: Mutex\n  constructor(public readonly path: string) {\n    this.mutex = getMutex(path)\n    if (!existsSync(dirname(path))) {\n      mkdirSync(dirname(path), { recursive: true })\n    }\n  }\n\n  async append(entry: unknown): Promise<void> {\n    const line = `${JSON.stringify(entry)}\\n`\n    await this.mutex.runExclusive(() => {\n      appendFileSync(this.path, line)\n    })\n  }\n}\n\n/** Reset all internal mutex state — tests only. */\nexport function resetLockedAppendersForTesting(): void {\n  mutexes.clear()\n}\n","/**\n * FindingsStore — durable persistence for AnalystFinding rows + a diff\n * helper so we can answer \"what changed since the last run?\" without\n * recomputing analysts.\n *\n * On-disk shape is JSONL: one finding per line, append-only, locked via\n * LockedJsonlAppender. Operators get crash-safety (no partial JSON),\n * cheap reads (sequential parse), and trivial backup (rsync the file).\n *\n * Reads are non-locking: a reader sees a consistent snapshot of all\n * fully-written lines and skips an incomplete trailing line if the\n * writer is mid-append. Cross-process locking is intentionally out of\n * scope (see locked-jsonl-appender.ts).\n *\n * The store is run-scoped: callers pass `runId` on append and on load,\n * which keeps multi-run files cleanly partitioned. The `diffFindings`\n * helper compares two run-id sets using stable `finding_id` semantics —\n * the diff is the cross-run signal the regression dashboard renders.\n */\n\nimport { existsSync, readFileSync } from 'node:fs'\n\nimport { LockedJsonlAppender } from '../locked-jsonl-appender'\nimport type { AnalystFinding } from './types'\n\n/**\n * One persisted row. We attach `run_id` on disk so a single file can\n * hold multiple runs and the diff helper can query without re-walking\n * separate files.\n */\nexport interface PersistedFinding extends AnalystFinding {\n  run_id: string\n}\n\nexport class FindingsStore {\n  private readonly appender: LockedJsonlAppender\n\n  constructor(public readonly path: string) {\n    this.appender = new LockedJsonlAppender(path)\n  }\n\n  async append(runId: string, findings: AnalystFinding[]): Promise<void> {\n    for (const f of findings) {\n      const row: PersistedFinding = { ...f, run_id: runId }\n      await this.appender.append(row)\n    }\n  }\n\n  /** Load every persisted finding. Discards malformed trailing lines silently. */\n  loadAll(): PersistedFinding[] {\n    if (!existsSync(this.path)) return []\n    const raw = readFileSync(this.path, 'utf8')\n    if (!raw) return []\n    const out: PersistedFinding[] = []\n    for (const line of raw.split('\\n')) {\n      if (!line) continue\n      try {\n        out.push(JSON.parse(line) as PersistedFinding)\n      } catch {\n        // Skip torn trailing line — the lock guarantees no torn lines\n        // mid-file, only at EOF when a writer is in-flight.\n      }\n    }\n    return out\n  }\n\n  /** Filter to a single run. */\n  loadRun(runId: string): PersistedFinding[] {\n    return this.loadAll().filter((r) => r.run_id === runId)\n  }\n}\n\n// ── Cross-run diff ──────────────────────────────────────────────────\n\nexport interface FindingsDiff {\n  /** New finding ids in `current` that weren't in `previous`. */\n  appeared: PersistedFinding[]\n  /** Finding ids in `previous` that aren't in `current`. */\n  disappeared: PersistedFinding[]\n  /** Same finding id present in both runs and unchanged per the materiality test. */\n  persisted: PersistedFinding[]\n  /**\n   * Same finding id in both runs but at least one non-identity field\n   * shifted per `DiffPolicy.isMaterial`. Reported as [previous, current].\n   */\n  changed: Array<{ previous: PersistedFinding; current: PersistedFinding }>\n}\n\nexport interface DiffPolicy {\n  /**\n   * Predicate that decides whether two findings (same finding_id) count\n   * as a material change. Defaults to {@link defaultIsMaterial}: severity\n   * shift, confidence Δ > 0.05, or evidence count change. Compliance /\n   * perf consumers MAY supply a stricter predicate (e.g. rationale text\n   * diff, metric Δ thresholds).\n   */\n  isMaterial?: (previous: AnalystFinding, current: AnalystFinding) => boolean\n}\n\n/**\n * Default materiality test. Deliberately narrow so LLM-reword churn\n * doesn't flood the diff. Stricter tests are opt-in via DiffPolicy.\n */\nfunction defaultIsMaterial(a: AnalystFinding, b: AnalystFinding): boolean {\n  if (a.severity !== b.severity) return true\n  if (Math.abs((a.confidence ?? 0) - (b.confidence ?? 0)) > 0.05) return true\n  if (a.evidence_refs.length !== b.evidence_refs.length) return true\n  return false\n}\n\n/**\n * Diff two findings sets by stable finding_id. Callers typically load\n * the two run-id slices from the same store and pass them in.\n */\nexport function diffFindings(\n  previous: PersistedFinding[],\n  current: PersistedFinding[],\n  policy: DiffPolicy = {},\n): FindingsDiff {\n  const isMaterial = policy.isMaterial ?? defaultIsMaterial\n  const prevById = new Map(previous.map((f) => [f.finding_id, f]))\n  const curById = new Map(current.map((f) => [f.finding_id, f]))\n\n  const appeared: PersistedFinding[] = []\n  const disappeared: PersistedFinding[] = []\n  const persisted: PersistedFinding[] = []\n  const changed: FindingsDiff['changed'] = []\n\n  for (const [id, cur] of curById) {\n    const prev = prevById.get(id)\n    if (!prev) {\n      appeared.push(cur)\n      continue\n    }\n    if (isMaterial(prev, cur)) {\n      changed.push({ previous: prev, current: cur })\n    } else {\n      persisted.push(cur)\n    }\n  }\n  for (const [id, prev] of prevById) {\n    if (!curById.has(id)) disappeared.push(prev)\n  }\n  return { appeared, disappeared, persisted, changed }\n}\n"],"mappings":"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"}

package/dist/fuzz.d.ts

@@ -1,5 +1,5 @@
-import { a as CostChannel, c as CostLedgerHandle, x as MaximumCharge } from "./cost-ledger-CO7UyEcQ.js";
-import { t as DefaultVerdict } from "./verdict-E4eRNf7-.js";
+import { a as CostLedgerHandle, m as MaximumCharge, r as CostChannel } from "./cost-ledger-Jk62OBfF.js";
+import { t as DefaultVerdict } from "./verdict-C24NELtN.js";
 import { t as AdversarialMutation } from "./adversarial-smnADNFS.js";
 //#region src/fuzz/types.d.ts
 /** One input axis of the stratification plan (e.g. matterType, difficulty, personaRigor). */
@@ -39,13 +39,13 @@ interface Evaluation extends DefaultVerdict {
 /** Run the target against one scenario in a cell. */
 type Evaluator<S> = (scenario: S, cell: Cell) => Promise<Evaluation>;
 /** Context a proposer sees — prior elites + findings let a skill-backed proposer steer. */
-interface ProposeContext<S> {
+interface FuzzProposeContext<S> {
   cell: Cell;
   seeds: S[];
   /** Current archive elites whose input cell matches. */
   elites: S[];
   /** Verified findings so far (read-only) — probe new gaps, not re-found ones. */
-  findings: ReadonlyArray<Finding<S>>;
+  findings: ReadonlyArray<FuzzFinding<S>>;
   /** How many candidates to propose. */
   count: number;
   rng: () => number;
@@ -60,13 +60,13 @@ interface ProposeContext<S> {
  * is the scenario generator in the behavior-fuzzing loop. `SurfaceProposer` is
  * THE optimization proposer.
  */
-type MutationProposer<S> = (ctx: ProposeContext<S>) => Promise<S[]> | S[];
+type MutationProposer<S> = (ctx: FuzzProposeContext<S>) => Promise<S[]> | S[];
 /**
  * What "interesting" means. `interest` in [0,1]; a candidate is notable (gate-
  * checked, reported) when `interest >= threshold`. `adversarialObjective` (low
  * score is interesting) and `noveltyObjective` (far from the archive) ship.
  */
-interface Objective {
+interface FuzzObjective {
   kind: string;
   interest(ev: Evaluation, ctx: ObjectiveContext): number;
   /** Default 0.5. */
@@ -87,7 +87,7 @@ interface ValidityGates<S> {
   isUncontaminated?: (scenario: S, ev: Evaluation, cell: Cell) => boolean | Promise<boolean>;
 }
 /** A gate-verified, minimized finding — the unit the capsule reports. */
-interface Finding<S> {
+interface FuzzFinding<S> {
   id: string;
   cell: Cell;
   scenario: S;
@@ -148,7 +148,7 @@ interface CapsuleData<S> {
   generatedAt?: string;
   coverage: CoverageCell[];
   /** Verified findings, sorted by descending interest. */
-  findings: Finding<S>[];
+  findings: FuzzFinding<S>[];
   /** QD archive elites (binned by input × measured coords). */
   archive: ArchiveEntry<S>[];
   /** Post-harden lift, filled by a second pass after an improvement. */
@@ -211,7 +211,7 @@ type ExploreEvent<S> = {
   evaluation: Evaluation;
 } | {
   type: 'finding';
-  finding: Finding<S>;
+  finding: FuzzFinding<S>;
 } | {
   type: 'eval-error';
   cell: Cell;
@@ -240,7 +240,7 @@ interface ExploreOptions<S> {
   /** Measured behavior coords appended to the archive bin. Default: input cell only. */
   descriptor?: (scenario: S, ev: Evaluation) => Record<string, string>;
   /** What "interesting" means. Default: `adversarialObjective(0.5)`. */
-  objective?: Objective;
+  objective?: FuzzObjective;
   /** Validity gates. Default pass-through. */
   gates?: ValidityGates<S>;
   /** Budget steering across input cells. `variance` chases uncertainty; `uniform` is the unsteered ablation baseline. Default `variance`. */
@@ -322,7 +322,7 @@ interface BuildCapsuleInput<S> {
   /** The objective's notable threshold — drives findingRate. */
   threshold: number;
   archive: ArchiveEntry<S>[];
-  findings: Finding<S>[];
+  findings: FuzzFinding<S>[];
   candidateFindings: number;
   runsUsed: number;
   /** Known-dollar / unknown-run split — present only when cost tracking was
@@ -339,7 +339,6 @@ interface BuildCapsuleInput<S> {
     detail: string;
   };
 }
-export declare function buildCapsule<S>(input: BuildCapsuleInput<S>): CapsuleData<S>;
 interface RenderCapsuleOptions {
   /** Max finding exemplars to show. Default 8. */
   maxFindings?: number;
@@ -349,47 +348,6 @@ interface RenderCapsuleOptions {
 /** Render a self-contained HTML capsule — heat-map + per-dimension chips + verified findings. */
 export declare function renderCapsuleHtml<S>(capsule: CapsuleData<S>, opts?: RenderCapsuleOptions): string;
 //#endregion
-//#region src/fuzz/explorer.d.ts
-export declare class BehaviorExplorer<S> {
-  private readonly opts;
-  private readonly cells;
-  private readonly cellById;
-  private readonly objective;
-  private readonly threshold;
-  private readonly floorPerCell;
-  private readonly perRoundBudget;
-  /** The single evaluation log — coverage + allocation are projections of it. */
-  private readonly log;
-  /** binId (input × measured coords) → the most interesting entry seen. */
-  private readonly archiveByBin;
-  private readonly _findings;
-  private runsUsed;
-  private candidateFindings;
-  private evalErrors;
-  private consecutiveEvalErrors;
-  private stoppedEarly;
-  private readonly rng;
-  private readonly costLedger?;
-  private readonly costPhase;
-  constructor(opts: ExploreOptions<S>);
-  private binId;
-  private allocate;
-  private objectiveContext;
-  /** Elites whose INPUT cell matches — what the proposer mutates/deepens from. */
-  private elitesFor;
-  /** One allocate → propose → evaluate → gate → archive round. */
-  step(): Promise<{
-    runs: number;
-    findings: Finding<S>[];
-  }>;
-  /** Loop `step()` until the run or dollar budget is spent, the signal aborts,
-   *  or no progress is made. */
-  run(): Promise<CapsuleData<S>>;
-  coverage(): CoverageCell[];
-  findings(): Finding<S>[];
-  capsule(): CapsuleData<S>;
-}
-//#endregion
 //#region src/fuzz/fuzz-agent.d.ts
 type FuzzAgentOptions<S> = Omit<ExploreOptions<S>, 'objective'> & {
   /** Score strictly below this is a candidate failure. Default 0.5. */
@@ -435,16 +393,16 @@ export declare function mutationProposer<S>(opts: {
   mutationsFor: (cell: Cell) => AdversarialMutation<S>[];
   scenarioId: (s: S) => string;
 }): MutationProposer<S>;
-/** Adversarial: a low headline score is interesting — find where the agent fails. */
-export declare function adversarialObjective(threshold?: number): Objective;
-/**
- * Novelty: interesting when far from the archive in score AND measured behavior
- * descriptor — quality-diversity's diversity pressure; drives corpus growth
- * rather than re-finding the same hole.
- */
-export declare function noveltyObjective(threshold?: number): Objective;
 //#endregion
 //#region src/fuzz/tools.d.ts
+/**
+ * Agent-drivable surface over a live exploration session.
+ *
+ * Framework-neutral tool defs ({name, description, parameters: JSON Schema,
+ * handler}) so the on-demand agent — not a batch script — drives the search:
+ * step it, read coverage, inspect findings, render the capsule. Transport
+ * encodings (OpenAI function shape, MCP) are one-line mappings the host owns.
+ */
 interface ExploreToolDef {
   name: string;
   description: string;
@@ -454,7 +412,6 @@ interface ExploreToolDef {
     signal?: AbortSignal;
   }) => Promise<unknown>;
 }
-export declare function makeExploreTools<S>(explorer: BehaviorExplorer<S>): ExploreToolDef[];
 //#endregion
-export type { ArchiveEntry, BehaviorSpace, BuildCapsuleInput, CapsuleData, Cell, CoverageCell, EvalRecord, Evaluation, Evaluator, ExploreEvent, ExploreOptions, ExploreToolDef, Finding, FuzzAgentOptions, MutationProposer, Objective, ObjectiveContext, ProposeContext, RenderCapsuleOptions, RunCost, SpaceAxis, ValidityGates };
+export type { ArchiveEntry, BehaviorSpace, BuildCapsuleInput, CapsuleData, Cell, CoverageCell, EvalRecord, Evaluation, Evaluator, ExploreEvent, ExploreOptions, ExploreToolDef, FuzzAgentOptions, FuzzFinding, FuzzObjective, FuzzProposeContext, MutationProposer, ObjectiveContext, RenderCapsuleOptions, RunCost, SpaceAxis, ValidityGates };
 //# sourceMappingURL=fuzz.d.ts.map

package/dist/fuzz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fuzz.d.ts","names":[],"sources":["../src/fuzz/types.ts","../src/fuzz/cube.ts","../src/fuzz/capsule.ts","../src/fuzz/explorer.ts","../src/fuzz/fuzz-agent.ts","../src/fuzz/gates.ts","../src/fuzz/policies.ts","../src/fuzz/tools.ts"],"mappings":"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"}
+{"version":3,"file":"fuzz.d.ts","names":[],"sources":["../src/fuzz/types.ts","../src/fuzz/cube.ts","../src/fuzz/capsule.ts","../src/fuzz/fuzz-agent.ts","../src/fuzz/gates.ts","../src/fuzz/policies.ts","../src/fuzz/tools.ts"],"mappings":"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"}

package/dist/fuzz.js

@@ -1,7 +1,6 @@
-import { s as ValidationError } from "./errors-Dngq5h35.js";
-import { t as mulberry32 } from "./random-Dn5fPWkt.js";
-import { i as CostLedger, o as CostReceiptCaptureError } from "./cost-ledger-D2FnJPBF.js";
-import { t as varianceBasedCurriculum } from "./active-curriculum-B_Lc9kfO.js";
+import { s as ValidationError } from "./errors-BcOs5MKW.js";
+import { t as mulberry32 } from "./random-DDDcC7YU.js";
+import { o as CostReceiptCaptureError, t as CostLedger } from "./cost-ledger-D0352Z4d.js";
 //#region src/fuzz/cube.ts
 /** Enumerate every input cell (cartesian product of the axes), in stable order. */
 function enumerateCells(space) {
@@ -260,6 +259,64 @@ ${findingsHtml(capsule.findings, opts.maxFindings ?? 8)}
 </div></body></html>`;
 }
 //#endregion
+//#region src/rl/active-curriculum.ts
+/**
+* Variance-proportional allocation. For each cell, estimate variance from
+* past observations + a prior, then allocate the budget proportional to
+* (sqrt(variance) + 1/sqrt(n)) — a classical optimal-allocation rule
+* (Neyman 1934) that balances "explore noisy cells" with "explore
+* under-sampled cells."
+*/
+function varianceBasedCurriculum(observations, candidateCells, opts) {
+	const variancePrior = opts.variancePrior ?? .05;
+	const floor = opts.floorPerCell ?? 1;
+	const budget = opts.budget;
+	const grouped = /* @__PURE__ */ new Map();
+	for (const o of observations) {
+		const k = `${o.variantId}::${o.scenarioId}`;
+		const arr = grouped.get(k) ?? [];
+		arr.push(o.score);
+		grouped.set(k, arr);
+	}
+	const cellStats = candidateCells.map((c) => {
+		const k = `${c.variantId}::${c.scenarioId}`;
+		const samples = grouped.get(k) ?? [];
+		const n = samples.length;
+		const mean = n === 0 ? .5 : samples.reduce((s, v) => s + v, 0) / n;
+		const variance = n < 2 ? variancePrior : samples.reduce((s, v) => s + (v - mean) ** 2, 0) / (n - 1) + variancePrior;
+		const weight = Math.sqrt(variance) + 1 / Math.sqrt(Math.max(1, n));
+		return {
+			variantId: c.variantId,
+			scenarioId: c.scenarioId,
+			n,
+			mean,
+			variance,
+			weight
+		};
+	});
+	const floorTotal = floor * cellStats.length;
+	if (floorTotal >= budget) {
+		const each = Math.max(1, Math.floor(budget / Math.max(1, cellStats.length)));
+		return cellStats.map((c) => ({
+			variantId: c.variantId,
+			scenarioId: c.scenarioId,
+			count: each,
+			reason: `floor allocation (budget tight; n=${c.n})`
+		}));
+	}
+	const remaining = budget - floorTotal;
+	const totalWeight = cellStats.reduce((s, c) => s + c.weight, 0);
+	return cellStats.map((c) => {
+		const proportional = totalWeight === 0 ? 0 : Math.round(c.weight / totalWeight * remaining);
+		return {
+			variantId: c.variantId,
+			scenarioId: c.scenarioId,
+			count: floor + proportional,
+			reason: `variance ${c.variance.toFixed(3)} (n=${c.n}, mean=${c.mean.toFixed(3)})`
+		};
+	});
+}
+//#endregion
 //#region src/fuzz/policies.ts
 const clamp01 = (x) => Math.max(0, Math.min(1, x));
 /**
@@ -298,30 +355,6 @@ function adversarialObjective(threshold = .5) {
 		interest: (ev) => clamp01(1 - ev.score)
 	};
 }
-function hamming(a, b) {
-	if (!a || !b) return 1;
-	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
-	if (keys.size === 0) return 0;
-	let diff = 0;
-	for (const k of keys) if (a[k] !== b[k]) diff++;
-	return diff / keys.size;
-}
-/**
-* Novelty: interesting when far from the archive in score AND measured behavior
-* descriptor — quality-diversity's diversity pressure; drives corpus growth
-* rather than re-finding the same hole.
-*/
-function noveltyObjective(threshold = .3) {
-	return {
-		kind: "novelty",
-		threshold,
-		interest: (ev, ctx) => {
-			const scoreNovelty = ctx.archiveScores.length === 0 ? 1 : Math.min(...ctx.archiveScores.map((s) => Math.abs(s - ev.score)));
-			const descNovelty = ctx.archiveDescriptors.length === 0 ? 1 : Math.min(...ctx.archiveDescriptors.map((d) => hamming(d, ev.descriptor)));
-			return clamp01(.5 * scoreNovelty + .5 * descNovelty);
-		}
-	};
-}
 //#endregion
 //#region src/fuzz/explorer.ts
 /**
@@ -677,85 +710,6 @@ function severityFloorGate(opts) {
 	return { isValid: (_scenario, ev) => ev.score <= threshold - margin };
 }
 //#endregion
-//#region src/fuzz/tools.ts
-/**
-* Agent-drivable surface over a live exploration session.
-*
-* Framework-neutral tool defs ({name, description, parameters: JSON Schema,
-* handler}) so the on-demand agent — not a batch script — drives the search:
-* step it, read coverage, inspect findings, render the capsule. Transport
-* encodings (OpenAI function shape, MCP) are one-line mappings the host owns.
-*/
-const NO_ARGS = {
-	type: "object",
-	properties: {},
-	additionalProperties: false
-};
-function makeExploreTools(explorer) {
-	return [
-		{
-			name: "explore_step",
-			description: "Run one exploration round: allocate budget across cells, propose + evaluate scenarios, archive elites, admit gate-verified findings. Returns runs spent and new findings.",
-			parameters: NO_ARGS,
-			handler: async () => {
-				const { runs, findings } = await explorer.step();
-				return {
-					runs,
-					newFindings: findings.length,
-					findings
-				};
-			}
-		},
-		{
-			name: "explore_coverage",
-			description: "Read the live coverage map: per planned cell — runs, robustness (null = uncovered), finding rate, per-dimension means.",
-			parameters: NO_ARGS,
-			handler: async () => explorer.coverage()
-		},
-		{
-			name: "explore_findings",
-			description: "List gate-verified findings so far, sorted by descending interest.",
-			parameters: {
-				type: "object",
-				properties: { limit: {
-					type: "number",
-					description: "max findings to return"
-				} },
-				additionalProperties: false
-			},
-			handler: async (args) => {
-				const limit = args?.limit;
-				const all = explorer.findings();
-				return typeof limit === "number" ? all.slice(0, limit) : all;
-			}
-		},
-		{
-			name: "explore_capsule",
-			description: "Build the capsule artifact from the current session state. format \"data\" returns the structured CapsuleData; \"html\" returns the standalone page.",
-			parameters: {
-				type: "object",
-				properties: {
-					format: {
-						type: "string",
-						enum: ["data", "html"]
-					},
-					generatedAt: {
-						type: "string",
-						description: "ISO timestamp to stamp into the page"
-					}
-				},
-				additionalProperties: false
-			},
-			handler: async (args) => {
-				const a = args ?? {};
-				const capsule = explorer.capsule();
-				if (a.format === "html") return renderCapsuleHtml(capsule, { generatedAt: a.generatedAt });
-				return capsule;
-			}
-		}
-	];
-}
-//#endregion
-export { BehaviorExplorer, adversarialObjective, buildCapsule, buildCoverage, cellId, composeGates, enumerateCells, fuzzAgent, makeExploreTools, mutationProposer, noveltyObjective, perturbationStabilityGate, renderCapsuleHtml, severityFloorGate };
+export { buildCoverage, cellId, composeGates, enumerateCells, fuzzAgent, mutationProposer, perturbationStabilityGate, renderCapsuleHtml, severityFloorGate };
 
 //# sourceMappingURL=fuzz.js.map