@tangle-network/agent-runtime 0.69.0 → 0.70.0

package/dist/{worktree-fanout-DUiKPApb.d.ts → worktree-fanout-gNfl0Byj.d.ts}

@@ -1,10 +1,8 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { h as AgentSpec, E as ExecutorRegistry, B as Budget, A as Agent, i as SpawnJournal, g as ResultBlobStore, j as RootHandle, k as SupervisedResult, N as NodeId, l as Settled, m as Spend, S as Scope, n as Executor, G as GitRunner } from './delegates-CLFNAKyi.js';
-import { I as Iteration } from './types-Crxftafi.js';
+import { h as AgentSpec, E as ExecutorRegistry, B as Budget, A as Agent, i as SpawnJournal, g as ResultBlobStore, j as RootHandle, k as SupervisedResult, N as NodeId, l as Settled, m as Spend, S as Scope, n as Executor, L as LocalHarness, G as GitRunner, r as runLocalHarness } from './delegates-DqAgo32T.js';
+import { b as RuntimeHooks, I as Iteration } from './types-BYa2ZOAx.js';
 import { BackendType } from '@tangle-network/sandbox';
-import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-import { L as LocalHarness, r as runLocalHarness } from './local-harness-BE_h8szs.js';
 
 /**
  * @experimental
@@ -787,6 +785,12 @@ type EqualKOnCost = (arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptio
  * fail-closed (not delivered), never a crash.
  */
 
+/**
+ * The deployable completion oracle passed to {@link gateOnDeliverable}: a `check` that
+ * decides DELIVERED (settles `valid` ⟺ it resolves true) plus an optional `describe` of
+ * what the spawn was supposed to produce. The check reads the child's output — never the
+ * model judging itself.
+ */
 interface DeliverableSpec<Out = unknown> {
     /** The deployable check that decides DELIVERED. `settled.valid ⟺ this resolves true`. */
     check: (out: Out) => boolean | Promise<boolean>;
@@ -813,15 +817,6 @@ declare function gateOnDeliverable<Out>(inner: Executor<Out>, deliverable: Deliv
  * (`isNonEmptyPatch` / `touchesSecretPath`) for reuse outside the full scorer.
  */
 
-/** @experimental The patch + its derived PASS signals the mechanical gate decides on. */
-interface CoderCheckInput {
-    /** The unified diff produced by the run. */
-    patch: string;
-    /** Did `testCmd` exit clean? */
-    testsPassed: boolean;
-    /** Did `typecheckCmd` exit clean? */
-    typecheckPassed: boolean;
-}
 /** @experimental The per-task constraints the mechanical gate enforces. */
 interface CoderCheckConstraints {
     /** Default 400. Hard cap; gate fails when exceeded. */
@@ -829,29 +824,6 @@ interface CoderCheckConstraints {
     /** Literal path prefixes the patch must not touch. */
     forbiddenPaths?: string[];
 }
-/** The unified-diff paths the patch touches — the `+++`/`---` headers, de-`a/`/`b/`-prefixed,
- *  with `/dev/null` (a delete's other side) dropped. */
-declare function touchedPathsFromPatch(patch: string): string[];
-/** Count the added/removed content lines in a unified diff (excludes the `+++`/`---` headers). */
-declare function countDiffLines(patch: string): number;
-/** True when the patch actually changes something — at least one touched path AND non-blank body.
- *  An empty patch can trivially "pass" tests/typecheck (nothing changed) yet does no work. */
-declare function isNonEmptyPatch(patch: string): boolean;
-/** The credential-shaped paths the patch touches (always-on floor, independent of `forbiddenPaths`). */
-declare function touchesSecretPath(patch: string): string[];
-/**
- * @experimental
- *
- * The pure mechanical gate — the SINGLE source of the no-op / always-on secret-path floor /
- * diff-size / forbidden-path / test / typecheck checks. No I/O: it scores a patch + its
- * already-derived pass signals.
- *
- * Checks in order: (1) no-op rejection, (2) always-on secret-path floor (independent of
- * `forbiddenPaths`), (3) forbidden-path, (4) diff-size cap, (5) tests, (6) typecheck.
- * Aggregate score: `0.5*tests + 0.3*typecheck + 0.2*(1 - diffLines/maxDiff)`; `valid` is the
- * conjunction of all six.
- */
-declare function runCoderChecks(input: CoderCheckInput, constraints?: CoderCheckConstraints): DefaultVerdict;
 
 /**
  * @experimental
@@ -1096,4 +1068,4 @@ interface WorktreeFanoutOptions extends PatchDeliverableOptions {
  */
 declare function worktreeFanout<Task>(options: WorktreeFanoutOptions): CombinatorShape<Task, WorktreePatchArtifact>;
 
-export { type TrajectoryNode as $, type AuthoredHarness as A, type FlatWidenGate as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type LoopUntil as G, type LoopUntilState as H, type Panel as I, type PanelJudge as J, type PanelVerdict as K, type LoopUntilSpec as L, type PatchDeliverableOptions as M, type PersonaContext as N, type Outcome as O, type PanelSpec as P, type PersonaExecutors as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type Pipeline as U, type VerifySpec as V, type WinnerStrategy as W, type RenderCorpusToInstructions as X, type RunPersonified as Y, type ShapeBudget as Z, type ShapeContext as _, type WorktreeFanoutOptions as a, type TrajectoryReportFn as a0, type Verify as a1, type Widen as a2, type WidenDecision as a3, type WidenLineage as a4, type WorktreeCliExecutorOptions as a5, type WorktreeCommandResult as a6, countDiffLines as a7, createWorktreeCliExecutor as a8, gateOnDeliverable as a9, isNonEmptyPatch as aa, patchDelivered as ab, runCoderChecks as ac, touchedPathsFromPatch as ad, touchesSecretPath as ae, worktreeFanout as af, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DeliverableSpec as t, type CoderCheckConstraints as u, type CoderCheckInput as v, type DefinePersona as w, type EqualKOnCost as x, type Fanout as y, type FanoutSynthesis as z };
+export { type Verify as $, type AuthoredHarness as A, type LoopUntilState as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type Panel as G, type PanelJudge as H, type PanelVerdict as I, type PatchDeliverableOptions as J, type PersonaContext as K, type LoopUntilSpec as L, type PersonaExecutors as M, type Pipeline as N, type Outcome as O, type PanelSpec as P, type RenderCorpusToInstructions as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type RunPersonified as U, type VerifySpec as V, type WinnerStrategy as W, type ShapeBudget as X, type ShapeContext as Y, type TrajectoryNode as Z, type TrajectoryReportFn as _, type WorktreeFanoutOptions as a, type Widen as a0, type WidenDecision as a1, type WidenLineage as a2, type WorktreeCliExecutorOptions as a3, type WorktreeCommandResult as a4, createWorktreeCliExecutor as a5, gateOnDeliverable as a6, patchDelivered as a7, worktreeFanout as a8, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DeliverableSpec as t, type DefinePersona as u, type EqualKOnCost as v, type Fanout as w, type FanoutSynthesis as x, type FlatWidenGate as y, type LoopUntil as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -19,21 +19,6 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./platform": {
-      "types": "./dist/platform.d.ts",
-      "import": "./dist/platform.js",
-      "default": "./dist/platform.js"
-    },
-    "./analyst-loop": {
-      "types": "./dist/analyst-loop.d.ts",
-      "import": "./dist/analyst-loop.js",
-      "default": "./dist/analyst-loop.js"
-    },
-    "./improvement": {
-      "types": "./dist/improvement.d.ts",
-      "import": "./dist/improvement.js",
-      "default": "./dist/improvement.js"
-    },
     "./agent": {
       "types": "./dist/agent.d.ts",
       "import": "./dist/agent.js",
@@ -44,36 +29,16 @@
       "import": "./dist/intelligence.js",
       "default": "./dist/intelligence.js"
     },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "import": "./dist/runtime.js",
-      "default": "./dist/runtime.js"
-    },
     "./loops": {
       "types": "./dist/loops.d.ts",
       "import": "./dist/loops.js",
       "default": "./dist/loops.js"
     },
-    "./topology": {
-      "types": "./dist/topology.d.ts",
-      "import": "./dist/topology.js",
-      "default": "./dist/topology.js"
-    },
-    "./workflow": {
-      "types": "./dist/workflow.d.ts",
-      "import": "./dist/workflow.js",
-      "default": "./dist/workflow.js"
-    },
     "./profiles": {
       "types": "./dist/profiles.d.ts",
       "import": "./dist/profiles.js",
       "default": "./dist/profiles.js"
     },
-    "./audit": {
-      "types": "./dist/audit.d.ts",
-      "import": "./dist/audit.js",
-      "default": "./dist/audit.js"
-    },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "import": "./dist/mcp/index.js",
@@ -102,16 +67,21 @@
     "lint:fix": "biome check --write src tests examples",
     "typecheck": "tsc --noEmit && pnpm run typecheck:examples",
     "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
-    "verify:package": "node scripts/verify-package-exports.mjs"
+    "verify:package": "node scripts/verify-package-exports.mjs",
+    "docs:api": "typedoc",
+    "docs:freshness": "node scripts/check-docs-freshness.mjs",
+    "docs:check": "pnpm run docs:api && git diff --exit-code -- docs/api && pnpm run docs:freshness"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": ">=0.93.0 <1.0.0",
+    "@tangle-network/agent-eval": ">=0.95.0 <1.0.0",
     "@tangle-network/agent-interface": ">=0.10.0 <1.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",
     "@types/node": "^25.9.3",
     "playwright": "^1.61.0",
     "tsup": "^8.0.0",
+    "typedoc": "0.28.19",
+    "typedoc-plugin-markdown": "4.12.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
@@ -132,7 +102,7 @@
   "license": "MIT",
   "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.93.0 <1.0.0",
+    "@tangle-network/agent-eval": ">=0.95.0 <1.0.0",
     "@tangle-network/agent-interface": ">=0.10.0 <1.0.0",
     "@tangle-network/agent-knowledge": ">=1.7.0 <2.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",

package/dist/analyst-loop.d.ts

@@ -1,52 +0,0 @@
-import { TraceAnalystByteBudgets, TraceAnalysisStore } from '@tangle-network/agent-eval';
-import { I as Iteration } from './types-Crxftafi.js';
-import { R as RunAnalystLoopOpts, a as RunAnalystLoopResult } from './types-p8dWBIXL.js';
-export { A as AnalystLoopEvent, b as AnalystRegistryLike, c as AnalystRegistryStreamingLike, d as AutoApplyPolicy, F as FindingsStoreLike, I as ImprovementAdapter, e as ImprovementEditBatch, f as ImprovementReport, K as KnowledgeAdapter, g as KnowledgeProposalBatch, h as KnowledgeReport } from './types-p8dWBIXL.js';
-import '@tangle-network/sandbox';
-import './runtime-hooks-C7JwKb9E.js';
-
-/**
- * @experimental
- *
- * The read seam that closes the autonomous loop: project a round's `Iteration[]`
- * (each carrying its raw `SandboxEvent[]`) into an in-memory `TraceAnalysisStore`, the
- * read interface the trace analysts query. `runAnalystLoop` has had zero consumers
- * because nothing turned a loop's iterations into a store — this is that bridge.
- *
- * One iteration → one trace. The iteration is the root AGENT span; each `SandboxEvent`
- * becomes a child span (LLM for llm_call events, TOOL for tool events, else SPAN), so an
- * analyst can walk a shot's trace, cluster its errors, and emit findings the driver
- * steers on. Projection is best-effort over the FLAT SandboxEvent shape (no per-event
- * lineage yet — that's the richer-trace gap); it never fabricates — an errored iteration
- * surfaces a real ERROR span carrying the real message.
- */
-
-/**
- * Build an in-memory `TraceAnalysisStore` over a loop round's iterations. Fail-loud on an
- * empty round — there is nothing for an analyst to read, and a silent empty store would
- * mask a broken capture path.
- */
-declare function iterationsToTraceStore<Task, Output>(iterations: ReadonlyArray<Iteration<Task, Output>>, budgets?: TraceAnalystByteBudgets): TraceAnalysisStore;
-
-/**
- * `runAnalystLoop` — the one call agent apps reach for to close the
- * recursive-self-improvement loop.
- *
- *   1. Load baseline findings (last run, or the slice the caller specifies)
- *   2. Run the analyst registry with priorFindings injected
- *   3. Persist the new run's findings to the ledger
- *   4. Diff the new run against the baseline
- *   5. Hand the findings to the knowledge adapter → proposals (and
- *      optionally apply them) → wiki edits
- *   6. Hand the findings to the improvement adapter → prompt / tool /
- *      scaffolding edits (review-only by default)
- *   7. Return a single report the consumer renders / persists / acts on.
- *
- * Adapters are optional: the loop works as a "run + diff + report"
- * primitive when no adapters are wired; it closes end-to-end when
- * both adapters are wired.
- */
-
-declare function runAnalystLoop<TProposal = unknown, TEdit = unknown>(opts: RunAnalystLoopOpts): Promise<RunAnalystLoopResult<TProposal, TEdit>>;
-
-export { RunAnalystLoopOpts, RunAnalystLoopResult, iterationsToTraceStore, runAnalystLoop };

package/dist/analyst-loop.js

@@ -1,11 +0,0 @@
-import {
-  iterationsToTraceStore,
-  runAnalystLoop
-} from "./chunk-P5OKDSLB.js";
-import "./chunk-VLF5RHEQ.js";
-import "./chunk-DGUM43GV.js";
-export {
-  iterationsToTraceStore,
-  runAnalystLoop
-};
-//# sourceMappingURL=analyst-loop.js.map

package/dist/analyst-loop.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/audit.d.ts

@@ -1,93 +0,0 @@
-import { U as UiFinding, a as UiLens } from './substrate-CUgk7F7s.js';
-
-/**
- * @experimental
- *
- * UI-audit issue writer — pure I/O. Takes a workspace dir + `UiFinding[]`
- * and emits:
- *   - `<workspace>/issues/NNN--<lens>--<slug>.md` — one self-contained
- *     GitHub-issue-ready Markdown per finding, with embedded screenshot
- *     references.
- *   - `<workspace>/registry.json` — finding index for dedup and audit
- *     resume across iterations.
- *   - `<workspace>/index.md` — human-readable rollup (severity / lens /
- *     route counts plus a sorted finding list).
- *
- * The writer is deterministic, idempotent for `appendFindings()`, and
- * never invokes an LLM. It assigns the next monotonic id to a finding the
- * caller did not pre-id.
- */
-
-/** @experimental */
-interface AuditRegistry {
-    schemaVersion: 1;
-    findings: UiFinding[];
-    /** Route → URL + captures sidecar; preserved across runs. */
-    routes: Record<string, {
-        url?: string;
-        captures: AuditRegistryCapture[];
-    }>;
-}
-/** @experimental */
-interface AuditRegistryCapture {
-    file: string;
-    viewport?: string;
-    fullPage?: boolean;
-    elementSelector?: string;
-    capturedAt: string;
-}
-/** @experimental */
-declare function initAuditWorkspace(workspaceDir: string): Promise<void>;
-/** @experimental */
-declare function readAuditRegistry(workspaceDir: string): Promise<AuditRegistry>;
-/** @experimental */
-interface AppendFindingsResult {
-    /** Findings with id + createdAt assigned, in input order. */
-    written: UiFinding[];
-    /** Workspace-relative path to each issue Markdown file, in input order. */
-    files: string[];
-}
-/**
- * Append findings to a workspace, writing one Markdown file per finding
- * and updating registry.json. Assigns monotonically increasing ids to
- * findings that arrived without one.
- *
- * Findings already carrying an id that collides with the registry are
- * rejected — callers must either freshly mint findings (id undefined) or
- * use a separate update path. This protects against accidental overwrite.
- *
- * @experimental
- */
-declare function appendFindings(workspaceDir: string, findings: readonly UiFinding[]): Promise<AppendFindingsResult>;
-/** @experimental */
-interface RegisterCapturesOptions {
-    route: string;
-    url?: string;
-    captures: readonly AuditRegistryCapture[];
-}
-/**
- * Record screenshots taken for a route in the registry, without filing a
- * finding. Useful when the auditor wants to remember which captures
- * exist for resume / dedup purposes.
- *
- * @experimental
- */
-declare function registerCaptures(workspaceDir: string, options: RegisterCapturesOptions): Promise<void>;
-/** @experimental */
-interface AuditIndex {
-    /** Total findings in the workspace. */
-    total: number;
-    bySeverity: Record<UiFinding['severity'], number>;
-    byLens: Partial<Record<UiLens, number>>;
-    byRoute: Record<string, number>;
-}
-/** @experimental */
-declare function summarizeRegistry(reg: AuditRegistry): AuditIndex;
-/**
- * Regenerate `<workspace>/index.md` from registry.json.
- *
- * @experimental
- */
-declare function writeAuditIndex(workspaceDir: string): Promise<string>;
-
-export { type AppendFindingsResult, type AuditIndex, type AuditRegistry, type AuditRegistryCapture, type RegisterCapturesOptions, appendFindings, initAuditWorkspace, readAuditRegistry, registerCaptures, summarizeRegistry, writeAuditIndex };

package/dist/audit.js

@@ -1,312 +0,0 @@
-import {
-  slugify
-} from "./chunk-4B6U4CVQ.js";
-import {
-  UI_FINDING_SEVERITIES,
-  UI_LENSES
-} from "./chunk-WIR4HOOJ.js";
-import "./chunk-DGUM43GV.js";
-
-// src/audit/issue-writer.ts
-import { promises as fs } from "fs";
-import path from "path";
-var SEVERITY_ORDER = {
-  critical: 0,
-  high: 1,
-  med: 2,
-  low: 3
-};
-function assertValidWorkspaceDir(dir) {
-  if (typeof dir !== "string" || dir.length === 0) {
-    throw new Error(
-      `audit-writer: workspaceDir must be a non-empty string (got ${JSON.stringify(dir)})`
-    );
-  }
-  if (!path.isAbsolute(dir)) {
-    throw new Error(
-      `audit-writer: workspaceDir must be an absolute path (got ${JSON.stringify(dir)})`
-    );
-  }
-  if (dir.split(path.sep).includes("..")) {
-    throw new Error(
-      `audit-writer: workspaceDir must not contain '..' segments (got ${JSON.stringify(dir)})`
-    );
-  }
-}
-async function initAuditWorkspace(workspaceDir) {
-  assertValidWorkspaceDir(workspaceDir);
-  await fs.mkdir(path.join(workspaceDir, "issues"), { recursive: true });
-  await fs.mkdir(path.join(workspaceDir, "screenshots"), { recursive: true });
-  const regPath = path.join(workspaceDir, "registry.json");
-  try {
-    await fs.access(regPath);
-  } catch {
-    const fresh = { schemaVersion: 1, findings: [], routes: {} };
-    await fs.writeFile(regPath, JSON.stringify(fresh, null, 2));
-  }
-}
-async function readAuditRegistry(workspaceDir) {
-  assertValidWorkspaceDir(workspaceDir);
-  const regPath = path.join(workspaceDir, "registry.json");
-  const text = await fs.readFile(regPath, "utf8");
-  const parsed = JSON.parse(text);
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error(`audit-writer: registry.json at ${regPath} is not a JSON object`);
-  }
-  const reg = parsed;
-  if (reg.schemaVersion !== 1 || !Array.isArray(reg.findings) || typeof reg.routes !== "object") {
-    throw new Error(`audit-writer: registry.json at ${regPath} has an unrecognized shape`);
-  }
-  return reg;
-}
-async function writeAuditRegistry(workspaceDir, reg) {
-  const regPath = path.join(workspaceDir, "registry.json");
-  const tmpPath = `${regPath}.tmp-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  await fs.writeFile(tmpPath, JSON.stringify(reg, null, 2));
-  await fs.rename(tmpPath, regPath);
-}
-var workspaceLocks = /* @__PURE__ */ new Map();
-async function withWorkspaceLock(workspaceDir, fn) {
-  const key = path.resolve(workspaceDir);
-  const prev = workspaceLocks.get(key) ?? Promise.resolve();
-  let signalDone;
-  const done = new Promise((resolve) => {
-    signalDone = resolve;
-  });
-  workspaceLocks.set(key, done);
-  try {
-    await prev;
-    return await fn();
-  } finally {
-    signalDone();
-    if (workspaceLocks.get(key) === done) workspaceLocks.delete(key);
-  }
-}
-function assertFindingShape(f, index) {
-  const where = `audit-writer: findings[${index}]`;
-  if (!UI_LENSES.includes(f.lens)) {
-    throw new Error(
-      `${where}: invalid lens ${JSON.stringify(f.lens)}; one of ${UI_LENSES.join("|")}`
-    );
-  }
-  if (!UI_FINDING_SEVERITIES.includes(f.severity)) {
-    throw new Error(
-      `${where}: invalid severity ${JSON.stringify(f.severity)}; one of ${UI_FINDING_SEVERITIES.join("|")}`
-    );
-  }
-  for (const field of ["title", "route", "observation", "impact", "suggestedFix"]) {
-    const v = f[field];
-    if (typeof v !== "string" || v.trim().length === 0) {
-      throw new Error(`${where}: ${field} must be a non-empty string`);
-    }
-  }
-  if (!Array.isArray(f.screenshots) || f.screenshots.length === 0) {
-    throw new Error(`${where}: screenshots must be a non-empty array`);
-  }
-  for (let i = 0; i < f.screenshots.length; i += 1) {
-    const s = f.screenshots[i];
-    if (!s || typeof s.path !== "string" || s.path.length === 0) {
-      throw new Error(`${where}.screenshots[${i}].path must be a non-empty string`);
-    }
-    if (s.path.split(/[/\\]/).includes("..")) {
-      throw new Error(`${where}.screenshots[${i}].path must not contain '..' segments`);
-    }
-  }
-}
-function nextFindingId(reg) {
-  let max = 0;
-  for (const f of reg.findings) {
-    if (typeof f.id === "number" && f.id > max) max = f.id;
-  }
-  return max + 1;
-}
-function slugifyTitle(title) {
-  return slugify(title, "title");
-}
-function renderFinding(finding) {
-  if (!finding.id) {
-    throw new Error("audit-writer: cannot render a finding without an assigned id");
-  }
-  if (finding.screenshots.length === 0) {
-    throw new Error(`audit-writer: finding #${finding.id} has no screenshots`);
-  }
-  const id = finding.id;
-  const numStr = String(id).padStart(3, "0");
-  const metaLines = [
-    `> **Issue #${numStr}** \xB7 **Severity:** ${finding.severity} \xB7 **Lens:** ${finding.lens}`,
-    `> **Route:** \`${finding.route}\`${finding.url ? ` \xB7 **URL:** ${finding.url}` : ""}`
-  ];
-  if (finding.viewport) metaLines.push(`> **Viewport:** ${finding.viewport}`);
-  if (finding.selector) metaLines.push(`> **Selector:** \`${finding.selector}\``);
-  if (finding.tags && finding.tags.length > 0) {
-    metaLines.push(`> **Tags:** ${finding.tags.map((t) => `\`${t}\``).join(", ")}`);
-  }
-  if (finding.similarTo && finding.similarTo.length > 0) {
-    metaLines.push(
-      `> **Possible duplicates:** ${finding.similarTo.map((n) => `#${String(n).padStart(3, "0")}`).join(", ")}`
-    );
-  }
-  metaLines.push(`> _Generated: ${finding.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}_`);
-  const reproSteps = finding.reproSteps ?? `1. Open \`${finding.route}\`${finding.url ? ` (${finding.url})` : ""}
-2. Observe the area shown in the screenshot${finding.selector ? ` (selector: \`${finding.selector}\`)` : ""}.`;
-  const evidence = finding.screenshots.map((s) => `![${path.basename(s.path)}](../${s.path})`).join("\n\n");
-  return [
-    `# [UI] ${finding.title}`,
-    "",
-    metaLines.join("\n"),
-    "",
-    "## Observation",
-    finding.observation.trim(),
-    "",
-    "## Why it matters",
-    finding.impact.trim(),
-    "",
-    "## Steps to reproduce",
-    reproSteps,
-    "",
-    "## Suggested fix",
-    finding.suggestedFix.trim(),
-    "",
-    "## Evidence",
-    evidence,
-    "",
-    "---",
-    `<sub>Generated by agent-runtime/ui-auditor \xB7 lens=\`${finding.lens}\` \xB7 severity=\`${finding.severity}\`</sub>`,
-    ""
-  ].join("\n");
-}
-async function appendFindings(workspaceDir, findings) {
-  assertValidWorkspaceDir(workspaceDir);
-  for (let i = 0; i < findings.length; i += 1) {
-    const f = findings[i];
-    if (!f) throw new Error(`audit-writer: findings[${i}] is undefined`);
-    assertFindingShape(f, i);
-  }
-  return withWorkspaceLock(workspaceDir, async () => {
-    await initAuditWorkspace(workspaceDir);
-    const reg = await readAuditRegistry(workspaceDir);
-    const usedIds = /* @__PURE__ */ new Set();
-    for (const f of reg.findings) {
-      if (typeof f.id === "number") usedIds.add(f.id);
-    }
-    const written = [];
-    const files = [];
-    let nextId = nextFindingId(reg);
-    for (const incoming of findings) {
-      let id = incoming.id;
-      if (id !== void 0) {
-        if (usedIds.has(id)) {
-          throw new Error(
-            `audit-writer: incoming finding id ${id} (title=${JSON.stringify(incoming.title)}) collides with an existing registry entry`
-          );
-        }
-      } else {
-        id = nextId;
-        while (usedIds.has(id)) id += 1;
-        nextId = id + 1;
-      }
-      usedIds.add(id);
-      const createdAt = incoming.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
-      const persisted = { ...incoming, id, createdAt };
-      const slug = slugifyTitle(persisted.title);
-      const fileName = `${String(id).padStart(3, "0")}--${persisted.lens}--${slug}.md`;
-      const filePathAbs = path.join(workspaceDir, "issues", fileName);
-      const filePathRel = `issues/${fileName}`;
-      await fs.writeFile(filePathAbs, renderFinding(persisted));
-      reg.findings.push(persisted);
-      written.push(persisted);
-      files.push(filePathRel);
-    }
-    await writeAuditRegistry(workspaceDir, reg);
-    return { written, files };
-  });
-}
-async function registerCaptures(workspaceDir, options) {
-  assertValidWorkspaceDir(workspaceDir);
-  if (typeof options.route !== "string" || options.route.trim().length === 0) {
-    throw new Error("audit-writer: registerCaptures: route must be a non-empty string");
-  }
-  return withWorkspaceLock(workspaceDir, async () => {
-    await initAuditWorkspace(workspaceDir);
-    const reg = await readAuditRegistry(workspaceDir);
-    const slot = reg.routes[options.route] ?? { captures: [] };
-    if (options.url) slot.url = options.url;
-    slot.captures = [...slot.captures, ...options.captures];
-    reg.routes[options.route] = slot;
-    await writeAuditRegistry(workspaceDir, reg);
-  });
-}
-function summarizeRegistry(reg) {
-  const bySeverity = {
-    critical: 0,
-    high: 0,
-    med: 0,
-    low: 0
-  };
-  const byLens = {};
-  const byRoute = {};
-  for (const f of reg.findings) {
-    bySeverity[f.severity] += 1;
-    byLens[f.lens] = (byLens[f.lens] ?? 0) + 1;
-    byRoute[f.route] = (byRoute[f.route] ?? 0) + 1;
-  }
-  return { total: reg.findings.length, bySeverity, byLens, byRoute };
-}
-async function writeAuditIndex(workspaceDir) {
-  assertValidWorkspaceDir(workspaceDir);
-  const reg = await readAuditRegistry(workspaceDir);
-  const summary = summarizeRegistry(reg);
-  const sorted = [...reg.findings].sort((a, b) => {
-    const sa = SEVERITY_ORDER[a.severity];
-    const sb = SEVERITY_ORDER[b.severity];
-    if (sa !== sb) return sa - sb;
-    return (a.id ?? 0) - (b.id ?? 0);
-  });
-  const lines = [];
-  lines.push("# UI audit index", "");
-  lines.push(`_Generated: ${(/* @__PURE__ */ new Date()).toISOString()}_`, "");
-  lines.push(`**Total findings:** ${summary.total}`, "");
-  lines.push("## By severity");
-  for (const s of ["critical", "high", "med", "low"]) {
-    const n = summary.bySeverity[s] ?? 0;
-    if (n > 0) lines.push(`- **${s}** \u2014 ${n}`);
-  }
-  lines.push("", "## By lens");
-  const lensEntries = Object.entries(summary.byLens).map(([k, v]) => [
-    k,
-    v ?? 0
-  ]);
-  for (const [lens, n] of lensEntries.sort((a, b) => b[1] - a[1])) {
-    lines.push(`- **${lens}** \u2014 ${n}`);
-  }
-  lines.push("", "## By route");
-  const routeEntries = Object.entries(summary.byRoute).map(([k, v]) => [
-    k,
-    v ?? 0
-  ]);
-  for (const [route, n] of routeEntries.sort((a, b) => b[1] - a[1])) {
-    lines.push(`- \`${route}\` \u2014 ${n}`);
-  }
-  lines.push("", "## Findings", "");
-  for (const f of sorted) {
-    if (typeof f.id !== "number") continue;
-    const num = String(f.id).padStart(3, "0");
-    const slug = slugifyTitle(f.title);
-    const file = `issues/${num}--${f.lens}--${slug}.md`;
-    lines.push(`- [#${num} \`${f.severity}\` \`${f.lens}\` \`${f.route}\` \u2014 ${f.title}](${file})`);
-  }
-  lines.push("");
-  const out = path.join(workspaceDir, "index.md");
-  const body = lines.join("\n");
-  await fs.writeFile(out, body);
-  return out;
-}
-export {
-  appendFindings,
-  initAuditWorkspace,
-  readAuditRegistry,
-  registerCaptures,
-  summarizeRegistry,
-  writeAuditIndex
-};
-//# sourceMappingURL=audit.js.map