@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/adapters/emulated-services/constants.js

@@ -0,0 +1,24 @@
+export const EMULATED_SERVICES_ID = "emulated-services";
+export const EMULATED_SERVICES_SUPPORTED_VERSION = "0.11.2";
+
+export const EMULATED_SERVICES_PROCESS_LIMITS = Object.freeze({
+  maxStdoutBytes: 64 * 1024,
+  maxStderrBytes: 64 * 1024,
+  maxServices: 32,
+  maxTimeoutMs: 120_000,
+  terminationGraceMs: 250,
+  readinessPollMs: 50,
+});
+
+export const EMULATED_SERVICES_ERROR_CODES = Object.freeze({
+  CONFIG_INVALID: "E_EMULATED_SERVICES_CONFIG_INVALID",
+  UNAVAILABLE: "E_EMULATED_SERVICES_UNAVAILABLE",
+  VERSION_UNSUPPORTED: "E_EMULATED_SERVICES_VERSION_UNSUPPORTED",
+  OUTPUT_INVALID: "E_EMULATED_SERVICES_OUTPUT_INVALID",
+  OUTPUT_LIMIT: "E_EMULATED_SERVICES_OUTPUT_LIMIT",
+  TIMEOUT: "E_EMULATED_SERVICES_TIMEOUT",
+  CANCELLED: "E_EMULATED_SERVICES_CANCELLED",
+  EXECUTION_FAILED: "E_EMULATED_SERVICES_EXECUTION_FAILED",
+  ENDPOINT_INVALID: "E_EMULATED_SERVICES_ENDPOINT_INVALID",
+  CLEANUP_FAILED: "E_EMULATED_SERVICES_CLEANUP_FAILED",
+});

package/src/adapters/emulated-services/index.js

@@ -0,0 +1,7 @@
+export { createEmulatedServicesProvider, normalizeEndpoint, parseVersion } from "./provider.js";
+export {
+  EMULATED_SERVICES_ERROR_CODES,
+  EMULATED_SERVICES_ID,
+  EMULATED_SERVICES_PROCESS_LIMITS,
+  EMULATED_SERVICES_SUPPORTED_VERSION,
+} from "./constants.js";

package/src/adapters/emulated-services/process.js

@@ -0,0 +1,162 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+import {
+  EMULATED_SERVICES_ERROR_CODES,
+  EMULATED_SERVICES_PROCESS_LIMITS,
+} from "./constants.js";
+
+function processError(code, message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.name = "EmulatedServicesProcessError";
+  error.code = code;
+  return error;
+}
+
+function byteLength(value) {
+  return Buffer.isBuffer(value) ? value.byteLength : Buffer.byteLength(String(value));
+}
+
+function terminateChild(child) {
+  if (!child || typeof child.kill !== "function") return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    // The process may have exited between a boundary failure and termination.
+  }
+  const timer = setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Preserve the original boundary error.
+    }
+  }, EMULATED_SERVICES_PROCESS_LIMITS.terminationGraceMs);
+  timer.unref?.();
+}
+
+function waitForClose(child, alreadyClosed = () => false) {
+  if (alreadyClosed()) return Promise.resolve();
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    child.once?.("close", finish);
+    const timer = setTimeout(finish, EMULATED_SERVICES_PROCESS_LIMITS.terminationGraceMs + 1000);
+    timer.unref?.();
+  });
+}
+
+function assertArgv(args) {
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || /\p{Cc}/u.test(arg))) {
+    throw processError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services arguments must be portable strings");
+  }
+}
+
+export function spawnManagedEmulatedServicesProcess(executablePath, args, options = {}) {
+  assertArgv(args);
+  const spawnImpl = options.spawnImpl ?? nodeSpawn;
+  if (typeof spawnImpl !== "function") {
+    throw processError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services spawn implementation must be a function");
+  }
+
+  let child;
+  try {
+    child = spawnImpl(executablePath, [...args], {
+      cwd: options.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: options.env,
+    });
+  } catch (error) {
+    throw processError(EMULATED_SERVICES_ERROR_CODES.UNAVAILABLE, "Unable to start the Emulated Services executable", error);
+  }
+
+  if (!child || !child.stdout || !child.stderr || typeof child.on !== "function") {
+    terminateChild(child);
+    throw processError(EMULATED_SERVICES_ERROR_CODES.UNAVAILABLE, "Emulated Services process did not expose piped output");
+  }
+
+  const maxStdoutBytes = options.maxStdoutBytes ?? EMULATED_SERVICES_PROCESS_LIMITS.maxStdoutBytes;
+  const maxStderrBytes = options.maxStderrBytes ?? EMULATED_SERVICES_PROCESS_LIMITS.maxStderrBytes;
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let overflowError = null;
+  const stdoutChunks = [];
+
+  child.stdout.on("data", (chunk) => {
+    stdoutBytes += byteLength(chunk);
+    if (stdoutBytes > maxStdoutBytes && !overflowError) {
+      overflowError = processError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_LIMIT, "Emulated Services stdout exceeded its safety limit");
+      terminateChild(child);
+      return;
+    }
+    if (!overflowError) stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  });
+  child.stderr.on("data", (chunk) => {
+    stderrBytes += byteLength(chunk);
+    if (stderrBytes > maxStderrBytes && !overflowError) {
+      overflowError = processError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_LIMIT, "Emulated Services stderr exceeded its safety limit");
+      terminateChild(child);
+    }
+  });
+
+  let processErrorValue = null;
+  child.on("error", (error) => {
+    processErrorValue = processError(
+      error?.code === "ENOENT" ? EMULATED_SERVICES_ERROR_CODES.UNAVAILABLE : EMULATED_SERVICES_ERROR_CODES.EXECUTION_FAILED,
+      "Emulated Services process failed",
+      error,
+    );
+  });
+
+  let hasClosed = false;
+  const closed = new Promise((resolve) => {
+    child.on("close", (code, signal) => {
+      hasClosed = true;
+      resolve({ code, signal });
+    });
+  });
+
+  return Object.freeze({
+    child,
+    closed,
+    output: () => ({
+      stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+      stdoutBytes,
+      stderrBytes,
+    }),
+    failure: () => overflowError ?? processErrorValue,
+    stop: () => terminateChild(child),
+    waitForClose: () => waitForClose(child, () => hasClosed),
+  });
+}
+
+export async function runBoundedEmulatedServicesCommand(executablePath, args, options = {}) {
+  const managed = spawnManagedEmulatedServicesProcess(executablePath, args, options);
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const timeout = new Promise((_, reject) => {
+    const timer = setTimeout(() => {
+      managed.stop();
+      reject(processError(EMULATED_SERVICES_ERROR_CODES.TIMEOUT, "Emulated Services command exceeded its timeout"));
+    }, timeoutMs);
+    timer.unref?.();
+  });
+  try {
+    const result = await Promise.race([managed.closed, timeout]);
+    const failure = managed.failure();
+    if (failure) throw failure;
+    if (result.code !== 0) {
+      throw processError(EMULATED_SERVICES_ERROR_CODES.EXECUTION_FAILED, "Emulated Services command exited unsuccessfully");
+    }
+    return managed.output();
+  } finally {
+    managed.stop();
+    await managed.waitForClose();
+  }
+}
+
+export function emulatedServicesProcessError(code, message, cause) {
+  return processError(code, message, cause);
+}

package/src/adapters/emulated-services/provider.js

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  EMULATED_SERVICES_ERROR_CODES,
+  EMULATED_SERVICES_ID,
+  EMULATED_SERVICES_PROCESS_LIMITS,
+  EMULATED_SERVICES_SUPPORTED_VERSION,
+} from "./constants.js";
+import {
+  emulatedServicesProcessError,
+  runBoundedEmulatedServicesCommand,
+  spawnManagedEmulatedServicesProcess,
+} from "./process.js";
+
+const FACTORY_KEYS = new Set([
+  "executablePath",
+  "expectedVersion",
+  "tempRoot",
+  "targetRoot",
+  "spawnImpl",
+  "fsImpl",
+  "mkdtempImpl",
+  "rmImpl",
+  "fetchImpl",
+  "sleepImpl",
+  "nowImpl",
+]);
+
+function providerError(code, message, cause) {
+  return emulatedServicesProcessError(code, message, cause);
+}
+
+function assertPortableString(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+function assertAbsolutePath(value, label) {
+  assertPortableString(value, label);
+  if (!path.isAbsolute(value)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be absolute`);
+  }
+  return value;
+}
+
+function assertRegularFile(filePath, label, fsImpl) {
+  assertAbsolutePath(filePath, label);
+  let stat;
+  try {
+    stat = fsImpl.lstatSync(filePath);
+  } catch (error) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} is unavailable`, error);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink?.()) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be a regular non-symlink file`);
+  }
+  return filePath;
+}
+
+function isWithin(parent, candidate) {
+  const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function assertTempRootSafe(tempRoot, targetRoot) {
+  if (targetRoot && (isWithin(targetRoot, tempRoot) || isWithin(tempRoot, targetRoot))) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services temporary state must be outside the target root");
+  }
+}
+
+function filteredEnvironment() {
+  const allowed = new Set(["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SystemRoot", "ComSpec", "LANG", "LC_ALL", "NODE_PATH"]);
+  return Object.fromEntries(Object.entries(process.env).filter(([key]) => allowed.has(key)));
+}
+
+function parseVersion(stdout) {
+  if (typeof stdout !== "string") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_INVALID, "Emulated Services version output was not text");
+  }
+  const match = /^\s*(?:emulate(?:\s+|@))?v?(\d+\.\d+\.\d+)\s*$/iu.exec(stdout);
+  if (!match) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_INVALID, "Emulated Services version output was malformed");
+  }
+  return match[1];
+}
+
+function normalizeServices(services) {
+  if (!Array.isArray(services) || services.length === 0 || services.length > EMULATED_SERVICES_PROCESS_LIMITS.maxServices) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "services must be a non-empty bounded array");
+  }
+  const normalized = services.map((service) => {
+    assertPortableString(service, "service");
+    if (!/^[a-z][a-z0-9-]*$/u.test(service)) {
+      throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "service identifiers must be portable lowercase names");
+    }
+    return service;
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "services must not contain duplicates");
+  }
+  return normalized;
+}
+
+function normalizeRequest(request, { fsImpl, targetRoot }) {
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services request must be an object");
+  }
+  const services = normalizeServices(request.services);
+  const basePort = request.basePort ?? 4000;
+  if (!Number.isSafeInteger(basePort) || basePort < 1 || basePort + services.length - 1 > 65535) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "basePort must provide a valid loopback port range");
+  }
+  const timeoutMs = request.timeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > EMULATED_SERVICES_PROCESS_LIMITS.maxTimeoutMs) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "timeoutMs is outside the supported bounded range");
+  }
+  let seedPath = null;
+  if (request.seedPath !== undefined && request.seedPath !== null) {
+    seedPath = assertRegularFile(request.seedPath, "seedPath", fsImpl);
+    if (targetRoot && isWithin(targetRoot, seedPath)) {
+      throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "seedPath must not be inside the target root");
+    }
+  }
+  return { services, basePort, timeoutMs, seedPath, signal: request.signal };
+}
+
+function validateSignal(signal) {
+  if (signal !== undefined && (!signal || typeof signal.aborted !== "boolean" || typeof signal.addEventListener !== "function")) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "signal must be an AbortSignal");
+  }
+}
+
+function assertNotCancelled(signal) {
+  if (signal?.aborted) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CANCELLED, "Emulated Services operation was cancelled");
+  }
+}
+
+function normalizeEndpoint(port) {
+  const endpoint = `http://127.0.0.1:${port}`;
+  const url = new URL(endpoint);
+  if (url.protocol !== "http:" || url.hostname !== "127.0.0.1") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.ENDPOINT_INVALID, "Emulated Services endpoint was not loopback HTTP");
+  }
+  return endpoint;
+}
+
+async function waitForReady(endpoint, { fetchImpl, signal, deadline, sleepImpl, nowImpl }) {
+  while (nowImpl() < deadline) {
+    assertNotCancelled(signal);
+    try {
+      const response = await fetchImpl(endpoint, { method: "GET", redirect: "manual", signal });
+      const status = Number(response?.status);
+      if (Number.isInteger(status) && status >= 200 && status < 500) return;
+    } catch (error) {
+      if (signal?.aborted) throw providerError(EMULATED_SERVICES_ERROR_CODES.CANCELLED, "Emulated Services operation was cancelled", error);
+    }
+    const remaining = deadline - nowImpl();
+    if (remaining <= 0) break;
+    await sleepImpl(Math.min(EMULATED_SERVICES_PROCESS_LIMITS.readinessPollMs, remaining), signal);
+  }
+  throw providerError(EMULATED_SERVICES_ERROR_CODES.TIMEOUT, "Emulated Services did not become ready before the timeout");
+}
+
+function validateFactoryOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services provider options must be an object");
+  }
+  for (const key of Object.keys(options)) {
+    if (!FACTORY_KEYS.has(key)) throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `Unsupported Emulated Services option: ${key}`);
+  }
+}
+
+export function createEmulatedServicesProvider(options = {}) {
+  validateFactoryOptions(options);
+  const fsImpl = options.fsImpl ?? fs;
+  const executablePath = assertRegularFile(options.executablePath, "executablePath", fsImpl);
+  const expectedVersion = options.expectedVersion ?? EMULATED_SERVICES_SUPPORTED_VERSION;
+  if (expectedVersion !== EMULATED_SERVICES_SUPPORTED_VERSION) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `Only Emulated Services ${EMULATED_SERVICES_SUPPORTED_VERSION} is supported`);
+  }
+  const tempRoot = assertAbsolutePath(options.tempRoot ?? os.tmpdir(), "tempRoot");
+  const targetRoot = options.targetRoot === undefined ? null : assertAbsolutePath(options.targetRoot, "targetRoot");
+  assertTempRootSafe(tempRoot, targetRoot);
+  const mkdtempImpl = options.mkdtempImpl ?? fs.promises.mkdtemp;
+  const rmImpl = options.rmImpl ?? fs.promises.rm;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const sleepImpl = options.sleepImpl ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+  const nowImpl = options.nowImpl ?? (() => Date.now());
+  if (typeof fetchImpl !== "function" || typeof mkdtempImpl !== "function" || typeof rmImpl !== "function") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services host capabilities are incomplete");
+  }
+
+  return Object.freeze({
+    id: EMULATED_SERVICES_ID,
+    version: expectedVersion,
+    async start(request = {}) {
+      const normalized = normalizeRequest(request, { fsImpl, targetRoot });
+      validateSignal(normalized.signal);
+      assertNotCancelled(normalized.signal);
+      const tempPrefix = path.join(tempRoot, "forgeloop-emulated-");
+      let stateRoot = null;
+      let managed = null;
+      let result = null;
+      let operationError = null;
+      try {
+        stateRoot = await mkdtempImpl(tempPrefix);
+        assertAbsolutePath(stateRoot, "Emulated Services temporary state");
+        assertTempRootSafe(stateRoot, targetRoot);
+        const versionResult = await runBoundedEmulatedServicesCommand(executablePath, ["--version"], {
+          cwd: stateRoot,
+          env: filteredEnvironment(),
+          spawnImpl: options.spawnImpl,
+          timeoutMs: Math.min(normalized.timeoutMs, 10_000),
+        });
+        const actualVersion = parseVersion(versionResult.stdout);
+        if (actualVersion !== expectedVersion) {
+          throw providerError(EMULATED_SERVICES_ERROR_CODES.VERSION_UNSUPPORTED, `Unsupported Emulated Services version: ${actualVersion}`);
+        }
+
+        const args = ["--service", normalized.services.join(","), "--port", String(normalized.basePort)];
+        if (normalized.seedPath) args.push("--seed", normalized.seedPath);
+        managed = spawnManagedEmulatedServicesProcess(executablePath, args, {
+          cwd: stateRoot,
+          env: filteredEnvironment(),
+          spawnImpl: options.spawnImpl,
+        });
+        const deadline = nowImpl() + normalized.timeoutMs;
+        const endpoints = normalized.services.map((service, index) => ({
+          id: service,
+          endpoint: normalizeEndpoint(normalized.basePort + index),
+        }));
+        for (const service of endpoints) {
+          await waitForReady(service.endpoint, {
+            fetchImpl,
+            signal: normalized.signal,
+            deadline,
+            sleepImpl,
+            nowImpl,
+          });
+        }
+        result = {
+          provider: { id: EMULATED_SERVICES_ID, version: expectedVersion },
+          services: endpoints,
+          status: "READY",
+          diagnostics: ["Host-provided emulated services were observed on loopback"],
+          authority: "OBSERVATION",
+          evidenceAuthority: "NONE",
+          lifecycleAuthority: false,
+          completionAuthority: false,
+          persisted: false,
+          cleanup: { status: "PENDING" },
+        };
+      } catch (error) {
+        operationError = error;
+      } finally {
+        if (managed) {
+          managed.stop();
+          await managed.waitForClose();
+        }
+        if (stateRoot) {
+          try {
+            await rmImpl(stateRoot, { recursive: true, force: true });
+            if (result) result.cleanup = { status: "COMPLETED" };
+          } catch (error) {
+            const cleanupError = providerError(EMULATED_SERVICES_ERROR_CODES.CLEANUP_FAILED, "Emulated Services temporary state cleanup failed", error);
+            if (!operationError) operationError = cleanupError;
+            if (result) result.cleanup = { status: "FAILED" };
+          }
+        }
+      }
+      if (operationError) throw operationError;
+      return Object.freeze(result);
+    },
+  });
+}
+
+export { normalizeEndpoint, parseVersion };

package/src/adapters/opensrc/normalize.js

@@ -0,0 +1,90 @@
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+} from "../../core/error-codes.js";
+
+function adapterError(code, message) {
+  const error = new Error(message);
+  error.name = "OpenSrcAdapterError";
+  error.code = code;
+  return error;
+}
+
+function fitText(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(1, maxLength - 1))}…`;
+}
+
+function lineRangeLabel(startLine, endLine) {
+  return startLine === endLine ? `L${startLine}` : `L${startLine}-L${endLine}`;
+}
+
+function normalizeMatch(match) {
+  if (!match || typeof match !== "object" || Array.isArray(match)) return null;
+  const { sourceSpec, relativePath, snippet, snippetStartLine, snippetEndLine } = match;
+  if (typeof sourceSpec !== "string" || sourceSpec === "") return null;
+  if (typeof relativePath !== "string" || relativePath === "" || relativePath.startsWith("/")) return null;
+  if (typeof snippet !== "string") return null;
+  if (!Number.isSafeInteger(snippetStartLine) || snippetStartLine < 1) return null;
+  if (!Number.isSafeInteger(snippetEndLine) || snippetEndLine < snippetStartLine) return null;
+  const range = lineRangeLabel(snippetStartLine, snippetEndLine);
+  const flatSnippet = snippet.replace(/\s+/gu, " ").trim();
+  return {
+    title: `${sourceSpec} — ${relativePath}`,
+    summary: flatSnippet === "" ? range : `${range} | ${flatSnippet}`,
+    sourceRef: `opensrc:${sourceSpec}:${relativePath}#${range}`,
+    identity: [sourceSpec, relativePath, range, snippet].join(" "),
+  };
+}
+
+/**
+ * Convert bounded deterministic search matches into ForgeLoop advisory items.
+ *
+ * Titles, summaries, and source references carry only portable relative
+ * paths; absolute cache locations never leave this boundary.
+ */
+export function normalizeOpenSrcResult(matches, {
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+} = {}) {
+  if (!Array.isArray(matches)) {
+    throw adapterError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc search matches must be an array");
+  }
+  if (matches.length > ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems) {
+    throw adapterError(
+      E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+      `OpenSrc returned ${matches.length} matches, exceeding the raw item ceiling of ${ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems}`,
+    );
+  }
+  const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+  const prepared = [];
+  const seen = new Set();
+  for (const match of matches) {
+    const normalized = normalizeMatch(match);
+    if (!normalized) continue;
+    if (seen.has(normalized.identity)) continue;
+    seen.add(normalized.identity);
+    const summary = fitText(normalized.summary, options.maxItemChars);
+    prepared.push({ title: normalized.title, summary, sourceRef: normalized.sourceRef });
+  }
+
+  const items = [];
+  let totalChars = 0;
+  for (const candidate of prepared) {
+    if (items.length >= options.limit) break;
+    const chars = candidate.title.length + candidate.summary.length + candidate.sourceRef.length;
+    if (totalChars + chars > options.maxTotalChars) break;
+    totalChars += chars;
+    items.push(candidate);
+  }
+  if (items.length === 0 && prepared.length > 0) {
+    throw adapterError(E_ADVISORY_CONTEXT_OUTPUT_LIMIT, "OpenSrc matches cannot fit the requested output budget");
+  }
+  return { items };
+}