@agenr/agenr-plugin 2.0.0 → 2.1.0

package/dist/chunk-MJIB6J5S.js

@@ -0,0 +1,3059 @@
+import {
+  composeProcedureRecallText,
+  computeProcedureRevisionHash,
+  computeProcedureSourceHash
+} from "./chunk-ZYADFKX3.js";
+import {
+  BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K,
+  BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K,
+  RECALL_DEBUG_ARTIFACT_DEFAULT_TOP_K,
+  RECALL_DEBUG_ARTIFACT_MAX_TOP_K,
+  formatAgenrBeforeTurnRecall,
+  runBeforeTurn
+} from "./chunk-IMQIJPIP.js";
+import {
+  CLAIM_KEY_SOURCES,
+  CLAIM_KEY_STATUSES,
+  CLAIM_SUPPORT_MODES,
+  ENTRY_TYPES,
+  EXPIRY_LEVELS,
+  attachCrossEncoderPort,
+  composeEmbeddingText,
+  createDatabase,
+  createEmbeddingClient,
+  createOpenAICrossEncoder,
+  createRecallAdapter,
+  isRecord,
+  normalizeProcedureDefinition,
+  parseOptionalBoolean,
+  parseOptionalIntegerInRange,
+  parseOptionalTimestampString,
+  parseOptionalTrimmedString,
+  parseRequiredTrimmedString,
+  projectClaimCentricRecallEntry,
+  pushIssue,
+  pushUnexpectedFields,
+  readConfig,
+  resolveCrossEncoderApiKey,
+  resolveEmbeddingApiKey,
+  resolveEmbeddingModel,
+  resolveModel,
+  runUnifiedRecall
+} from "./chunk-7TDALVPY.js";
+import {
+  recall
+} from "./chunk-6T5RXGIR.js";
+
+// src/internal-eval-server.ts
+import process from "process";
+
+// src/adapters/api/internal-eval-server.ts
+import { createServer } from "http";
+
+// src/app/evals/recall/provision-fixtures.ts
+import { createHash } from "crypto";
+var DEFAULT_IMPORTANCE = 6;
+var DEFAULT_EXPIRY = "permanent";
+var DEFAULT_QUALITY_SCORE = 0.5;
+async function provisionRecallEvalFixtures(params) {
+  const preparedBatch = prepareFixtures(params.caseId, params.memoryPool, params.provisionedAt);
+  if (preparedBatch.insertionOrder.length === 0) {
+    return {
+      provisionedCount: 0,
+      providedIdCount: 0,
+      generatedIdCount: 0,
+      retiredCount: 0,
+      supersededCount: 0,
+      createdAtDefaultedCount: 0,
+      updatedAtDefaultedCount: 0,
+      seededEntries: []
+    };
+  }
+  const embeddings = await params.embedding.embed(preparedBatch.insertionOrder.map((fixture) => fixture.embeddingText));
+  if (embeddings.length !== preparedBatch.insertionOrder.length) {
+    throw new Error(`Fixture embedding count mismatch: expected ${preparedBatch.insertionOrder.length}, received ${embeddings.length}.`);
+  }
+  await params.store.withTransaction(async (store) => {
+    for (const [index, fixture] of preparedBatch.insertionOrder.entries()) {
+      await store.insertEntry(fixture.entry, embeddings[index] ?? [], fixture.contentHash);
+    }
+  });
+  return {
+    provisionedCount: preparedBatch.insertionOrder.length,
+    providedIdCount: preparedBatch.providedIdCount,
+    generatedIdCount: preparedBatch.generatedIdCount,
+    retiredCount: preparedBatch.retiredCount,
+    supersededCount: preparedBatch.supersededCount,
+    createdAtDefaultedCount: preparedBatch.createdAtDefaultedCount,
+    updatedAtDefaultedCount: preparedBatch.updatedAtDefaultedCount,
+    seededEntries: preparedBatch.seededEntries
+  };
+}
+function prepareFixtures(caseId, fixtures, provisionedAt) {
+  const resolvedIds = fixtures.map((fixture, index) => fixture.id ?? createFixtureId(caseId, index, fixture));
+  const duplicateIds = findDuplicateIds(resolvedIds);
+  if (duplicateIds.length > 0) {
+    throw new Error(`Fixture IDs must be unique. Duplicate IDs: ${duplicateIds.join(", ")}.`);
+  }
+  const knownIds = new Set(resolvedIds);
+  const prepared = fixtures.map((fixture, index) => {
+    const supersededBy = fixture.superseded_by;
+    if (supersededBy && !knownIds.has(supersededBy)) {
+      throw new Error(`memoryPool[${index}].superseded_by references unknown fixture id "${supersededBy}".`);
+    }
+    const entry = buildEntry(fixture, resolvedIds[index] ?? "", provisionedAt);
+    return {
+      fixtureIndex: index,
+      entry,
+      contentHash: hashText(`${entry.type}
+${entry.subject}
+${entry.content}`),
+      embeddingText: composeEmbeddingText(entry)
+    };
+  });
+  return {
+    insertionOrder: topologicallySortFixtures(prepared),
+    providedIdCount: fixtures.filter((fixture) => fixture.id !== void 0).length,
+    generatedIdCount: fixtures.filter((fixture) => fixture.id === void 0).length,
+    retiredCount: prepared.filter((fixture) => fixture.entry.retired).length,
+    supersededCount: prepared.filter((fixture) => fixture.entry.superseded_by !== void 0).length,
+    createdAtDefaultedCount: fixtures.filter((fixture) => fixture.created_at === void 0).length,
+    updatedAtDefaultedCount: fixtures.filter((fixture) => fixture.updated_at === void 0).length,
+    seededEntries: prepared.map((fixture) => summarizePreparedFixture(fixture.entry))
+  };
+}
+function buildEntry(fixture, id, provisionedAt) {
+  const createdAt = fixture.created_at ?? provisionedAt;
+  const updatedAt = fixture.updated_at ?? createdAt;
+  return {
+    id,
+    type: fixture.type,
+    subject: fixture.subject,
+    content: fixture.content,
+    importance: fixture.importance ?? DEFAULT_IMPORTANCE,
+    expiry: fixture.expiry ?? DEFAULT_EXPIRY,
+    tags: fixture.tags ?? [],
+    source_file: fixture.source_file,
+    source_context: fixture.source_context,
+    quality_score: DEFAULT_QUALITY_SCORE,
+    recall_count: 0,
+    superseded_by: fixture.superseded_by,
+    claim_key: fixture.claim_key,
+    claim_key_status: fixture.claim_key_status,
+    claim_key_source: fixture.claim_key_source,
+    claim_support_source_kind: fixture.claim_support_source_kind,
+    claim_support_locator: fixture.claim_support_locator,
+    claim_support_observed_at: fixture.claim_support_observed_at,
+    claim_support_mode: fixture.claim_support_mode,
+    valid_from: fixture.valid_from,
+    valid_to: fixture.valid_to,
+    supersession_kind: fixture.supersession_kind,
+    supersession_reason: fixture.supersession_reason,
+    retired: fixture.retired ?? false,
+    retired_at: fixture.retired_at,
+    retired_reason: fixture.retired_reason,
+    created_at: createdAt,
+    updated_at: updatedAt
+  };
+}
+function summarizePreparedFixture(entry) {
+  return {
+    id: entry.id,
+    created_at: entry.created_at,
+    updated_at: entry.updated_at,
+    retired: entry.retired,
+    superseded_by: entry.superseded_by,
+    claim_key: entry.claim_key,
+    claim_key_status: entry.claim_key_status,
+    valid_from: entry.valid_from,
+    valid_to: entry.valid_to
+  };
+}
+function createFixtureId(caseId, index, fixture) {
+  const digest = createHash("sha256").update(caseId).update(":").update(String(index)).update(":").update(fixture.type).update(":").update(fixture.subject).update(":").update(fixture.content).digest("hex");
+  return `eval-${digest.slice(0, 24)}`;
+}
+function findDuplicateIds(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = [];
+  for (const id of ids) {
+    if (seen.has(id)) {
+      if (!duplicates.includes(id)) {
+        duplicates.push(id);
+      }
+      continue;
+    }
+    seen.add(id);
+  }
+  return duplicates;
+}
+function topologicallySortFixtures(fixtures) {
+  const indegree = new Map(fixtures.map((fixture) => [fixture.entry.id, 0]));
+  const dependents = /* @__PURE__ */ new Map();
+  for (const fixture of fixtures) {
+    const successorId = fixture.entry.superseded_by;
+    if (!successorId) {
+      continue;
+    }
+    indegree.set(fixture.entry.id, (indegree.get(fixture.entry.id) ?? 0) + 1);
+    const successorDependents = dependents.get(successorId) ?? [];
+    successorDependents.push(fixture);
+    dependents.set(successorId, successorDependents);
+  }
+  const ready = fixtures.filter((fixture) => (indegree.get(fixture.entry.id) ?? 0) === 0).sort((left, right) => left.fixtureIndex - right.fixtureIndex);
+  const sorted = [];
+  while (ready.length > 0) {
+    const current = ready.shift();
+    if (!current) {
+      break;
+    }
+    sorted.push(current);
+    const currentDependents = (dependents.get(current.entry.id) ?? []).sort((left, right) => left.fixtureIndex - right.fixtureIndex);
+    for (const dependent of currentDependents) {
+      const remaining = (indegree.get(dependent.entry.id) ?? 0) - 1;
+      indegree.set(dependent.entry.id, remaining);
+      if (remaining === 0) {
+        ready.push(dependent);
+        ready.sort((left, right) => left.fixtureIndex - right.fixtureIndex);
+      }
+    }
+  }
+  if (sorted.length !== fixtures.length) {
+    const unresolved = fixtures.filter((fixture) => !sorted.includes(fixture)).map((fixture) => fixture.entry.id);
+    throw new Error(`Fixture supersession metadata contains a cycle: ${unresolved.join(", ")}.`);
+  }
+  return sorted;
+}
+function hashText(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+// src/app/evals/recall/provision-procedure-fixtures.ts
+import { createHash as createHash2 } from "crypto";
+async function provisionRecallEvalProcedureFixtures(params) {
+  const procedures = prepareProcedures(params.caseId, params.procedurePool, params.provisionedAt);
+  if (procedures.length === 0) {
+    return {
+      provisionedCount: 0
+    };
+  }
+  await params.store.withTransaction(async (store) => {
+    for (const procedure of procedures) {
+      await store.insertProcedure(procedure);
+    }
+  });
+  return {
+    provisionedCount: procedures.length
+  };
+}
+function prepareProcedures(caseId, fixtures, provisionedAt) {
+  const resolvedIds = fixtures.map((fixture, index) => fixture.id ?? createFixtureId2(caseId, index, fixture));
+  const duplicateIds = findDuplicateIds2(resolvedIds);
+  if (duplicateIds.length > 0) {
+    throw new Error(`Procedure fixture IDs must be unique. Duplicate IDs: ${duplicateIds.join(", ")}.`);
+  }
+  const knownIds = new Set(resolvedIds);
+  return fixtures.map((fixture, index) => {
+    if (fixture.superseded_by && !knownIds.has(fixture.superseded_by)) {
+      throw new Error(`procedurePool[${index}].superseded_by references unknown fixture id "${fixture.superseded_by}".`);
+    }
+    const normalizedBody = normalizeProcedureDefinition(
+      {
+        procedure_key: fixture.procedure_key,
+        title: fixture.title,
+        goal: fixture.goal,
+        when_to_use: fixture.when_to_use ?? [],
+        when_not_to_use: fixture.when_not_to_use ?? [],
+        prerequisites: fixture.prerequisites ?? [],
+        steps: fixture.steps,
+        verification: fixture.verification ?? [],
+        failure_modes: fixture.failure_modes ?? [],
+        sources: fixture.sources ?? [{ kind: "manual", label: "recall eval fixture" }]
+      },
+      `procedurePool[${index}]`
+    );
+    const createdAt = fixture.created_at ?? provisionedAt;
+    const updatedAt = fixture.updated_at ?? createdAt;
+    return {
+      id: resolvedIds[index] ?? "",
+      ...normalizedBody,
+      source_file: fixture.source_file,
+      recall_text: composeProcedureRecallText(normalizedBody),
+      revision_hash: computeProcedureRevisionHash(normalizedBody),
+      source_hash: computeProcedureSourceHash(JSON.stringify(normalizedBody)),
+      retired: fixture.retired ?? false,
+      retired_at: fixture.retired_at,
+      retired_reason: fixture.retired_reason,
+      superseded_by: fixture.superseded_by,
+      created_at: createdAt,
+      updated_at: updatedAt
+    };
+  });
+}
+function createFixtureId2(caseId, index, fixture) {
+  const digest = createHash2("sha256").update(caseId).update(":").update(String(index)).update(":").update(fixture.procedure_key).update(":").update(fixture.title).update(":").update(fixture.goal).digest("hex");
+  return `eval-procedure-${digest.slice(0, 24)}`;
+}
+function findDuplicateIds2(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = [];
+  for (const id of ids) {
+    if (seen.has(id)) {
+      if (!duplicates.includes(id)) {
+        duplicates.push(id);
+      }
+      continue;
+    }
+    seen.add(id);
+  }
+  return duplicates;
+}
+
+// src/app/evals/recall/sandbox.ts
+import { access, copyFile, mkdir, mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+
+// src/adapters/db/eval-fixture-store.ts
+function createRecallEvalFixtureStore(database) {
+  return {
+    insertEntry: async (entry, embedding, contentHash) => database.insertEntry(entry, embedding, contentHash),
+    insertProcedure: async (procedure) => database.upsertProcedure(procedure),
+    withTransaction: async (fn) => database.withTransaction(async (transaction) => fn(createRecallEvalFixtureStore(transaction)))
+  };
+}
+
+// src/app/evals/recall/sandbox.ts
+var SANDBOX_DB_FILENAME = "knowledge.db";
+var SANDBOX_DIR_PREFIX = "agenr-recall-eval-";
+async function setupRecallEvalSandbox(request) {
+  const suppliedRoot = request?.root !== void 0;
+  const preserved = request?.preserve === true;
+  const root = suppliedRoot ? path.resolve(request.root ?? "") : await mkdtemp(path.join(tmpdir(), SANDBOX_DIR_PREFIX));
+  const snapshotSeed = request?.corpusSeed?.mode === "snapshot_copy" ? request.corpusSeed : void 0;
+  let database;
+  const dbPath = path.join(root, SANDBOX_DB_FILENAME);
+  try {
+    if (suppliedRoot) {
+      await mkdir(root, { recursive: true });
+    }
+    await removeDatabaseFiles(dbPath);
+    if (snapshotSeed !== void 0) {
+      await seedSandboxFromSnapshot(snapshotSeed, dbPath);
+    }
+    database = await createDatabase(dbPath);
+    const openDatabase = database;
+    const snapshot = snapshotSeed ? buildSnapshotMetadata(snapshotSeed) : void 0;
+    return {
+      root,
+      dbPath,
+      preserved,
+      fixtureStore: createRecallEvalFixtureStore(openDatabase),
+      episodeDatabase: openDatabase,
+      procedureDatabase: openDatabase,
+      ...snapshot ? { snapshot } : {},
+      createRecallPorts: (embedding) => createRecallAdapter(openDatabase, embedding),
+      cleanup: async () => {
+        await openDatabase.close().catch(() => void 0);
+        if (preserved) {
+          return;
+        }
+        if (suppliedRoot) {
+          await removeDatabaseFiles(dbPath);
+          return;
+        }
+        await rm(root, { recursive: true, force: true });
+      }
+    };
+  } catch (error) {
+    await database?.close().catch(() => void 0);
+    if (!preserved) {
+      if (suppliedRoot) {
+        await removeDatabaseFiles(dbPath).catch(() => void 0);
+      } else {
+        await rm(root, { recursive: true, force: true }).catch(() => void 0);
+      }
+    }
+    throw error;
+  }
+}
+async function seedSandboxFromSnapshot(seed, dbPath) {
+  const rawPath = seed.snapshotDbPath.trim();
+  if (rawPath.length === 0) {
+    throw new Error("Snapshot database path must not be empty.");
+  }
+  const sourcePath = path.resolve(rawPath);
+  const targetPath = path.resolve(dbPath);
+  if (sourcePath === targetPath) {
+    throw new Error("Snapshot database path must not point at the sandbox database path.");
+  }
+  try {
+    await access(sourcePath);
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(`Snapshot database file is not accessible at ${sourcePath}: ${cause}`, {
+      cause: error
+    });
+  }
+  await copyFile(sourcePath, dbPath);
+}
+function buildSnapshotMetadata(seed) {
+  return {
+    ...seed.snapshotId !== void 0 ? { id: seed.snapshotId } : {},
+    ...seed.snapshotLabel !== void 0 ? { label: seed.snapshotLabel } : {},
+    dbPathBasename: path.basename(seed.snapshotDbPath),
+    allowedTelemetryWrites: seed.allowTelemetryWrites === true
+  };
+}
+async function removeDatabaseFiles(dbPath) {
+  await Promise.all([rm(dbPath, { force: true }), rm(`${dbPath}-wal`, { force: true }), rm(`${dbPath}-shm`, { force: true })]);
+}
+
+// src/app/evals/recall/telemetry-write-gate.ts
+function applyTelemetryWriteGate(ports, sandbox) {
+  const snapshot = sandbox.snapshot;
+  if (snapshot === void 0 || snapshot.allowedTelemetryWrites) {
+    return ports;
+  }
+  return {
+    async embed(text) {
+      return ports.embed(text);
+    },
+    async vectorSearch(params) {
+      return ports.vectorSearch(params);
+    },
+    async ftsSearch(params) {
+      return ports.ftsSearch(params);
+    },
+    ...ports.expandNeighborhood ? {
+      async expandNeighborhood(request) {
+        return ports.expandNeighborhood(request);
+      }
+    } : {},
+    ...ports.crossEncoder ? {
+      crossEncoder: ports.crossEncoder
+    } : {},
+    async hydrateEntries(ids) {
+      return ports.hydrateEntries(ids);
+    },
+    async recordRecallEvents() {
+      return void 0;
+    }
+  };
+}
+
+// src/app/evals/before-turn/build-debug-artifact.ts
+function buildBeforeTurnDebugArtifact(params) {
+  const { request, patch, sandbox } = params;
+  const diagnostics = patch.diagnostics;
+  const topK = resolveTopK(request.options?.topKCandidates);
+  const durableTopCandidates = buildDurableCandidates(patch, topK);
+  const procedureTopCandidates = buildProcedureCandidates(patch, topK);
+  const trigger = request.beforeTurnInput.trigger ?? "unspecified";
+  return {
+    schemaVersion: "before-turn-debug-artifact.v1",
+    caseId: request.caseId,
+    ...sandbox.snapshot ? { snapshot: buildSnapshot(sandbox.snapshot) } : {},
+    input: {
+      trigger,
+      currentTurnText: request.beforeTurnInput.currentTurnText
+    },
+    ...diagnostics.queryPolicy ? { queryPolicy: diagnostics.queryPolicy } : {},
+    ...diagnostics.queryVariants.length > 0 ? { queryVariants: [...diagnostics.queryVariants] } : {},
+    ...diagnostics.abstentionReasons.length > 0 ? { abstentionReasons: [...diagnostics.abstentionReasons] } : {},
+    selectedEntryIds: patch.durableMemory.map((item) => item.entry.id),
+    selectedProcedureKey: patch.procedure?.procedure.procedure_key ?? null,
+    ...durableTopCandidates.length > 0 ? { durableRecallTopCandidates: durableTopCandidates } : {},
+    ...procedureTopCandidates.length > 0 ? { procedureTopCandidates } : {}
+  };
+}
+function buildSnapshot(snapshot) {
+  return {
+    ...snapshot.id !== void 0 ? { id: snapshot.id } : {},
+    ...snapshot.label !== void 0 ? { label: snapshot.label } : {},
+    dbPathBasename: snapshot.dbPathBasename
+  };
+}
+function resolveTopK(requested) {
+  if (requested === void 0) {
+    return BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K;
+  }
+  if (!Number.isFinite(requested) || !Number.isInteger(requested)) {
+    return BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K;
+  }
+  if (requested < 1) {
+    return 1;
+  }
+  if (requested > BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K) {
+    return BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K;
+  }
+  return requested;
+}
+function buildDurableCandidates(patch, topK) {
+  return patch.durableMemory.slice(0, topK).map((item) => {
+    const reasons = item.whySurfaced.reasons.length > 0 ? [...item.whySurfaced.reasons] : void 0;
+    return {
+      id: item.entry.id,
+      score: item.score,
+      ...reasons ? { reasons } : {}
+    };
+  });
+}
+function buildProcedureCandidates(patch, topK) {
+  if (!patch.procedure) {
+    return [];
+  }
+  if (topK < 1) {
+    return [];
+  }
+  const reasons = patch.procedure.whySurfaced.reasons.length > 0 ? [...patch.procedure.whySurfaced.reasons] : void 0;
+  return [
+    {
+      procedureKey: patch.procedure.procedure.procedure_key,
+      score: patch.procedure.score,
+      ...reasons ? { reasons } : {}
+    }
+  ];
+}
+
+// src/app/evals/before-turn/normalize-response.ts
+function buildBeforeTurnEvalSuccessResponse(params) {
+  const output = buildOutput(params.patch, params.renderedPatchText);
+  const debugArtifact = params.request.options?.includeDebugArtifact === true ? buildBeforeTurnDebugArtifact({ request: params.request, patch: params.patch, sandbox: params.sandbox }) : void 0;
+  return {
+    status: "ok",
+    caseId: params.request.caseId,
+    output,
+    diagnostics: params.request.options?.includeDiagnostics === true ? params.patch.diagnostics : void 0,
+    timings: params.timings,
+    sandbox: buildSandboxResult(params.sandbox),
+    ...debugArtifact ? { debugArtifact } : {}
+  };
+}
+function buildBeforeTurnEvalErrorResponse(params) {
+  return {
+    status: "error",
+    caseId: params.request.caseId,
+    error: {
+      code: params.code,
+      message: params.message,
+      details: params.details
+    },
+    timings: params.timings,
+    sandbox: params.sandbox ? buildSandboxResult(params.sandbox) : void 0
+  };
+}
+function maybeRenderBeforeTurnPatch(request, patch) {
+  if (request.options?.includeRenderedPatch !== true) {
+    return void 0;
+  }
+  return formatAgenrBeforeTurnRecall(patch);
+}
+function buildSandboxResult(sandbox) {
+  return {
+    root: sandbox.root,
+    dbPath: sandbox.dbPath,
+    preserved: sandbox.preserved,
+    ...sandbox.snapshot ? { snapshot: sandbox.snapshot } : {}
+  };
+}
+function buildOutput(patch, renderedPatchText) {
+  return {
+    abstained: patch.diagnostics.abstained,
+    selectedEntryIds: patch.durableMemory.map((item) => item.entry.id),
+    selectedProcedureKey: patch.procedure?.procedure.procedure_key ?? null,
+    patch: normalizePatchForEvalOutput(patch),
+    ...renderedPatchText !== void 0 ? { renderedPatchText } : {}
+  };
+}
+function normalizePatchForEvalOutput(patch) {
+  return {
+    ...patch,
+    durableMemory: patch.durableMemory.map((item) => ({
+      ...item,
+      entry: {
+        ...item.entry,
+        ...typeof item.entry.claim_key === "string" ? { claimKey: item.entry.claim_key } : {}
+      }
+    }))
+  };
+}
+
+// src/app/evals/before-turn/run-before-turn-eval-case.ts
+async function runBeforeTurnEvalCase(request, dependencies = {}) {
+  const startedAt = Date.now();
+  const provisionedAt = new Date(startedAt).toISOString();
+  let sandbox;
+  let sharedEmbeddingPort;
+  let sharedEmbeddingError;
+  let timings;
+  const getEmbeddingSupport = () => {
+    if (sharedEmbeddingPort) {
+      return {
+        available: true,
+        port: sharedEmbeddingPort
+      };
+    }
+    if (sharedEmbeddingError) {
+      return {
+        available: false,
+        error: sharedEmbeddingError
+      };
+    }
+    const config = readConfig();
+    try {
+      sharedEmbeddingPort = createEmbeddingClient(resolveEmbeddingApiKey(config), resolveEmbeddingModel(config));
+      return {
+        available: true,
+        port: sharedEmbeddingPort
+      };
+    } catch (error) {
+      sharedEmbeddingError = error instanceof Error ? error.message : String(error);
+      return {
+        available: false,
+        error: sharedEmbeddingError
+      };
+    }
+  };
+  try {
+    const sandboxStartedAt = Date.now();
+    try {
+      sandbox = await setupRecallEvalSandbox(request.sandbox);
+      timings = {
+        ...timings,
+        sandboxSetupMs: elapsedMs(sandboxStartedAt)
+      };
+    } catch (error) {
+      timings = {
+        ...timings,
+        totalMs: elapsedMs(startedAt),
+        sandboxSetupMs: elapsedMs(sandboxStartedAt)
+      };
+      return buildBeforeTurnEvalErrorResponse({
+        request,
+        code: "sandbox_setup_failed",
+        message: "Failed to create isolated before-turn eval sandbox.",
+        details: toErrorDetails(error),
+        timings: request.options?.includeTimings === true ? timings : void 0
+      });
+    }
+    if (request.memoryPool.length > 0 || (request.procedurePool?.length ?? 0) > 0) {
+      const provisionStartedAt = Date.now();
+      try {
+        if (request.memoryPool.length > 0) {
+          const embeddingSupport = getEmbeddingSupport();
+          const embeddingPort = embeddingSupport.port ?? createUnavailableEmbeddingPort(embeddingSupport.error ?? "Embeddings are unavailable.");
+          await provisionRecallEvalFixtures({
+            caseId: request.caseId,
+            memoryPool: request.memoryPool,
+            store: sandbox.fixtureStore,
+            embedding: embeddingPort,
+            provisionedAt
+          });
+        }
+        if ((request.procedurePool?.length ?? 0) > 0) {
+          await provisionRecallEvalProcedureFixtures({
+            caseId: request.caseId,
+            procedurePool: request.procedurePool ?? [],
+            store: sandbox.fixtureStore,
+            provisionedAt
+          });
+        }
+        timings = {
+          ...timings,
+          fixtureProvisionMs: elapsedMs(provisionStartedAt)
+        };
+      } catch (error) {
+        timings = {
+          ...timings,
+          totalMs: elapsedMs(startedAt),
+          fixtureProvisionMs: elapsedMs(provisionStartedAt)
+        };
+        return buildBeforeTurnEvalErrorResponse({
+          request,
+          code: "fixture_provision_failed",
+          message: "Failed to provision before-turn eval fixtures into isolated storage.",
+          details: toErrorDetails(error),
+          timings: request.options?.includeTimings === true ? timings : void 0,
+          sandbox
+        });
+      }
+    }
+    const beforeTurnStartedAt = Date.now();
+    try {
+      const embeddingSupport = getEmbeddingSupport();
+      const sandboxRecallPorts = sandbox.createRecallPorts(
+        embeddingSupport.port ?? createUnavailableEmbeddingPort(embeddingSupport.error ?? "Embeddings are unavailable.")
+      );
+      const recallPorts = applyTelemetryWriteGate(attachCrossEncoderPort(sandboxRecallPorts, dependencies.crossEncoder), sandbox);
+      const patch = await runBeforeTurn(request.beforeTurnInput, {
+        recall: recallPorts,
+        procedures: sandbox.procedureDatabase,
+        embedQuery: embeddingSupport.port ? async (text) => {
+          const vectors = await embeddingSupport.port.embed([text]);
+          return vectors[0] ?? [];
+        } : void 0
+      });
+      timings = {
+        ...timings,
+        beforeTurnMs: elapsedMs(beforeTurnStartedAt)
+      };
+      let renderedPatchText;
+      if (request.options?.includeRenderedPatch === true) {
+        const renderStartedAt = Date.now();
+        renderedPatchText = maybeRenderBeforeTurnPatch(request, patch);
+        timings = {
+          ...timings,
+          renderPatchMs: elapsedMs(renderStartedAt)
+        };
+      }
+      timings = {
+        ...timings,
+        totalMs: elapsedMs(startedAt)
+      };
+      return buildBeforeTurnEvalSuccessResponse({
+        request,
+        patch,
+        renderedPatchText,
+        timings: request.options?.includeTimings === true ? timings : void 0,
+        sandbox
+      });
+    } catch (error) {
+      timings = {
+        ...timings,
+        totalMs: elapsedMs(startedAt),
+        beforeTurnMs: elapsedMs(beforeTurnStartedAt)
+      };
+      return buildBeforeTurnEvalErrorResponse({
+        request,
+        code: "before_turn_execution_failed",
+        message: "Failed to execute real before-turn selection against isolated eval state.",
+        details: toErrorDetails(error),
+        timings: request.options?.includeTimings === true ? timings : void 0,
+        sandbox
+      });
+    }
+  } catch (error) {
+    return buildBeforeTurnEvalErrorResponse({
+      request,
+      code: "internal_error",
+      message: "Before-turn eval execution failed unexpectedly.",
+      details: toErrorDetails(error),
+      timings: request.options?.includeTimings === true ? { ...timings, totalMs: elapsedMs(startedAt) } : void 0,
+      sandbox
+    });
+  } finally {
+    await sandbox?.cleanup().catch(() => void 0);
+  }
+}
+function toErrorDetails(error) {
+  if (error instanceof Error) {
+    return {
+      cause: error.message
+    };
+  }
+  return {
+    cause: String(error)
+  };
+}
+function createUnavailableEmbeddingPort(message) {
+  return {
+    async embed() {
+      throw new Error(message);
+    }
+  };
+}
+function elapsedMs(startedAt) {
+  return Date.now() - startedAt;
+}
+
+// src/adapters/api/validation/internal-eval-shared.ts
+var SANDBOX_REQUEST_KEYS = /* @__PURE__ */ new Set(["root", "preserve", "corpusSeed"]);
+var CORPUS_SEED_MODES = ["fixture", "snapshot_copy"];
+var FIXTURE_CORPUS_SEED_KEYS = /* @__PURE__ */ new Set(["mode"]);
+var SNAPSHOT_COPY_CORPUS_SEED_KEYS = /* @__PURE__ */ new Set(["mode", "snapshotDbPath", "snapshotId", "snapshotLabel", "allowTelemetryWrites"]);
+var FIXTURE_ENTRY_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "subject",
+  "content",
+  "importance",
+  "expiry",
+  "tags",
+  "source_file",
+  "source_context",
+  "created_at",
+  "updated_at",
+  "retired",
+  "retired_at",
+  "retired_reason",
+  "superseded_by",
+  "claim_key",
+  "claim_key_status",
+  "claim_key_source",
+  "claim_support_source_kind",
+  "claim_support_locator",
+  "claim_support_observed_at",
+  "claim_support_mode",
+  "valid_from",
+  "valid_to",
+  "supersession_kind",
+  "supersession_reason"
+]);
+var FIXTURE_PROCEDURE_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "procedure_key",
+  "title",
+  "goal",
+  "when_to_use",
+  "when_not_to_use",
+  "prerequisites",
+  "steps",
+  "verification",
+  "failure_modes",
+  "sources",
+  "source_file",
+  "retired",
+  "retired_at",
+  "retired_reason",
+  "superseded_by",
+  "created_at",
+  "updated_at"
+]);
+function extractParseableCaseId(value) {
+  if (!isRecord(value) || typeof value.caseId !== "string") {
+    return void 0;
+  }
+  const normalized = value.caseId.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function parseObject(value, path2, issues) {
+  if (!isRecord(value)) {
+    pushIssue(issues, path2, "Expected an object.");
+    return void 0;
+  }
+  return value;
+}
+function parseSandbox(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const sandbox = parseObject(value, "sandbox", issues);
+  if (sandbox === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(sandbox, SANDBOX_REQUEST_KEYS, "sandbox", issues);
+  return {
+    root: parseOptionalTrimmedString(sandbox.root, "sandbox.root", issues),
+    preserve: parseOptionalBoolean(sandbox.preserve, "sandbox.preserve", issues),
+    corpusSeed: parseCorpusSeed(sandbox.corpusSeed, issues)
+  };
+}
+function parseCorpusSeed(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const seed = parseObject(value, "sandbox.corpusSeed", issues);
+  if (seed === void 0) {
+    return void 0;
+  }
+  const mode = parseCorpusSeedMode(seed.mode, "sandbox.corpusSeed.mode", issues);
+  if (mode === void 0) {
+    return void 0;
+  }
+  if (mode === "fixture") {
+    pushUnexpectedFields(seed, FIXTURE_CORPUS_SEED_KEYS, "sandbox.corpusSeed", issues);
+    return { mode: "fixture" };
+  }
+  pushUnexpectedFields(seed, SNAPSHOT_COPY_CORPUS_SEED_KEYS, "sandbox.corpusSeed", issues);
+  const snapshotDbPath = parseRequiredTrimmedString(seed.snapshotDbPath, "sandbox.corpusSeed.snapshotDbPath", issues);
+  const snapshotId = parseOptionalTrimmedString(seed.snapshotId, "sandbox.corpusSeed.snapshotId", issues);
+  const snapshotLabel = parseOptionalTrimmedString(seed.snapshotLabel, "sandbox.corpusSeed.snapshotLabel", issues);
+  const allowTelemetryWrites = parseOptionalBoolean(seed.allowTelemetryWrites, "sandbox.corpusSeed.allowTelemetryWrites", issues);
+  if (snapshotDbPath === void 0) {
+    return void 0;
+  }
+  return {
+    mode: "snapshot_copy",
+    snapshotDbPath,
+    ...snapshotId !== void 0 ? { snapshotId } : {},
+    ...snapshotLabel !== void 0 ? { snapshotLabel } : {},
+    ...allowTelemetryWrites !== void 0 ? { allowTelemetryWrites } : {}
+  };
+}
+function parseCorpusSeedMode(value, path2, issues) {
+  if (typeof value !== "string" || !CORPUS_SEED_MODES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${CORPUS_SEED_MODES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseMemoryPool(value, issues) {
+  if (!Array.isArray(value)) {
+    pushIssue(issues, "memoryPool", "Expected an array of fixture entries.");
+    return void 0;
+  }
+  return value.flatMap((entry, index) => {
+    const parsed = parseFixtureEntry(entry, index, issues);
+    return parsed ? [parsed] : [];
+  });
+}
+function parseProcedurePool(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    pushIssue(issues, "procedurePool", "Expected an array of fixture procedures.");
+    return void 0;
+  }
+  return value.flatMap((procedure, index) => {
+    const parsed = parseFixtureProcedure(procedure, index, issues);
+    return parsed ? [parsed] : [];
+  });
+}
+function mapSandboxRequestDto(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    root: dto.root,
+    preserve: dto.preserve,
+    corpusSeed: dto.corpusSeed
+  };
+}
+function mapFixtureEntryDto(dto) {
+  return {
+    id: dto.id,
+    type: dto.type,
+    subject: dto.subject,
+    content: dto.content,
+    importance: dto.importance,
+    expiry: dto.expiry,
+    tags: dto.tags,
+    source_file: dto.source_file,
+    source_context: dto.source_context,
+    created_at: dto.created_at,
+    updated_at: dto.updated_at,
+    retired: dto.retired,
+    retired_at: dto.retired_at,
+    retired_reason: dto.retired_reason,
+    superseded_by: dto.superseded_by,
+    claim_key: dto.claim_key,
+    claim_key_status: dto.claim_key_status,
+    claim_key_source: dto.claim_key_source,
+    claim_support_source_kind: dto.claim_support_source_kind,
+    claim_support_locator: dto.claim_support_locator,
+    claim_support_observed_at: dto.claim_support_observed_at,
+    claim_support_mode: dto.claim_support_mode,
+    valid_from: dto.valid_from,
+    valid_to: dto.valid_to,
+    supersession_kind: dto.supersession_kind,
+    supersession_reason: dto.supersession_reason
+  };
+}
+function mapFixtureProcedureDto(dto) {
+  return {
+    id: dto.id,
+    procedure_key: dto.procedure_key,
+    title: dto.title,
+    goal: dto.goal,
+    when_to_use: dto.when_to_use,
+    when_not_to_use: dto.when_not_to_use,
+    prerequisites: dto.prerequisites,
+    steps: dto.steps,
+    verification: dto.verification,
+    failure_modes: dto.failure_modes,
+    sources: dto.sources,
+    source_file: dto.source_file,
+    retired: dto.retired,
+    retired_at: dto.retired_at,
+    retired_reason: dto.retired_reason,
+    superseded_by: dto.superseded_by,
+    created_at: dto.created_at,
+    updated_at: dto.updated_at
+  };
+}
+function parseOptionalStringArray(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    pushIssue(issues, path2, "Expected an array of strings.");
+    return void 0;
+  }
+  return value.map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function parseOptionalThreshold(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || Number.isNaN(value) || value < 0 || value > 1) {
+    pushIssue(issues, path2, "Expected a number from 0 to 1.");
+    return void 0;
+  }
+  return value;
+}
+function parseRequiredString(value, path2, issues) {
+  if (typeof value !== "string") {
+    pushIssue(issues, path2, "Expected a string.");
+    return void 0;
+  }
+  return value;
+}
+function parseRecentTurnRole(value, path2, issues) {
+  if (typeof value !== "string") {
+    pushIssue(issues, path2, 'Expected "user" or "assistant".');
+    return void 0;
+  }
+  const normalized = value.trim();
+  if (normalized !== "user" && normalized !== "assistant") {
+    pushIssue(issues, path2, 'Expected "user" or "assistant".');
+    return void 0;
+  }
+  return normalized;
+}
+function parseFixtureEntry(value, index, issues) {
+  const basePath = `memoryPool[${index}]`;
+  const fixture = parseObject(value, basePath, issues);
+  if (fixture === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(fixture, FIXTURE_ENTRY_KEYS, basePath, issues);
+  const type = parseEntryType(fixture.type, `${basePath}.type`, issues);
+  const subject = parseRequiredTrimmedString(fixture.subject, `${basePath}.subject`, issues);
+  const content = parseRequiredTrimmedString(fixture.content, `${basePath}.content`, issues);
+  if (type === void 0 || subject === void 0 || content === void 0) {
+    return void 0;
+  }
+  return {
+    id: parseOptionalTrimmedString(fixture.id, `${basePath}.id`, issues),
+    type,
+    subject,
+    content,
+    importance: parseOptionalIntegerInRange(fixture.importance, `${basePath}.importance`, issues, {
+      min: 1,
+      max: 10
+    }),
+    expiry: parseOptionalExpiry(fixture.expiry, `${basePath}.expiry`, issues),
+    tags: parseOptionalStringArray(fixture.tags, `${basePath}.tags`, issues),
+    source_file: parseOptionalTrimmedString(fixture.source_file, `${basePath}.source_file`, issues),
+    source_context: parseOptionalTrimmedString(fixture.source_context, `${basePath}.source_context`, issues),
+    created_at: parseOptionalTimestampString(fixture.created_at, `${basePath}.created_at`, issues),
+    updated_at: parseOptionalTimestampString(fixture.updated_at, `${basePath}.updated_at`, issues),
+    retired: parseOptionalBoolean(fixture.retired, `${basePath}.retired`, issues),
+    retired_at: parseOptionalTimestampString(fixture.retired_at, `${basePath}.retired_at`, issues),
+    retired_reason: parseOptionalTrimmedString(fixture.retired_reason, `${basePath}.retired_reason`, issues),
+    superseded_by: parseOptionalTrimmedString(fixture.superseded_by, `${basePath}.superseded_by`, issues),
+    claim_key: parseOptionalTrimmedString(fixture.claim_key, `${basePath}.claim_key`, issues),
+    claim_key_status: parseOptionalClaimKeyStatus(fixture.claim_key_status, `${basePath}.claim_key_status`, issues),
+    claim_key_source: parseOptionalClaimKeySource(fixture.claim_key_source, `${basePath}.claim_key_source`, issues),
+    claim_support_source_kind: parseOptionalTrimmedString(fixture.claim_support_source_kind, `${basePath}.claim_support_source_kind`, issues),
+    claim_support_locator: parseOptionalTrimmedString(fixture.claim_support_locator, `${basePath}.claim_support_locator`, issues),
+    claim_support_observed_at: parseOptionalTimestampString(fixture.claim_support_observed_at, `${basePath}.claim_support_observed_at`, issues),
+    claim_support_mode: parseOptionalClaimSupportMode(fixture.claim_support_mode, `${basePath}.claim_support_mode`, issues),
+    valid_from: parseOptionalTimestampString(fixture.valid_from, `${basePath}.valid_from`, issues),
+    valid_to: parseOptionalTimestampString(fixture.valid_to, `${basePath}.valid_to`, issues),
+    supersession_kind: parseOptionalTrimmedString(fixture.supersession_kind, `${basePath}.supersession_kind`, issues),
+    supersession_reason: parseOptionalTrimmedString(fixture.supersession_reason, `${basePath}.supersession_reason`, issues)
+  };
+}
+function parseFixtureProcedure(value, index, issues) {
+  const basePath = `procedurePool[${index}]`;
+  const fixture = parseObject(value, basePath, issues);
+  if (fixture === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(fixture, FIXTURE_PROCEDURE_KEYS, basePath, issues);
+  const procedureKey = parseRequiredTrimmedString(fixture.procedure_key, `${basePath}.procedure_key`, issues);
+  const title = parseRequiredTrimmedString(fixture.title, `${basePath}.title`, issues);
+  const goal = parseRequiredTrimmedString(fixture.goal, `${basePath}.goal`, issues);
+  const whenToUse = parseOptionalStringArray(fixture.when_to_use, `${basePath}.when_to_use`, issues);
+  const whenNotToUse = parseOptionalStringArray(fixture.when_not_to_use, `${basePath}.when_not_to_use`, issues);
+  const prerequisites = parseOptionalStringArray(fixture.prerequisites, `${basePath}.prerequisites`, issues);
+  const verification = parseOptionalStringArray(fixture.verification, `${basePath}.verification`, issues);
+  const failureModes = parseOptionalStringArray(fixture.failure_modes, `${basePath}.failure_modes`, issues);
+  if (procedureKey === void 0 || title === void 0 || goal === void 0) {
+    return void 0;
+  }
+  try {
+    const normalized = normalizeProcedureDefinition(
+      {
+        procedure_key: procedureKey,
+        title,
+        goal,
+        when_to_use: whenToUse ?? [],
+        when_not_to_use: whenNotToUse ?? [],
+        prerequisites: prerequisites ?? [],
+        steps: fixture.steps,
+        verification: verification ?? [],
+        failure_modes: failureModes ?? [],
+        sources: fixture.sources ?? [{ kind: "manual", label: "recall eval fixture" }]
+      },
+      basePath
+    );
+    return {
+      id: parseOptionalTrimmedString(fixture.id, `${basePath}.id`, issues),
+      procedure_key: normalized.procedure_key,
+      title: normalized.title,
+      goal: normalized.goal,
+      when_to_use: normalized.when_to_use,
+      when_not_to_use: normalized.when_not_to_use,
+      prerequisites: normalized.prerequisites,
+      steps: normalized.steps,
+      verification: normalized.verification,
+      failure_modes: normalized.failure_modes,
+      sources: normalized.sources,
+      source_file: parseOptionalTrimmedString(fixture.source_file, `${basePath}.source_file`, issues),
+      retired: parseOptionalBoolean(fixture.retired, `${basePath}.retired`, issues),
+      retired_at: parseOptionalTimestampString(fixture.retired_at, `${basePath}.retired_at`, issues),
+      retired_reason: parseOptionalTrimmedString(fixture.retired_reason, `${basePath}.retired_reason`, issues),
+      superseded_by: parseOptionalTrimmedString(fixture.superseded_by, `${basePath}.superseded_by`, issues),
+      created_at: parseOptionalTimestampString(fixture.created_at, `${basePath}.created_at`, issues),
+      updated_at: parseOptionalTimestampString(fixture.updated_at, `${basePath}.updated_at`, issues)
+    };
+  } catch (error) {
+    pushIssue(issues, basePath, error instanceof Error ? error.message : String(error));
+    return void 0;
+  }
+}
+function parseEntryType(value, path2, issues) {
+  if (typeof value !== "string" || !ENTRY_TYPES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${ENTRY_TYPES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalExpiry(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !EXPIRY_LEVELS.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${EXPIRY_LEVELS.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalClaimKeyStatus(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !CLAIM_KEY_STATUSES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${CLAIM_KEY_STATUSES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalClaimKeySource(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !CLAIM_KEY_SOURCES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${CLAIM_KEY_SOURCES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalClaimSupportMode(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !CLAIM_SUPPORT_MODES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${CLAIM_SUPPORT_MODES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+
+// src/adapters/api/validation/before-turn-eval-request.ts
+var ROOT_REQUEST_KEYS = /* @__PURE__ */ new Set(["caseId", "description", "sandbox", "memoryPool", "procedurePool", "beforeTurnInput", "options"]);
+var BEFORE_TURN_INPUT_KEYS = /* @__PURE__ */ new Set(["sessionKey", "currentTurnText", "recentTurns", "trigger", "policy"]);
+var BEFORE_TURN_RECENT_TURN_KEYS = /* @__PURE__ */ new Set(["role", "text"]);
+var BEFORE_TURN_POLICY_KEYS = /* @__PURE__ */ new Set([
+  "enableDurableRecall",
+  "enableProcedureSuggestion",
+  "maxRecentTurns",
+  "maxQueryChars",
+  "maxDurableEntries",
+  "maxHighConfidenceDurableEntries",
+  "maxProcedureCandidates",
+  "recallThreshold",
+  "highConfidenceRecallThreshold",
+  "procedureThreshold",
+  "skipTrivialTurns",
+  "requireTurnSignal"
+]);
+var OPTIONS_KEYS = /* @__PURE__ */ new Set(["includeDiagnostics", "includeRenderedPatch", "includeTimings", "includeDebugArtifact", "topKCandidates"]);
+var BeforeTurnEvalRequestValidationError = class extends Error {
+  /** Parseable case identifier echoed for invalid request correlation when available. */
+  caseId;
+  /** Structured list of request validation issues. */
+  issues;
+  /**
+   * Creates a request validation error with stable issue details.
+   *
+   * @param issues - Structured validation issues collected during parsing.
+   * @param caseId - Parseable request case identifier when available.
+   */
+  constructor(issues, caseId) {
+    super("Invalid before-turn eval request.");
+    this.name = "BeforeTurnEvalRequestValidationError";
+    this.issues = issues;
+    this.caseId = caseId;
+  }
+};
+function parseBeforeTurnEvalCaseRequest(input) {
+  const caseId = extractParseableCaseId(input);
+  if (!isRecord(input)) {
+    throw new BeforeTurnEvalRequestValidationError(
+      [
+        {
+          path: "$",
+          message: "Request body must be a JSON object."
+        }
+      ],
+      caseId
+    );
+  }
+  const issues = [];
+  pushUnexpectedFields(input, ROOT_REQUEST_KEYS, "", issues);
+  const parsedCaseId = parseRequiredTrimmedString(input.caseId, "caseId", issues);
+  const description = parseOptionalTrimmedString(input.description, "description", issues);
+  const sandbox = parseSandbox(input.sandbox, issues);
+  const memoryPool = parseMemoryPool(input.memoryPool, issues);
+  const procedurePool = parseProcedurePool(input.procedurePool, issues);
+  const beforeTurnInput = parseBeforeTurnInput(input.beforeTurnInput, issues);
+  const options = parseOptions(input.options, issues);
+  if (issues.length > 0 || parsedCaseId === void 0 || memoryPool === void 0 || beforeTurnInput === void 0) {
+    throw new BeforeTurnEvalRequestValidationError(issues, caseId);
+  }
+  return {
+    caseId: parsedCaseId,
+    description,
+    sandbox,
+    memoryPool,
+    procedurePool,
+    beforeTurnInput,
+    options
+  };
+}
+function mapBeforeTurnEvalCaseRequestDto(dto) {
+  return {
+    caseId: dto.caseId,
+    description: dto.description,
+    sandbox: mapSandboxRequestDto(dto.sandbox),
+    memoryPool: dto.memoryPool.map((entry) => mapFixtureEntryDto(entry)),
+    procedurePool: dto.procedurePool?.map((procedure) => mapFixtureProcedureDto(procedure)),
+    beforeTurnInput: mapBeforeTurnInputDto(dto.beforeTurnInput),
+    options: mapCaseOptionsDto(dto.options)
+  };
+}
+function parseBeforeTurnInput(value, issues) {
+  const beforeTurnInput = parseObject(value, "beforeTurnInput", issues);
+  if (beforeTurnInput === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(beforeTurnInput, BEFORE_TURN_INPUT_KEYS, "beforeTurnInput", issues);
+  const currentTurnText = parseRequiredString(beforeTurnInput.currentTurnText, "beforeTurnInput.currentTurnText", issues);
+  if (currentTurnText === void 0) {
+    return void 0;
+  }
+  return {
+    sessionKey: parseOptionalTrimmedString(beforeTurnInput.sessionKey, "beforeTurnInput.sessionKey", issues),
+    currentTurnText,
+    recentTurns: parseRecentTurns(beforeTurnInput.recentTurns, issues),
+    trigger: parseOptionalTrimmedString(beforeTurnInput.trigger, "beforeTurnInput.trigger", issues),
+    policy: parseBeforeTurnPolicy(beforeTurnInput.policy, issues)
+  };
+}
+function parseRecentTurns(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    issues.push({
+      path: "beforeTurnInput.recentTurns",
+      message: "Expected an array of recent turns."
+    });
+    return void 0;
+  }
+  return value.flatMap((turn, index) => {
+    const basePath = `beforeTurnInput.recentTurns[${index}]`;
+    const record = parseObject(turn, basePath, issues);
+    if (record === void 0) {
+      return [];
+    }
+    pushUnexpectedFields(record, BEFORE_TURN_RECENT_TURN_KEYS, basePath, issues);
+    const role = parseRecentTurnRole(record.role, `${basePath}.role`, issues);
+    const text = parseRequiredString(record.text, `${basePath}.text`, issues);
+    if (role === void 0 || text === void 0) {
+      return [];
+    }
+    return [{ role, text }];
+  });
+}
+function parseBeforeTurnPolicy(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const policy = parseObject(value, "beforeTurnInput.policy", issues);
+  if (policy === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(policy, BEFORE_TURN_POLICY_KEYS, "beforeTurnInput.policy", issues);
+  return {
+    enableDurableRecall: parseOptionalBoolean(policy.enableDurableRecall, "beforeTurnInput.policy.enableDurableRecall", issues),
+    enableProcedureSuggestion: parseOptionalBoolean(policy.enableProcedureSuggestion, "beforeTurnInput.policy.enableProcedureSuggestion", issues),
+    maxRecentTurns: parseOptionalIntegerInRange(policy.maxRecentTurns, "beforeTurnInput.policy.maxRecentTurns", issues, {
+      min: 0
+    }),
+    maxQueryChars: parseOptionalIntegerInRange(policy.maxQueryChars, "beforeTurnInput.policy.maxQueryChars", issues, {
+      min: 0
+    }),
+    maxDurableEntries: parseOptionalIntegerInRange(policy.maxDurableEntries, "beforeTurnInput.policy.maxDurableEntries", issues, {
+      min: 0
+    }),
+    maxHighConfidenceDurableEntries: parseOptionalIntegerInRange(
+      policy.maxHighConfidenceDurableEntries,
+      "beforeTurnInput.policy.maxHighConfidenceDurableEntries",
+      issues,
+      {
+        min: 0
+      }
+    ),
+    maxProcedureCandidates: parseOptionalIntegerInRange(policy.maxProcedureCandidates, "beforeTurnInput.policy.maxProcedureCandidates", issues, {
+      min: 0
+    }),
+    recallThreshold: parseOptionalThreshold(policy.recallThreshold, "beforeTurnInput.policy.recallThreshold", issues),
+    highConfidenceRecallThreshold: parseOptionalThreshold(policy.highConfidenceRecallThreshold, "beforeTurnInput.policy.highConfidenceRecallThreshold", issues),
+    procedureThreshold: parseOptionalThreshold(policy.procedureThreshold, "beforeTurnInput.policy.procedureThreshold", issues),
+    skipTrivialTurns: parseOptionalBoolean(policy.skipTrivialTurns, "beforeTurnInput.policy.skipTrivialTurns", issues),
+    requireTurnSignal: parseOptionalBoolean(policy.requireTurnSignal, "beforeTurnInput.policy.requireTurnSignal", issues)
+  };
+}
+function parseOptions(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const options = parseObject(value, "options", issues);
+  if (options === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(options, OPTIONS_KEYS, "options", issues);
+  return {
+    includeDiagnostics: parseOptionalBoolean(options.includeDiagnostics, "options.includeDiagnostics", issues),
+    includeRenderedPatch: parseOptionalBoolean(options.includeRenderedPatch, "options.includeRenderedPatch", issues),
+    includeTimings: parseOptionalBoolean(options.includeTimings, "options.includeTimings", issues),
+    includeDebugArtifact: parseOptionalBoolean(options.includeDebugArtifact, "options.includeDebugArtifact", issues),
+    topKCandidates: parseOptionalIntegerInRange(options.topKCandidates, "options.topKCandidates", issues, {
+      min: 1,
+      max: BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K
+    })
+  };
+}
+function mapBeforeTurnInputDto(dto) {
+  return {
+    sessionKey: dto.sessionKey,
+    currentTurnText: dto.currentTurnText,
+    recentTurns: dto.recentTurns?.map((turn) => ({
+      role: turn.role,
+      text: turn.text
+    })),
+    trigger: dto.trigger,
+    policy: mapBeforeTurnPolicyDto(dto.policy)
+  };
+}
+function mapBeforeTurnPolicyDto(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    enableDurableRecall: dto.enableDurableRecall,
+    enableProcedureSuggestion: dto.enableProcedureSuggestion,
+    maxRecentTurns: dto.maxRecentTurns,
+    maxQueryChars: dto.maxQueryChars,
+    maxDurableEntries: dto.maxDurableEntries,
+    maxHighConfidenceDurableEntries: dto.maxHighConfidenceDurableEntries,
+    maxProcedureCandidates: dto.maxProcedureCandidates,
+    recallThreshold: dto.recallThreshold,
+    highConfidenceRecallThreshold: dto.highConfidenceRecallThreshold,
+    procedureThreshold: dto.procedureThreshold,
+    skipTrivialTurns: dto.skipTrivialTurns,
+    requireTurnSignal: dto.requireTurnSignal
+  };
+}
+function mapCaseOptionsDto(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    includeDiagnostics: dto.includeDiagnostics,
+    includeRenderedPatch: dto.includeRenderedPatch,
+    includeTimings: dto.includeTimings,
+    includeDebugArtifact: dto.includeDebugArtifact,
+    topKCandidates: dto.topKCandidates
+  };
+}
+
+// src/adapters/api/routes/internal-before-turn-eval.ts
+var INTERNAL_BEFORE_TURN_EVAL_ROUTE_PATH = "/internal/evals/before-turn/run";
+function createInternalBeforeTurnEvalRoute(optionsOrRunner = {}) {
+  const options = typeof optionsOrRunner === "function" ? { runner: optionsOrRunner } : optionsOrRunner;
+  const crossEncoder = options.crossEncoder;
+  const runner = options.runner ?? ((request) => runBeforeTurnEvalCase(request, { crossEncoder }));
+  return {
+    method: "POST",
+    path: INTERNAL_BEFORE_TURN_EVAL_ROUTE_PATH,
+    handler: async (request) => {
+      let validatedRequest;
+      try {
+        validatedRequest = await parseValidatedRequest(request);
+        const result = await runner(validatedRequest);
+        return jsonResponse(result, 200);
+      } catch (error) {
+        if (error instanceof BeforeTurnEvalRequestValidationError) {
+          return jsonResponse(
+            {
+              status: "error",
+              caseId: error.caseId,
+              error: {
+                code: "invalid_request",
+                message: error.message,
+                details: error.issues
+              }
+            },
+            400
+          );
+        }
+        return jsonResponse(
+          {
+            status: "error",
+            caseId: validatedRequest?.caseId,
+            error: {
+              code: "internal_error",
+              message: "Internal before-turn eval adapter error."
+            }
+          },
+          500
+        );
+      }
+    }
+  };
+}
+var parseJsonBody = async (request) => {
+  try {
+    return await request.json();
+  } catch {
+    throw new BeforeTurnEvalRequestValidationError([
+      {
+        path: "$",
+        message: "Request body must be valid JSON."
+      }
+    ]);
+  }
+};
+var parseValidatedRequest = async (request) => {
+  const payload = await parseJsonBody(request);
+  const requestDto = parseBeforeTurnEvalCaseRequest(payload);
+  return mapBeforeTurnEvalCaseRequestDto(requestDto);
+};
+var jsonResponse = (body, status) => new Response(JSON.stringify(body), {
+  status,
+  headers: {
+    "content-type": "application/json; charset=utf-8"
+  }
+});
+
+// src/app/evals/recall/collect-diagnostics.ts
+function createRecallEvalDiagnosticsCollector(request) {
+  const diagnosticsRequested = wantsRecallEvalDiagnostics(request);
+  const timingsRequested = request.options?.includeTimings === true;
+  const debugArtifactRequested = request.options?.includeDebugArtifact === true;
+  const observationEnabled = diagnosticsRequested || timingsRequested || debugArtifactRequested;
+  const execution = {
+    mode: "isolated-case",
+    provisioning: "exact-fixture-seed",
+    recallPath: request.recallPath ?? "core",
+    memoryPoolCount: request.memoryPool.length,
+    provisionedCount: 0,
+    requestedDiagnostics: request.options?.includeDiagnostics === true,
+    requestedCandidates: request.options?.includeCandidates === true
+  };
+  const stageTimings = {
+    sandboxSetupMs: 0,
+    fixtureProvisionMs: 0,
+    recallMs: 0,
+    queryEmbeddingMs: 0,
+    vectorSearchMs: 0,
+    lexicalSearchMs: 0,
+    mergeCandidatesMs: 0,
+    scoreCandidatesMs: 0,
+    thresholdMs: 0,
+    budgetMs: 0,
+    hydrateEntriesMs: 0,
+    shapeResultsMs: 0,
+    recordRecallEventsMs: 0
+  };
+  const retrieval = {
+    queryEmbeddingDimensions: 0,
+    vectorSearchLimit: 0,
+    lexicalSearchLimit: 0
+  };
+  const candidateCounts = {
+    vectorRetrieved: 0,
+    lexicalRetrieved: 0,
+    merged: 0,
+    thresholdQualified: 0,
+    budgetAccepted: 0,
+    finalRanked: 0,
+    hydrated: 0,
+    returned: 0,
+    telemetryAttempted: 0
+  };
+  let provision;
+  let ranking;
+  let filtering;
+  let claimKey;
+  let rrf;
+  let neighborhood;
+  let mmr;
+  let crossEncoder;
+  let degraded;
+  let provisionObserved = false;
+  let retrievalObserved = false;
+  let traceObserved = false;
+  const traceSink = {
+    reportSummary(summary) {
+      traceObserved = true;
+      ranking = {
+        limit: summary.ranking.limit,
+        threshold: summary.ranking.threshold,
+        budget: summary.ranking.budget,
+        noResultReason: summary.ranking.noResultReason
+      };
+      filtering = {
+        types: [...summary.filtering.types],
+        tags: [...summary.filtering.tags],
+        since: summary.filtering.since,
+        until: summary.filtering.until,
+        around: summary.filtering.around ? {
+          source: summary.filtering.around.source,
+          anchor: summary.filtering.around.anchor,
+          radiusDays: summary.filtering.around.radiusDays
+        } : void 0
+      };
+      candidateCounts.merged = summary.candidateCounts.merged;
+      candidateCounts.thresholdQualified = summary.candidateCounts.thresholdQualified;
+      candidateCounts.budgetAccepted = summary.candidateCounts.budgetAccepted;
+      candidateCounts.finalRanked = summary.candidateCounts.finalRanked;
+      candidateCounts.returned = summary.candidateCounts.returned;
+      claimKey = {
+        historicalBoosted: summary.claimKey.historicalBoosted,
+        tentativeLineageSuppressed: summary.claimKey.tentativeLineageSuppressed,
+        trustPenalized: summary.claimKey.trustPenalized,
+        redundancyPenalized: summary.claimKey.redundancyPenalized
+      };
+      rrf = {
+        applied: summary.rrf.applied,
+        channelCount: summary.rrf.channelCount,
+        rankConstant: summary.rrf.rankConstant,
+        fusedCandidateCount: summary.rrf.fusedCandidateCount,
+        maxFusedScore: summary.rrf.maxFusedScore
+      };
+      neighborhood = {
+        expansionRequested: summary.neighborhood.expansionRequested,
+        expansionAvailable: summary.neighborhood.expansionAvailable,
+        familiesRequested: [...summary.neighborhood.familiesRequested],
+        includeRetired: summary.neighborhood.includeRetired,
+        seedIds: [...summary.neighborhood.seedIds],
+        expansionCandidates: summary.neighborhood.expansionCandidates,
+        strongSeedIds: [...summary.neighborhood.strongSeedIds],
+        rerankBoostedIds: [...summary.neighborhood.rerankBoostedIds]
+      };
+      mmr = {
+        applied: summary.mmr.applied,
+        lambda: summary.mmr.lambda,
+        droppedDuplicateCount: summary.mmr.droppedDuplicateCount,
+        reorderedIds: [...summary.mmr.reorderedIds]
+      };
+      crossEncoder = {
+        applied: summary.crossEncoder.applied,
+        k: summary.crossEncoder.k,
+        alpha: summary.crossEncoder.alpha,
+        latencyMs: summary.crossEncoder.latencyMs,
+        rescoredIds: [...summary.crossEncoder.rescoredIds],
+        ...summary.crossEncoder.degradedReason ? { degradedReason: summary.crossEncoder.degradedReason } : {}
+      };
+      degraded = {
+        active: summary.degraded.active,
+        reasons: [...summary.degraded.reasons],
+        lexicalOnly: summary.degraded.lexicalOnly,
+        notices: [...summary.degraded.notices]
+      };
+      stageTimings.mergeCandidatesMs = summary.timings.mergeCandidatesMs;
+      stageTimings.scoreCandidatesMs = summary.timings.scoreCandidatesMs;
+      stageTimings.thresholdMs = summary.timings.thresholdMs;
+      stageTimings.budgetMs = summary.timings.budgetMs;
+      stageTimings.shapeResultsMs = summary.timings.shapeResultsMs;
+    }
+  };
+  return {
+    traceSink,
+    isObservationEnabled() {
+      return observationEnabled;
+    },
+    buildObservedArtifactFacts() {
+      return {
+        candidateCounts: { ...candidateCounts },
+        ranking: traceObserved && ranking ? { ...ranking } : void 0,
+        degraded: traceObserved && degraded ? {
+          active: degraded.active,
+          reasons: [...degraded.reasons],
+          lexicalOnly: degraded.lexicalOnly,
+          notices: [...degraded.notices]
+        } : void 0,
+        traceObserved
+      };
+    },
+    recordSandboxSetup(durationMs) {
+      stageTimings.sandboxSetupMs = durationMs;
+    },
+    recordFixtureProvisionTiming(durationMs) {
+      stageTimings.fixtureProvisionMs = durationMs;
+    },
+    recordProvision(result, durationMs) {
+      provisionObserved = true;
+      execution.provisionedCount = result.provisionedCount;
+      stageTimings.fixtureProvisionMs = durationMs;
+      provision = {
+        requestedCount: request.memoryPool.length,
+        provisionedCount: result.provisionedCount,
+        providedIdCount: result.providedIdCount,
+        generatedIdCount: result.generatedIdCount,
+        retiredCount: result.retiredCount,
+        supersededCount: result.supersededCount,
+        createdAtDefaultedCount: result.createdAtDefaultedCount,
+        updatedAtDefaultedCount: result.updatedAtDefaultedCount,
+        seededEntries: result.seededEntries.map((entry) => ({
+          id: entry.id,
+          created_at: entry.created_at,
+          updated_at: entry.updated_at,
+          retired: entry.retired,
+          superseded_by: entry.superseded_by,
+          claim_key: entry.claim_key,
+          claim_key_status: entry.claim_key_status,
+          valid_from: entry.valid_from,
+          valid_to: entry.valid_to
+        }))
+      };
+    },
+    recordRecall(durationMs) {
+      stageTimings.recallMs = durationMs;
+    },
+    recordQueryEmbedding(params) {
+      retrievalObserved = true;
+      stageTimings.queryEmbeddingMs = params.durationMs;
+      retrieval.queryEmbeddingDimensions = params.dimensions;
+    },
+    recordVectorSearch(params) {
+      retrievalObserved = true;
+      stageTimings.vectorSearchMs = params.durationMs;
+      retrieval.vectorSearchLimit = params.limit;
+      candidateCounts.vectorRetrieved = params.count;
+    },
+    recordLexicalSearch(params) {
+      retrievalObserved = true;
+      stageTimings.lexicalSearchMs = params.durationMs;
+      retrieval.lexicalSearchLimit = params.limit;
+      candidateCounts.lexicalRetrieved = params.count;
+    },
+    recordHydrateEntries(params) {
+      retrievalObserved = true;
+      stageTimings.hydrateEntriesMs = params.durationMs;
+      candidateCounts.hydrated = params.count;
+    },
+    recordRecallTelemetry(params) {
+      retrievalObserved = true;
+      stageTimings.recordRecallEventsMs = params.durationMs;
+      candidateCounts.telemetryAttempted = params.entryCount;
+    },
+    buildDiagnostics() {
+      if (!diagnosticsRequested) {
+        return void 0;
+      }
+      return {
+        execution,
+        provision: provisionObserved ? provision : void 0,
+        retrieval: retrievalObserved ? retrieval : void 0,
+        ranking: traceObserved ? ranking : void 0,
+        filtering: traceObserved ? filtering : void 0,
+        claimKey: traceObserved ? claimKey : void 0,
+        rrf: traceObserved ? rrf : void 0,
+        neighborhood: traceObserved ? neighborhood : void 0,
+        mmr: traceObserved ? mmr : void 0,
+        crossEncoder: traceObserved ? crossEncoder : void 0,
+        degraded: traceObserved ? degraded : void 0,
+        candidateCounts
+      };
+    },
+    buildTimings(totalMs) {
+      if (!timingsRequested) {
+        return void 0;
+      }
+      return {
+        totalMs,
+        sandboxSetupMs: stageTimings.sandboxSetupMs,
+        fixtureProvisionMs: stageTimings.fixtureProvisionMs,
+        recallMs: stageTimings.recallMs,
+        queryEmbeddingMs: stageTimings.queryEmbeddingMs,
+        vectorSearchMs: stageTimings.vectorSearchMs,
+        lexicalSearchMs: stageTimings.lexicalSearchMs,
+        mergeCandidatesMs: stageTimings.mergeCandidatesMs,
+        scoreCandidatesMs: stageTimings.scoreCandidatesMs,
+        thresholdMs: stageTimings.thresholdMs,
+        budgetMs: stageTimings.budgetMs,
+        hydrateEntriesMs: stageTimings.hydrateEntriesMs,
+        shapeResultsMs: stageTimings.shapeResultsMs,
+        recordRecallEventsMs: stageTimings.recordRecallEventsMs
+      };
+    }
+  };
+}
+function wantsRecallEvalDiagnostics(request) {
+  return request.options?.includeDiagnostics === true || request.options?.includeCandidates === true;
+}
+
+// src/app/evals/recall/instrumented-recall-ports.ts
+function createInstrumentedRecallPorts(ports, observer) {
+  return {
+    async embed(text) {
+      const startedAt = Date.now();
+      try {
+        const embedding = await ports.embed(text);
+        observer.recordQueryEmbedding({
+          durationMs: elapsedMs2(startedAt),
+          dimensions: embedding.length
+        });
+        return embedding;
+      } catch (error) {
+        observer.recordQueryEmbedding({
+          durationMs: elapsedMs2(startedAt),
+          dimensions: 0
+        });
+        throw error;
+      }
+    },
+    async vectorSearch(params) {
+      const startedAt = Date.now();
+      try {
+        const results = await ports.vectorSearch(params);
+        observer.recordVectorSearch({
+          durationMs: elapsedMs2(startedAt),
+          count: results.length,
+          limit: params.limit
+        });
+        return results;
+      } catch (error) {
+        observer.recordVectorSearch({
+          durationMs: elapsedMs2(startedAt),
+          count: 0,
+          limit: params.limit
+        });
+        throw error;
+      }
+    },
+    async ftsSearch(params) {
+      const startedAt = Date.now();
+      try {
+        const results = await ports.ftsSearch(params);
+        observer.recordLexicalSearch({
+          durationMs: elapsedMs2(startedAt),
+          count: results.length,
+          limit: params.limit
+        });
+        return results;
+      } catch (error) {
+        observer.recordLexicalSearch({
+          durationMs: elapsedMs2(startedAt),
+          count: 0,
+          limit: params.limit
+        });
+        throw error;
+      }
+    },
+    ...ports.expandNeighborhood ? {
+      async expandNeighborhood(request) {
+        return ports.expandNeighborhood(request);
+      }
+    } : {},
+    // Cross-encoder is an optional port: proxy it when available so the
+    // core recall pipeline sees the same rerank surface as in production,
+    // and the diagnostics collector can report the `crossEncoder` trace
+    // branch exactly as the core emits it. Dropping the proxy here would
+    // silently convert rerank-aware eval cases into rerank-disabled runs.
+    ...ports.crossEncoder ? {
+      crossEncoder: ports.crossEncoder
+    } : {},
+    async hydrateEntries(ids) {
+      const startedAt = Date.now();
+      try {
+        const entries = await ports.hydrateEntries(ids);
+        observer.recordHydrateEntries({
+          durationMs: elapsedMs2(startedAt),
+          count: entries.length
+        });
+        return entries;
+      } catch (error) {
+        observer.recordHydrateEntries({
+          durationMs: elapsedMs2(startedAt),
+          count: 0
+        });
+        throw error;
+      }
+    },
+    async recordRecallEvents(params) {
+      const startedAt = Date.now();
+      try {
+        await ports.recordRecallEvents(params);
+      } finally {
+        observer.recordRecallTelemetry({
+          durationMs: elapsedMs2(startedAt),
+          entryCount: params.entryIds.length
+        });
+      }
+    }
+  };
+}
+function elapsedMs2(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+// src/app/evals/recall/build-debug-artifact.ts
+function buildRecallDebugArtifact(params) {
+  const { request, results, projectedEntries, sandbox, observed } = params;
+  const recallPath = request.recallPath ?? "core";
+  const entryResults = Array.isArray(results) ? results : results.entries;
+  const selectedEntryIds = entryResults.map((result) => result.entry.id);
+  const topK = resolveTopK2(request.options?.topKCandidates);
+  const reasonsByEntryId = /* @__PURE__ */ new Map();
+  for (const entry of projectedEntries) {
+    if (entry.whySurfaced.reasons.length > 0) {
+      reasonsByEntryId.set(entry.entryId, [...entry.whySurfaced.reasons]);
+    }
+  }
+  const topCandidates = buildTopCandidates(entryResults, reasonsByEntryId, topK);
+  const artifact = {
+    schemaVersion: "recall-debug-artifact.v1",
+    caseId: request.caseId,
+    ...sandbox.snapshot ? { snapshot: buildSnapshot2(sandbox.snapshot) } : {},
+    request: {
+      recallPath,
+      query: request.recallRequest.text
+    },
+    ...Array.isArray(results) ? {} : { routing: results.routing },
+    ...observed.traceObserved ? { candidateCounts: observed.candidateCounts } : {},
+    ...observed.ranking ? { ranking: observed.ranking } : {},
+    ...observed.degraded ? { degraded: observed.degraded } : {},
+    selectedEntryIds,
+    ...topCandidates.length > 0 ? { topCandidates } : {}
+  };
+  return artifact;
+}
+function buildSnapshot2(snapshot) {
+  return {
+    ...snapshot.id !== void 0 ? { id: snapshot.id } : {},
+    ...snapshot.label !== void 0 ? { label: snapshot.label } : {},
+    dbPathBasename: snapshot.dbPathBasename
+  };
+}
+function resolveTopK2(requested) {
+  if (requested === void 0) {
+    return RECALL_DEBUG_ARTIFACT_DEFAULT_TOP_K;
+  }
+  if (!Number.isFinite(requested) || !Number.isInteger(requested)) {
+    return RECALL_DEBUG_ARTIFACT_DEFAULT_TOP_K;
+  }
+  if (requested < 1) {
+    return 1;
+  }
+  if (requested > RECALL_DEBUG_ARTIFACT_MAX_TOP_K) {
+    return RECALL_DEBUG_ARTIFACT_MAX_TOP_K;
+  }
+  return requested;
+}
+function buildTopCandidates(entryResults, reasonsByEntryId, topK) {
+  const sliced = entryResults.slice(0, topK);
+  return sliced.map((result) => {
+    const reasons = reasonsByEntryId.get(result.entry.id);
+    return {
+      id: result.entry.id,
+      score: result.score,
+      lexicalScore: result.scores.lexical,
+      vectorScore: result.scores.vector,
+      recencyScore: result.scores.recency,
+      importanceScore: result.scores.importance,
+      ...reasons && reasons.length > 0 ? { reasons } : {}
+    };
+  });
+}
+
+// src/app/evals/recall/normalize-response.ts
+function buildRecallEvalSuccessResponse(params) {
+  const entryResults = Array.isArray(params.results) ? params.results : params.results.entries;
+  const projectedEntries = Array.isArray(params.results) ? entryResults.map((result) => projectClaimCentricRecallEntry(result, { asOf: params.request.recallRequest.asOf })) : params.results.projectedEntries;
+  const metadata = buildMetadata(params.request, params.results, projectedEntries);
+  const debugArtifact = params.request.options?.includeDebugArtifact === true && params.observedArtifactFacts ? buildRecallDebugArtifact({
+    request: params.request,
+    results: params.results,
+    projectedEntries,
+    sandbox: params.sandbox,
+    observed: params.observedArtifactFacts
+  }) : void 0;
+  return {
+    status: "ok",
+    caseId: params.request.caseId,
+    result: {
+      entries: entryResults.map((result, index) => ({
+        id: result.entry.id,
+        subject: result.entry.subject,
+        content: result.entry.content,
+        type: result.entry.type,
+        importance: result.entry.importance,
+        expiry: result.entry.expiry,
+        tags: result.entry.tags,
+        created_at: result.entry.created_at,
+        score: result.score,
+        scores: result.scores,
+        claim: {
+          familyKey: projectedEntries[index]?.familyKey ?? `entry:${result.entry.id}`,
+          claimKey: projectedEntries[index]?.claimKey,
+          slotPolicy: projectedEntries[index]?.slotPolicy ?? "exclusive",
+          memoryState: projectedEntries[index]?.memoryState ?? "current",
+          claimStatus: projectedEntries[index]?.claimStatus ?? "no_key",
+          freshness: projectedEntries[index]?.freshness ?? {
+            createdAt: result.entry.created_at,
+            isCurrent: true,
+            label: `created ${result.entry.created_at} | current state`
+          },
+          provenance: projectedEntries[index]?.provenance ?? {},
+          whySurfaced: projectedEntries[index]?.whySurfaced ?? {
+            summary: `ranked score ${result.score.toFixed(2)}`,
+            reasons: []
+          }
+        }
+      })),
+      entryIds: entryResults.map((result) => result.entry.id)
+    },
+    metadata,
+    diagnostics: params.diagnostics,
+    timings: params.timings,
+    sandbox: buildSandboxResult2(params.sandbox),
+    ...debugArtifact ? { debugArtifact } : {}
+  };
+}
+function buildRecallEvalErrorResponse(params) {
+  return {
+    status: "error",
+    caseId: params.request.caseId,
+    error: {
+      code: params.code,
+      message: params.message,
+      details: params.details
+    },
+    diagnostics: params.diagnostics,
+    timings: params.timings,
+    sandbox: params.sandbox ? buildSandboxResult2(params.sandbox) : void 0
+  };
+}
+function buildSandboxResult2(sandbox) {
+  return {
+    root: sandbox.root,
+    dbPath: sandbox.dbPath,
+    preserved: sandbox.preserved,
+    ...sandbox.snapshot ? { snapshot: sandbox.snapshot } : {}
+  };
+}
+function buildMetadata(request, results, projectedEntries) {
+  if (Array.isArray(results)) {
+    return {
+      path: request.recallPath ?? "core",
+      claim: {
+        projectedEntries: projectedEntries.map(buildProjectedEntryMetadata)
+      }
+    };
+  }
+  return {
+    path: "unified",
+    claim: {
+      projectedEntries: projectedEntries.map(buildProjectedEntryMetadata),
+      entryFamilies: results.entryFamilies.map(buildClaimFamilyMetadata),
+      transitions: results.claimTransitions
+    },
+    unified: {
+      routing: results.routing,
+      timeWindow: results.timeWindow,
+      asOf: results.asOf,
+      procedure: results.procedure ? {
+        id: results.procedure.id,
+        procedureKey: results.procedure.procedure_key,
+        title: results.procedure.title,
+        goal: results.procedure.goal
+      } : void 0,
+      procedureCandidates: results.procedureCandidates.map((candidate) => ({
+        id: candidate.procedure.id,
+        procedureKey: candidate.procedure.procedure_key,
+        title: candidate.procedure.title,
+        score: candidate.score,
+        lexicalScore: candidate.scores.lexical,
+        vectorScore: candidate.scores.vector
+      })),
+      procedureNotices: results.procedureNotices,
+      notices: results.notices,
+      episodeCount: results.episodes.length
+    }
+  };
+}
+function buildProjectedEntryMetadata(entry) {
+  return {
+    entryId: entry.entryId,
+    familyKey: entry.familyKey,
+    claimKey: entry.claimKey,
+    slotPolicy: entry.slotPolicy,
+    memoryState: entry.memoryState,
+    claimStatus: entry.claimStatus,
+    freshness: entry.freshness,
+    provenance: entry.provenance,
+    whySurfaced: entry.whySurfaced
+  };
+}
+function buildClaimFamilyMetadata(family) {
+  return {
+    familyKey: family.familyKey,
+    claimKey: family.claimKey,
+    slotPolicy: family.slotPolicy,
+    subject: family.subject,
+    primaryEntryId: family.primary.entryId,
+    entries: family.entries.map((entry) => ({
+      id: entry.entryId,
+      memoryState: entry.memoryState,
+      claimStatus: entry.claimStatus
+    }))
+  };
+}
+
+// src/app/evals/recall/run-recall-eval-case.ts
+async function runRecallEvalCase(request, dependencies = {}) {
+  const startedAt = Date.now();
+  const provisionedAt = new Date(startedAt).toISOString();
+  const diagnostics = createRecallEvalDiagnosticsCollector(request);
+  const recallPath = request.recallPath ?? "core";
+  let sandbox;
+  let sharedEmbeddingPort;
+  let sharedEmbeddingError;
+  const getEmbeddingSupport = () => {
+    if (sharedEmbeddingPort) {
+      return {
+        available: true,
+        port: sharedEmbeddingPort
+      };
+    }
+    if (sharedEmbeddingError) {
+      return {
+        available: false,
+        error: sharedEmbeddingError
+      };
+    }
+    const config = readConfig();
+    try {
+      sharedEmbeddingPort = createEmbeddingClient(resolveEmbeddingApiKey(config), resolveEmbeddingModel(config));
+      return {
+        available: true,
+        port: sharedEmbeddingPort
+      };
+    } catch (error) {
+      sharedEmbeddingError = error instanceof Error ? error.message : String(error);
+      return {
+        available: false,
+        error: sharedEmbeddingError
+      };
+    }
+  };
+  const getEmbeddingPort = () => {
+    const support = getEmbeddingSupport();
+    if (!support.port) {
+      throw new Error(support.error ?? "Embeddings are unavailable.");
+    }
+    return support.port;
+  };
+  try {
+    const sandboxStartedAt = Date.now();
+    try {
+      sandbox = await setupRecallEvalSandbox(request.sandbox);
+      diagnostics.recordSandboxSetup(elapsedMs3(sandboxStartedAt));
+    } catch (error) {
+      diagnostics.recordSandboxSetup(elapsedMs3(sandboxStartedAt));
+      return buildRecallEvalErrorResponse({
+        request,
+        code: "sandbox_setup_failed",
+        message: "Failed to create isolated recall eval sandbox.",
+        details: toErrorDetails2(error),
+        diagnostics: diagnostics.buildDiagnostics(),
+        timings: diagnostics.buildTimings(elapsedMs3(startedAt))
+      });
+    }
+    if (request.memoryPool.length > 0 || (request.procedurePool?.length ?? 0) > 0) {
+      const provisionStartedAt = Date.now();
+      try {
+        let entryProvisionResult;
+        if (request.memoryPool.length > 0) {
+          entryProvisionResult = await provisionRecallEvalFixtures({
+            caseId: request.caseId,
+            memoryPool: request.memoryPool,
+            store: sandbox.fixtureStore,
+            embedding: getEmbeddingPort(),
+            provisionedAt
+          });
+        }
+        if ((request.procedurePool?.length ?? 0) > 0) {
+          await provisionRecallEvalProcedureFixtures({
+            caseId: request.caseId,
+            procedurePool: request.procedurePool ?? [],
+            store: sandbox.fixtureStore,
+            provisionedAt
+          });
+        }
+        if (entryProvisionResult) {
+          diagnostics.recordProvision(entryProvisionResult, elapsedMs3(provisionStartedAt));
+        } else {
+          diagnostics.recordFixtureProvisionTiming(elapsedMs3(provisionStartedAt));
+        }
+      } catch (error) {
+        diagnostics.recordFixtureProvisionTiming(elapsedMs3(provisionStartedAt));
+        return buildRecallEvalErrorResponse({
+          request,
+          code: "fixture_provision_failed",
+          message: "Failed to provision recall eval fixtures into isolated storage.",
+          details: toErrorDetails2(error),
+          diagnostics: diagnostics.buildDiagnostics(),
+          timings: diagnostics.buildTimings(elapsedMs3(startedAt)),
+          sandbox
+        });
+      }
+    }
+    const recallStartedAt = Date.now();
+    try {
+      const embeddingSupport = getEmbeddingSupport();
+      const recallEmbeddingPort = request.options?.faultInjection?.queryEmbeddingFailure === true ? createUnavailableEmbeddingPort2("Injected recall eval query embedding failure.") : embeddingSupport.port ?? createUnavailableEmbeddingPort2(embeddingSupport.error ?? "Embeddings are unavailable.");
+      const sandboxPorts = sandbox.createRecallPorts(recallEmbeddingPort);
+      const portsWithCrossEncoder = attachCrossEncoderPort(sandboxPorts, dependencies.crossEncoder);
+      const telemetryGatedPorts = applyTelemetryWriteGate(portsWithCrossEncoder, sandbox);
+      const basePorts = applyRecallEvalFaultInjection(telemetryGatedPorts, request);
+      const recallPorts = diagnostics.isObservationEnabled() ? createInstrumentedRecallPorts(basePorts, diagnostics) : basePorts;
+      const slotPolicyConfig = request.unified?.memoryPolicy?.slotPolicies;
+      const rankingPolicy = request.recallRequest.rankingPolicy;
+      const unifiedRecallOptions = {
+        ...slotPolicyConfig ? { slotPolicyConfig } : {},
+        ...rankingPolicy ? { rankingPolicy } : {},
+        ...diagnostics.isObservationEnabled() ? { trace: diagnostics.traceSink } : {}
+      };
+      const coreRecallOptions = {
+        ...rankingPolicy ? { rankingPolicy } : {},
+        ...diagnostics.isObservationEnabled() ? { trace: diagnostics.traceSink } : {}
+      };
+      const results = recallPath === "unified" ? await runUnifiedRecall(
+        {
+          text: request.recallRequest.text,
+          ...request.unified?.mode ? { mode: request.unified.mode } : {},
+          ...request.recallRequest.limit !== void 0 ? { limit: request.recallRequest.limit } : {},
+          ...request.recallRequest.threshold !== void 0 ? { threshold: request.recallRequest.threshold } : {},
+          ...request.recallRequest.types && request.recallRequest.types.length > 0 ? { types: request.recallRequest.types } : {},
+          ...request.recallRequest.tags && request.recallRequest.tags.length > 0 ? { tags: request.recallRequest.tags } : {},
+          ...request.recallRequest.asOf ? { asOf: request.recallRequest.asOf } : {},
+          ...request.unified?.sessionKey ? { sessionKey: request.unified.sessionKey } : {}
+        },
+        {
+          database: sandbox.episodeDatabase,
+          procedures: sandbox.procedureDatabase,
+          recall: recallPorts,
+          embeddingAvailable: embeddingSupport.available,
+          ...embeddingSupport.error ? { embeddingError: embeddingSupport.error } : {},
+          ...slotPolicyConfig ? { claimSlotPolicyConfig: slotPolicyConfig } : {},
+          ...embeddingSupport.available ? {
+            embedQuery: async (text) => {
+              const vectors = await recallEmbeddingPort.embed([text]);
+              return vectors[0] ?? [];
+            }
+          } : {},
+          ...Object.keys(unifiedRecallOptions).length > 0 ? { recallOptions: unifiedRecallOptions } : {}
+        }
+      ) : await recall(request.recallRequest, recallPorts, Object.keys(coreRecallOptions).length > 0 ? coreRecallOptions : void 0);
+      diagnostics.recordRecall(elapsedMs3(recallStartedAt));
+      return buildRecallEvalSuccessResponse({
+        request,
+        results,
+        diagnostics: diagnostics.buildDiagnostics(),
+        timings: diagnostics.buildTimings(elapsedMs3(startedAt)),
+        sandbox,
+        observedArtifactFacts: request.options?.includeDebugArtifact === true ? diagnostics.buildObservedArtifactFacts() : void 0
+      });
+    } catch (error) {
+      diagnostics.recordRecall(elapsedMs3(recallStartedAt));
+      return buildRecallEvalErrorResponse({
+        request,
+        code: "recall_execution_failed",
+        message: "Failed to execute real recall against isolated eval state.",
+        details: toErrorDetails2(error),
+        diagnostics: diagnostics.buildDiagnostics(),
+        timings: diagnostics.buildTimings(elapsedMs3(startedAt)),
+        sandbox
+      });
+    }
+  } catch (error) {
+    return buildRecallEvalErrorResponse({
+      request,
+      code: "internal_error",
+      message: "Recall eval execution failed unexpectedly.",
+      details: toErrorDetails2(error),
+      diagnostics: diagnostics.buildDiagnostics(),
+      timings: diagnostics.buildTimings(elapsedMs3(startedAt)),
+      sandbox
+    });
+  } finally {
+    await sandbox?.cleanup().catch(() => void 0);
+  }
+}
+function toErrorDetails2(error) {
+  if (error instanceof Error) {
+    return {
+      cause: error.message
+    };
+  }
+  return {
+    cause: String(error)
+  };
+}
+function createUnavailableEmbeddingPort2(message) {
+  return {
+    async embed() {
+      throw new Error(message);
+    }
+  };
+}
+function applyRecallEvalFaultInjection(ports, request) {
+  if (request.options?.faultInjection?.vectorSearchFailure !== true) {
+    return ports;
+  }
+  return {
+    async embed(text) {
+      return ports.embed(text);
+    },
+    async vectorSearch() {
+      throw new Error("Injected recall eval vector search failure.");
+    },
+    async ftsSearch(params) {
+      return ports.ftsSearch(params);
+    },
+    ...ports.expandNeighborhood ? {
+      async expandNeighborhood(request2) {
+        return ports.expandNeighborhood(request2);
+      }
+    } : {},
+    // Cross-encoder remains wired during fault injection so rerank-aware
+    // cases can still observe the rerank stage running after the core
+    // recall pipeline falls back to lexical-only retrieval. Preserving
+    // the port is safe because the core helper fails closed on adapter
+    // errors and honors the ranking policy kill switch.
+    ...ports.crossEncoder ? {
+      crossEncoder: ports.crossEncoder
+    } : {},
+    async hydrateEntries(ids) {
+      return ports.hydrateEntries(ids);
+    },
+    async recordRecallEvents(params) {
+      return ports.recordRecallEvents(params);
+    }
+  };
+}
+function elapsedMs3(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+// src/adapters/api/validation/recall-eval-request.ts
+var ROOT_REQUEST_KEYS2 = /* @__PURE__ */ new Set(["caseId", "description", "recallPath", "sandbox", "memoryPool", "recallRequest", "unified", "options"]);
+var RECALL_REQUEST_KEYS = /* @__PURE__ */ new Set([
+  "text",
+  "limit",
+  "threshold",
+  "budget",
+  "types",
+  "tags",
+  "since",
+  "until",
+  "around",
+  "aroundRadius",
+  "asOf",
+  "rankingProfile",
+  "rankingPolicy"
+]);
+var RANKING_POLICY_KEYS = /* @__PURE__ */ new Set([
+  "rrf",
+  "rrfRankConstant",
+  "rrfSmallPoolRankConstant",
+  "neighborhood",
+  "mmr",
+  "mmrLambda",
+  "mmrMinPoolSize",
+  "crossEncoder",
+  "crossEncoderTopK",
+  "crossEncoderAlpha"
+]);
+var UNIFIED_REQUEST_KEYS = /* @__PURE__ */ new Set(["mode", "sessionKey", "memoryPolicy"]);
+var UNIFIED_MEMORY_POLICY_KEYS = /* @__PURE__ */ new Set(["slotPolicies"]);
+var SLOT_POLICY_KEYS = /* @__PURE__ */ new Set(["attributeHeads"]);
+var OPTIONS_KEYS2 = /* @__PURE__ */ new Set(["includeDiagnostics", "includeCandidates", "includeTimings", "includeDebugArtifact", "topKCandidates", "faultInjection"]);
+var FAULT_INJECTION_KEYS = /* @__PURE__ */ new Set(["queryEmbeddingFailure", "vectorSearchFailure"]);
+var RECALL_PATHS = ["core", "unified"];
+var RECALL_RANKING_PROFILES = ["historical_state"];
+var RANKING_POLICY_TOGGLES = ["enabled", "disabled"];
+var UNIFIED_RECALL_MODES = ["auto", "entries", "episodes"];
+var CLAIM_SLOT_POLICIES = ["exclusive", "multivalued"];
+var RecallEvalRequestValidationError = class extends Error {
+  /** Parseable case identifier echoed for invalid request correlation when available. */
+  caseId;
+  /** Structured list of request validation issues. */
+  issues;
+  /**
+   * Creates a request validation error with stable issue details.
+   *
+   * @param issues - Structured validation issues collected during parsing.
+   * @param caseId - Parseable request case identifier when available.
+   */
+  constructor(issues, caseId) {
+    super("Invalid recall eval request.");
+    this.name = "RecallEvalRequestValidationError";
+    this.issues = issues;
+    this.caseId = caseId;
+  }
+};
+function parseRecallEvalCaseRequest(input) {
+  const caseId = extractParseableCaseId(input);
+  if (!isRecord(input)) {
+    throw new RecallEvalRequestValidationError(
+      [
+        {
+          path: "$",
+          message: "Request body must be a JSON object."
+        }
+      ],
+      caseId
+    );
+  }
+  const issues = [];
+  pushUnexpectedFields(input, ROOT_REQUEST_KEYS2, "", issues);
+  const parsedCaseId = parseRequiredTrimmedString(input.caseId, "caseId", issues);
+  const description = parseOptionalTrimmedString(input.description, "description", issues);
+  const recallPath = parseOptionalRecallPath(input.recallPath, "recallPath", issues);
+  const sandbox = parseSandbox(input.sandbox, issues);
+  const memoryPool = parseMemoryPool(input.memoryPool, issues);
+  const recallRequest = parseRecallRequest(input.recallRequest, issues);
+  const unified = parseUnifiedRequest(input.unified, issues);
+  const options = parseOptions2(input.options, issues);
+  validatePathSpecificRequest(recallPath, recallRequest, unified, issues);
+  if (issues.length > 0 || parsedCaseId === void 0 || memoryPool === void 0 || recallRequest === void 0) {
+    throw new RecallEvalRequestValidationError(issues, caseId);
+  }
+  return {
+    caseId: parsedCaseId,
+    description,
+    recallPath,
+    sandbox,
+    memoryPool,
+    recallRequest,
+    unified,
+    options
+  };
+}
+function mapRecallEvalCaseRequestDto(dto) {
+  return {
+    caseId: dto.caseId,
+    description: dto.description,
+    recallPath: dto.recallPath,
+    sandbox: mapSandboxRequestDto2(dto.sandbox),
+    memoryPool: dto.memoryPool.map(mapFixtureEntryDto2),
+    recallRequest: mapRecallRequestDto(dto.recallRequest),
+    unified: mapUnifiedRequestDto(dto.unified),
+    options: mapCaseOptionsDto2(dto.options)
+  };
+}
+function parseRecallRequest(value, issues) {
+  const recallRequest = parseObject(value, "recallRequest", issues);
+  if (recallRequest === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(recallRequest, RECALL_REQUEST_KEYS, "recallRequest", issues);
+  const text = parseRequiredTrimmedString(recallRequest.text, "recallRequest.text", issues);
+  if (text === void 0) {
+    return void 0;
+  }
+  return {
+    text,
+    limit: parseOptionalIntegerInRange(recallRequest.limit, "recallRequest.limit", issues, {
+      min: 0
+    }),
+    threshold: parseOptionalThreshold(recallRequest.threshold, "recallRequest.threshold", issues),
+    budget: parseOptionalIntegerInRange(recallRequest.budget, "recallRequest.budget", issues, {
+      min: 0
+    }),
+    types: parseOptionalEntryTypeArray(recallRequest.types, "recallRequest.types", issues),
+    tags: parseOptionalStringArray(recallRequest.tags, "recallRequest.tags", issues),
+    since: parseOptionalTrimmedString(recallRequest.since, "recallRequest.since", issues),
+    until: parseOptionalTrimmedString(recallRequest.until, "recallRequest.until", issues),
+    around: parseOptionalTrimmedString(recallRequest.around, "recallRequest.around", issues),
+    aroundRadius: parseOptionalIntegerInRange(recallRequest.aroundRadius, "recallRequest.aroundRadius", issues, {
+      min: 1
+    }),
+    asOf: parseOptionalTrimmedString(recallRequest.asOf, "recallRequest.asOf", issues),
+    rankingProfile: parseOptionalRankingProfile(recallRequest.rankingProfile, "recallRequest.rankingProfile", issues),
+    rankingPolicy: parseOptionalRankingPolicy(recallRequest.rankingPolicy, "recallRequest.rankingPolicy", issues)
+  };
+}
+function parseOptionalRankingPolicy(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const policy = parseObject(value, path2, issues);
+  if (policy === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(policy, RANKING_POLICY_KEYS, path2, issues);
+  const parsed = {};
+  const rrf = parseOptionalStageToggle(policy.rrf, `${path2}.rrf`, issues);
+  if (rrf !== void 0) {
+    parsed.rrf = rrf;
+  }
+  const rrfRankConstant = parseOptionalIntegerInRange(policy.rrfRankConstant, `${path2}.rrfRankConstant`, issues, {
+    min: 1
+  });
+  if (rrfRankConstant !== void 0) {
+    parsed.rrfRankConstant = rrfRankConstant;
+  }
+  const rrfSmallPoolRankConstant = parseOptionalIntegerInRange(policy.rrfSmallPoolRankConstant, `${path2}.rrfSmallPoolRankConstant`, issues, { min: 1 });
+  if (rrfSmallPoolRankConstant !== void 0) {
+    parsed.rrfSmallPoolRankConstant = rrfSmallPoolRankConstant;
+  }
+  const neighborhood = parseOptionalStageToggle(policy.neighborhood, `${path2}.neighborhood`, issues);
+  if (neighborhood !== void 0) {
+    parsed.neighborhood = neighborhood;
+  }
+  const mmr = parseOptionalStageToggle(policy.mmr, `${path2}.mmr`, issues);
+  if (mmr !== void 0) {
+    parsed.mmr = mmr;
+  }
+  const mmrLambda = parseOptionalUnitInterval(policy.mmrLambda, `${path2}.mmrLambda`, issues);
+  if (mmrLambda !== void 0) {
+    parsed.mmrLambda = mmrLambda;
+  }
+  const mmrMinPoolSize = parseOptionalIntegerInRange(policy.mmrMinPoolSize, `${path2}.mmrMinPoolSize`, issues, {
+    min: 0
+  });
+  if (mmrMinPoolSize !== void 0) {
+    parsed.mmrMinPoolSize = mmrMinPoolSize;
+  }
+  const crossEncoder = parseOptionalStageToggle(policy.crossEncoder, `${path2}.crossEncoder`, issues);
+  if (crossEncoder !== void 0) {
+    parsed.crossEncoder = crossEncoder;
+  }
+  const crossEncoderTopK = parseOptionalIntegerInRange(policy.crossEncoderTopK, `${path2}.crossEncoderTopK`, issues, {
+    min: 1
+  });
+  if (crossEncoderTopK !== void 0) {
+    parsed.crossEncoderTopK = crossEncoderTopK;
+  }
+  const crossEncoderAlpha = parseOptionalUnitInterval(policy.crossEncoderAlpha, `${path2}.crossEncoderAlpha`, issues);
+  if (crossEncoderAlpha !== void 0) {
+    parsed.crossEncoderAlpha = crossEncoderAlpha;
+  }
+  return Object.keys(parsed).length > 0 ? parsed : void 0;
+}
+function parseOptionalStageToggle(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !RANKING_POLICY_TOGGLES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${RANKING_POLICY_TOGGLES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalUnitInterval(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    pushIssue(issues, path2, "Expected a number from 0 to 1.");
+    return void 0;
+  }
+  return value;
+}
+function parseUnifiedRequest(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const unified = parseObject(value, "unified", issues);
+  if (unified === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(unified, UNIFIED_REQUEST_KEYS, "unified", issues);
+  return {
+    mode: parseOptionalUnifiedRecallMode(unified.mode, "unified.mode", issues),
+    sessionKey: parseOptionalTrimmedString(unified.sessionKey, "unified.sessionKey", issues),
+    memoryPolicy: parseUnifiedMemoryPolicy(unified.memoryPolicy, issues)
+  };
+}
+function parseOptions2(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const options = parseObject(value, "options", issues);
+  if (options === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(options, OPTIONS_KEYS2, "options", issues);
+  return {
+    includeDiagnostics: parseOptionalBoolean(options.includeDiagnostics, "options.includeDiagnostics", issues),
+    includeCandidates: parseOptionalBoolean(options.includeCandidates, "options.includeCandidates", issues),
+    includeTimings: parseOptionalBoolean(options.includeTimings, "options.includeTimings", issues),
+    includeDebugArtifact: parseOptionalBoolean(options.includeDebugArtifact, "options.includeDebugArtifact", issues),
+    topKCandidates: parseOptionalIntegerInRange(options.topKCandidates, "options.topKCandidates", issues, {
+      min: 1,
+      max: RECALL_DEBUG_ARTIFACT_MAX_TOP_K
+    }),
+    faultInjection: parseFaultInjection(options.faultInjection, issues)
+  };
+}
+function parseFaultInjection(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const faultInjection = parseObject(value, "options.faultInjection", issues);
+  if (faultInjection === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(faultInjection, FAULT_INJECTION_KEYS, "options.faultInjection", issues);
+  return {
+    queryEmbeddingFailure: parseOptionalBoolean(faultInjection.queryEmbeddingFailure, "options.faultInjection.queryEmbeddingFailure", issues),
+    vectorSearchFailure: parseOptionalBoolean(faultInjection.vectorSearchFailure, "options.faultInjection.vectorSearchFailure", issues)
+  };
+}
+function parseUnifiedMemoryPolicy(value, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const memoryPolicy = parseObject(value, "unified.memoryPolicy", issues);
+  if (memoryPolicy === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(memoryPolicy, UNIFIED_MEMORY_POLICY_KEYS, "unified.memoryPolicy", issues);
+  return {
+    slotPolicies: parseClaimSlotPolicyConfig(memoryPolicy.slotPolicies, "unified.memoryPolicy.slotPolicies", issues)
+  };
+}
+function parseEntryType2(value, path2, issues) {
+  if (typeof value !== "string" || !ENTRY_TYPES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${ENTRY_TYPES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalRecallPath(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !RECALL_PATHS.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${RECALL_PATHS.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalUnifiedRecallMode(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !UNIFIED_RECALL_MODES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${UNIFIED_RECALL_MODES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalRankingProfile(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !RECALL_RANKING_PROFILES.includes(value)) {
+    pushIssue(issues, path2, `Expected one of: ${RECALL_RANKING_PROFILES.join(", ")}.`);
+    return void 0;
+  }
+  return value;
+}
+function parseOptionalEntryTypeArray(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    pushIssue(issues, path2, "Expected an array.");
+    return void 0;
+  }
+  const parsed = [];
+  for (const [index, item] of value.entries()) {
+    const entryType = parseEntryType2(item, `${path2}[${index}]`, issues);
+    if (entryType !== void 0) {
+      parsed.push(entryType);
+    }
+  }
+  return parsed;
+}
+function parseClaimSlotPolicyConfig(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const config = parseObject(value, path2, issues);
+  if (config === void 0) {
+    return void 0;
+  }
+  pushUnexpectedFields(config, SLOT_POLICY_KEYS, path2, issues);
+  const attributeHeads = parseClaimSlotPolicyAttributeHeads(config.attributeHeads, `${path2}.attributeHeads`, issues);
+  return attributeHeads ? { attributeHeads } : void 0;
+}
+function parseClaimSlotPolicyAttributeHeads(value, path2, issues) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!isRecord(value)) {
+    pushIssue(issues, path2, "Expected an object.");
+    return void 0;
+  }
+  const normalized = {};
+  for (const [rawKey, rawValue] of Object.entries(value)) {
+    const attributeHead = rawKey.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(attributeHead)) {
+      pushIssue(issues, `${path2}.${rawKey}`, "Expected a canonical attribute-head label.");
+      continue;
+    }
+    if (typeof rawValue !== "string" || !CLAIM_SLOT_POLICIES.includes(rawValue)) {
+      pushIssue(issues, `${path2}.${attributeHead}`, `Expected one of: ${CLAIM_SLOT_POLICIES.join(", ")}.`);
+      continue;
+    }
+    normalized[attributeHead] = rawValue;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function validatePathSpecificRequest(recallPath, recallRequest, unified, issues) {
+  const effectivePath = recallPath ?? "core";
+  if (effectivePath !== "unified") {
+    if (unified !== void 0) {
+      pushIssue(issues, "unified", 'The "unified" block is only allowed when recallPath is "unified".');
+    }
+    return;
+  }
+  if (recallRequest === void 0) {
+    return;
+  }
+  if (recallRequest.budget !== void 0) {
+    pushIssue(issues, "recallRequest.budget", 'This field is only supported when recallPath is "core".');
+  }
+  if (recallRequest.since !== void 0) {
+    pushIssue(issues, "recallRequest.since", 'This field is only supported when recallPath is "core".');
+  }
+  if (recallRequest.until !== void 0) {
+    pushIssue(issues, "recallRequest.until", 'This field is only supported when recallPath is "core".');
+  }
+  if (recallRequest.around !== void 0) {
+    pushIssue(issues, "recallRequest.around", 'This field is only supported when recallPath is "core".');
+  }
+  if (recallRequest.aroundRadius !== void 0) {
+    pushIssue(issues, "recallRequest.aroundRadius", 'This field is only supported when recallPath is "core".');
+  }
+  if (recallRequest.rankingProfile !== void 0) {
+    pushIssue(issues, "recallRequest.rankingProfile", 'This field is derived by unified recall and cannot be supplied when recallPath is "unified".');
+  }
+}
+function mapSandboxRequestDto2(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    root: dto.root,
+    preserve: dto.preserve,
+    corpusSeed: dto.corpusSeed
+  };
+}
+function mapFixtureEntryDto2(dto) {
+  return mapFixtureEntryDto(dto);
+}
+function mapRecallRequestDto(dto) {
+  return {
+    text: dto.text,
+    limit: dto.limit,
+    threshold: dto.threshold,
+    budget: dto.budget,
+    types: dto.types,
+    tags: dto.tags,
+    since: dto.since,
+    until: dto.until,
+    around: dto.around,
+    aroundRadius: dto.aroundRadius,
+    asOf: dto.asOf,
+    rankingProfile: dto.rankingProfile,
+    rankingPolicy: dto.rankingPolicy
+  };
+}
+function mapUnifiedRequestDto(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    mode: dto.mode,
+    sessionKey: dto.sessionKey,
+    memoryPolicy: dto.memoryPolicy !== void 0 ? {
+      slotPolicies: dto.memoryPolicy.slotPolicies
+    } : void 0
+  };
+}
+function mapCaseOptionsDto2(dto) {
+  if (dto === void 0) {
+    return void 0;
+  }
+  return {
+    includeDiagnostics: dto.includeDiagnostics,
+    includeCandidates: dto.includeCandidates,
+    includeTimings: dto.includeTimings,
+    includeDebugArtifact: dto.includeDebugArtifact,
+    topKCandidates: dto.topKCandidates,
+    faultInjection: dto.faultInjection
+  };
+}
+
+// src/adapters/api/routes/internal-recall-eval.ts
+var INTERNAL_RECALL_EVAL_ROUTE_PATH = "/internal/evals/recall/run";
+var INTERNAL_RECALL_EVAL_ROUTE = {
+  method: "POST",
+  path: INTERNAL_RECALL_EVAL_ROUTE_PATH
+};
+function createInternalRecallEvalRoute(optionsOrRunner = {}) {
+  const options = typeof optionsOrRunner === "function" ? { runner: optionsOrRunner } : optionsOrRunner;
+  const crossEncoder = options.crossEncoder;
+  const runner = options.runner ?? ((request) => runRecallEvalCase(request, { crossEncoder }));
+  return {
+    ...INTERNAL_RECALL_EVAL_ROUTE,
+    handler: async (request) => {
+      let validatedRequest;
+      try {
+        validatedRequest = await parseValidatedRequest2(request);
+        const result = await runner(validatedRequest);
+        return jsonResponse2(result, 200);
+      } catch (error) {
+        if (error instanceof RecallEvalRequestValidationError) {
+          return jsonResponse2(
+            {
+              status: "error",
+              caseId: error.caseId,
+              error: {
+                code: "invalid_request",
+                message: error.message,
+                details: error.issues
+              }
+            },
+            400
+          );
+        }
+        return jsonResponse2(
+          {
+            status: "error",
+            caseId: validatedRequest?.caseId,
+            error: {
+              code: "internal_error",
+              message: "Internal recall eval adapter error."
+            }
+          },
+          500
+        );
+      }
+    }
+  };
+}
+var parseJsonBody2 = async (request) => {
+  try {
+    return await request.json();
+  } catch {
+    throw new RecallEvalRequestValidationError([
+      {
+        path: "$",
+        message: "Request body must be valid JSON."
+      }
+    ]);
+  }
+};
+var parseValidatedRequest2 = async (request) => {
+  const payload = await parseJsonBody2(request);
+  const requestDto = parseRecallEvalCaseRequest(payload);
+  return mapRecallEvalCaseRequestDto(requestDto);
+};
+var jsonResponse2 = (body, status) => new Response(JSON.stringify(body), {
+  status,
+  headers: {
+    "content-type": "application/json; charset=utf-8"
+  }
+});
+
+// src/adapters/api/internal-eval-routes.ts
+function createInternalEvalRoutes(options = {}) {
+  return [createInternalRecallEvalRoute({ crossEncoder: options.crossEncoder }), createInternalBeforeTurnEvalRoute({ crossEncoder: options.crossEncoder })];
+}
+
+// src/adapters/api/internal-eval-server.ts
+var DEFAULT_INTERNAL_EVAL_HOST = "127.0.0.1";
+var DEFAULT_INTERNAL_EVAL_PORT = 4010;
+async function startInternalEvalServer(options = {}) {
+  const host2 = options.host ?? DEFAULT_INTERNAL_EVAL_HOST;
+  const port2 = options.port ?? DEFAULT_INTERNAL_EVAL_PORT;
+  const crossEncoderResolution = resolveCrossEncoderPort(options);
+  const routes = options.routes ?? createInternalEvalRoutes({ crossEncoder: crossEncoderResolution.port });
+  const server2 = createServer((request, response) => {
+    void handleRequest(request, response, routes, host2, port2).catch(() => {
+      if (response.headersSent !== true) {
+        writeTextResponse(response, 500, "Internal server error.\n");
+        return;
+      }
+      response.destroy();
+    });
+  });
+  await listen(server2, port2, host2);
+  const address = server2.address();
+  if (address === null || typeof address === "string") {
+    await closeServer(server2);
+    throw new Error("Internal eval server did not expose a TCP address.");
+  }
+  return {
+    host: host2,
+    port: address.port,
+    routePaths: routes.map((route) => route.path),
+    baseUrl: `http://${formatHostForUrl(host2)}:${address.port}`,
+    crossEncoder: crossEncoderResolution.result,
+    close: async () => {
+      await closeServer(server2);
+    }
+  };
+}
+function resolveCrossEncoderPort(options) {
+  if (options.crossEncoder) {
+    return {
+      port: options.crossEncoder,
+      result: { status: "configured" }
+    };
+  }
+  if (options.autoResolveCrossEncoder === false) {
+    return {
+      port: void 0,
+      result: {
+        status: "not_configured",
+        reason: "Auto-resolution disabled by caller."
+      }
+    };
+  }
+  let config;
+  try {
+    config = readConfig();
+  } catch (error) {
+    return {
+      port: void 0,
+      result: {
+        status: "error",
+        reason: toReason(error, "Failed to read agenr config for cross-encoder resolution.")
+      }
+    };
+  }
+  let apiKey;
+  try {
+    apiKey = resolveCrossEncoderApiKey(config);
+  } catch (error) {
+    return {
+      port: void 0,
+      result: {
+        status: "not_configured",
+        reason: toReason(error, "OPENAI_API_KEY not configured.")
+      }
+    };
+  }
+  try {
+    const { modelId } = resolveModel(config, "cross_encoder");
+    return {
+      port: createOpenAICrossEncoder({ apiKey, model: modelId }),
+      result: { status: "configured" }
+    };
+  } catch (error) {
+    return {
+      port: void 0,
+      result: {
+        status: "error",
+        reason: toReason(error, "Failed to construct OpenAI cross-encoder adapter.")
+      }
+    };
+  }
+}
+function toReason(error, fallback) {
+  if (error instanceof Error && error.message.length > 0) {
+    return error.message;
+  }
+  return fallback;
+}
+var handleRequest = async (request, response, routes, fallbackHost, fallbackPort) => {
+  const requestUrl = new URL(request.url ?? "/", `http://${formatHostForUrl(fallbackHost)}:${request.socket.localPort ?? fallbackPort}`);
+  const route = routes.find((candidate) => candidate.path === requestUrl.pathname);
+  if (!route) {
+    writeTextResponse(response, 404, "Not found.\n");
+    return;
+  }
+  if (request.method !== route.method) {
+    response.statusCode = 405;
+    response.setHeader("allow", route.method);
+    response.end();
+    return;
+  }
+  const body = await readBody(request);
+  const routeRequest = new Request(requestUrl, {
+    method: route.method,
+    headers: toHeaders(request),
+    body: body.length > 0 ? body : void 0
+  });
+  const routeResponse = await route.handler(routeRequest);
+  await writeRouteResponse(response, routeResponse);
+};
+var readBody = async (request) => {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+};
+var toHeaders = (request) => {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        headers.append(name, item);
+      }
+      continue;
+    }
+    headers.set(name, value);
+  }
+  return headers;
+};
+var writeRouteResponse = async (response, routeResponse) => {
+  response.statusCode = routeResponse.status;
+  for (const [name, value] of routeResponse.headers) {
+    response.setHeader(name, value);
+  }
+  const body = Buffer.from(await routeResponse.arrayBuffer());
+  response.end(body);
+};
+var writeTextResponse = (response, status, body) => {
+  response.statusCode = status;
+  response.setHeader("content-type", "text/plain; charset=utf-8");
+  response.end(body);
+};
+var listen = async (server2, port2, host2) => {
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server2.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server2.off("error", onError);
+      resolve();
+    };
+    server2.once("error", onError);
+    server2.once("listening", onListening);
+    server2.listen(port2, host2);
+  });
+};
+var closeServer = async (server2) => {
+  if (server2.listening !== true) {
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    server2.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+};
+var formatHostForUrl = (host2) => {
+  if (host2.includes(":") && host2.startsWith("[") !== true) {
+    return `[${host2}]`;
+  }
+  return host2;
+};
+
+// src/internal-eval-server.ts
+var HOST_ENV_NAME = "AGENR_INTERNAL_EVAL_HOST";
+var PORT_ENV_NAME = "AGENR_INTERNAL_EVAL_PORT";
+var LEGACY_HOST_ENV_NAME = "AGENR_INTERNAL_RECALL_EVAL_HOST";
+var LEGACY_PORT_ENV_NAME = "AGENR_INTERNAL_RECALL_EVAL_PORT";
+var host = resolveHost(process.env[HOST_ENV_NAME], process.env[LEGACY_HOST_ENV_NAME]);
+var port = resolvePort(process.env[PORT_ENV_NAME], process.env[LEGACY_PORT_ENV_NAME]);
+var server = await startInternalEvalServer({ host, port });
+console.log(`Internal eval dev server listening at ${server.baseUrl}`);
+console.log(`Serving routes: ${server.routePaths.join(", ")}`);
+if (server.crossEncoder.status === "configured") {
+  console.log("Cross-encoder enabled: OpenAI credential resolved at startup.");
+} else if (server.crossEncoder.status === "not_configured") {
+  console.log("Cross-encoder disabled: OPENAI_API_KEY not configured.");
+} else {
+  console.warn(`Cross-encoder unavailable: ${server.crossEncoder.reason ?? "construction failed"}.`);
+}
+installSignalHandler("SIGINT");
+installSignalHandler("SIGTERM");
+function installSignalHandler(signal) {
+  process.once(signal, () => {
+    void shutdown(signal);
+  });
+}
+var shuttingDown = false;
+async function shutdown(signal) {
+  if (shuttingDown === true) {
+    return;
+  }
+  shuttingDown = true;
+  console.log(`Received ${signal}. Shutting down internal eval dev server.`);
+  try {
+    await server.close();
+  } finally {
+    process.exit(0);
+  }
+}
+function resolveHost(value, fallbackValue) {
+  const trimmed = value?.trim() || fallbackValue?.trim();
+  if (!trimmed) {
+    return DEFAULT_INTERNAL_EVAL_HOST;
+  }
+  return trimmed;
+}
+function resolvePort(value, fallbackValue) {
+  const trimmed = value?.trim() || fallbackValue?.trim();
+  if (!trimmed) {
+    return DEFAULT_INTERNAL_EVAL_PORT;
+  }
+  if (/^\d+$/u.test(trimmed) !== true) {
+    throw new Error(`${PORT_ENV_NAME} must be an integer between 0 and 65535.`);
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    throw new Error(`${PORT_ENV_NAME} must be an integer between 0 and 65535.`);
+  }
+  return parsed;
+}