@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/adapters/opensrc/provider.js

@@ -0,0 +1,338 @@
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { assertSafePath, isPathWithin } from "../../core/filesystem.js";
+import {
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+import {
+  OPENSRC_PROCESS_LIMITS,
+  parseOpenSrcVersion,
+  runOpenSrcCommand,
+} from "./process.js";
+import { OPENSRC_SEARCH_LIMITS, searchSourceRoot } from "./search.js";
+import { normalizeOpenSrcResult } from "./normalize.js";
+
+const MAX_SOURCES = OPENSRC_SEARCH_LIMITS.maxSources;
+const MAX_SOURCE_SPEC_CHARS = 256;
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "OpenSrcAdvisoryProviderError";
+  error.code = code;
+  return error;
+}
+
+function assertAbsolutePath(value, label) {
+  if (typeof value !== "string" || value.trim() === "" || !path.isAbsolute(value) || /\p{Cc}/u.test(value)) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be an absolute portable path`);
+  }
+  return value;
+}
+
+function assertExpectedVersion(value) {
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || value.length > 64
+    || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/u.test(value)
+  ) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc expectedVersion must be a qualified version token under 64 characters");
+  }
+  return value;
+}
+
+function assertSourceSpec(value) {
+  if (typeof value !== "string" || value.trim() === "" || value.length > MAX_SOURCE_SPEC_CHARS) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc source specs must be non-empty strings under 256 characters");
+  }
+  if (/[\0\p{Cc}\s]/u.test(value)) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc source specs must not contain whitespace or control characters");
+  }
+  if (value.startsWith("-")) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc source specs must not begin with '-'");
+  }
+  if (/[;|&$`<>(){}[\]!*?~#"']/u.test(value)) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc source specs must not contain shell metacharacters");
+  }
+  return value;
+}
+
+function assertSources(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc sources must be a non-empty array");
+  }
+  if (value.length > MAX_SOURCES) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `OpenSrc sources must contain at most ${MAX_SOURCES} entries`);
+  }
+  return value.map(assertSourceSpec);
+}
+
+function remainingTimeout(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining < 1) {
+    throw providerError(E_ADVISORY_CONTEXT_TIMEOUT, "OpenSrc advisory recall deadline expired");
+  }
+  return remaining;
+}
+
+function reportTransport(callback, payload) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(Object.freeze({ ...payload }));
+  } catch {
+    // Observability hooks cannot change advisory correctness or failure mapping.
+  }
+}
+
+async function canonicalizeExisting(candidate) {
+  try {
+    return await realpath(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+async function assertCacheOutsideProject(cacheRoot, projectRoot) {
+  // Compare both the lexical and the canonicalized spellings: either side may
+  // traverse symlinked prefixes (for example /var versus /private/var), so a
+  // single spelling can miss a genuine containment relationship. The roots
+  // must be disjoint in both directions: neither may contain the other.
+  const spellings = [
+    [path.resolve(cacheRoot), path.resolve(projectRoot)],
+    [await canonicalizeExisting(cacheRoot), await canonicalizeExisting(projectRoot)],
+  ];
+  for (const [candidateCache, candidateProject] of spellings) {
+    if (isPathWithin(candidateProject, candidateCache) || isPathWithin(candidateCache, candidateProject)) {
+      throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc cacheRoot and project root must be disjoint");
+    }
+    if (isPathWithin(path.join(candidateProject, ".forgeloop"), candidateCache)) {
+      throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc cacheRoot must be outside .forgeloop");
+    }
+  }
+  return path.resolve(cacheRoot);
+}
+
+async function runAndReport(executablePath, args, {
+  cwd,
+  timeoutMs,
+  spawnImpl,
+  env,
+  maxStdoutBytes,
+  maxStderrBytes,
+  onTransport,
+  kind,
+  sourceIndex,
+} = {}) {
+  const result = await runOpenSrcCommand(executablePath, args, {
+    cwd,
+    timeoutMs,
+    spawnImpl,
+    env,
+    maxStdoutBytes,
+    maxStderrBytes,
+  });
+  reportTransport(onTransport, {
+    kind,
+    ...(sourceIndex === undefined ? {} : { sourceIndex }),
+    stdoutBytes: result.stdoutBytes,
+    stderrBytes: result.stderrBytes,
+    durationMs: result.durationMs,
+  });
+  return result;
+}
+
+async function resolveSourceRoot({
+  executablePath,
+  source,
+  sourceIndex,
+  projectRoot,
+  cacheRoot,
+  timeoutMs,
+  spawnImpl,
+  env,
+  onTransport,
+}) {
+  let result;
+  try {
+    result = await runAndReport(executablePath, ["path", source, "--cwd", projectRoot], {
+      cwd: projectRoot,
+      timeoutMs,
+      spawnImpl,
+      env,
+      maxStdoutBytes: OPENSRC_PROCESS_LIMITS.maxStdoutBytes,
+      maxStderrBytes: OPENSRC_PROCESS_LIMITS.maxStderrBytes,
+      onTransport,
+      kind: "path",
+      sourceIndex,
+    });
+  } catch (error) {
+    throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "OpenSrc source resolution failed");
+  }
+  const lines = result.stdout.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+  if (lines.length !== 1) {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc path must print exactly one path");
+  }
+  const [printed] = lines;
+  if (/\p{Cc}/u.test(printed)) {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc path output must be portable text");
+  }
+  if (!path.isAbsolute(printed)) {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc path output must be absolute");
+  }
+  let resolved;
+  try {
+    resolved = await realpath(printed);
+  } catch {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc source path could not be canonicalized");
+  }
+  let canonicalCache;
+  try {
+    canonicalCache = await realpath(cacheRoot);
+  } catch {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc cache root could not be canonicalized");
+  }
+  if (resolved !== canonicalCache && !isPathWithin(canonicalCache, resolved)) {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc source path escaped the configured cache");
+  }
+  let rootStat;
+  try {
+    rootStat = await stat(resolved);
+  } catch {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc source path is not an accessible directory");
+  }
+  if (!rootStat.isDirectory()) {
+    throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc source path is not a directory");
+  }
+  return resolved;
+}
+
+/**
+ * Create an optional host-injected OpenSrc adapter.
+ *
+ * Construction is inert: it validates the explicit executable, version,
+ * cache, and source allowlist but does not discover binaries, spawn
+ * processes, access the network, or write lifecycle state. Version
+ * qualification repeats lazily before every recall so a changed executable
+ * cannot silently change the provider identity.
+ */
+export function createOpenSrcAdvisoryContextProvider({
+  executablePath,
+  expectedVersion,
+  cacheRoot,
+  sources,
+  spawnImpl,
+  env,
+  onTransport,
+} = {}) {
+  const qualifiedExecutablePath = assertAbsolutePath(executablePath, "OpenSrc executablePath");
+  const qualifiedExpectedVersion = assertExpectedVersion(expectedVersion);
+  const qualifiedCacheRoot = assertAbsolutePath(cacheRoot, "OpenSrc cacheRoot");
+  const qualifiedSources = assertSources(sources);
+  if (spawnImpl !== undefined && typeof spawnImpl !== "function") {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc spawn implementation must be a function");
+  }
+  if (env !== undefined && (!env || typeof env !== "object" || Array.isArray(env))) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc process environment must be an object");
+  }
+
+  const provider = {
+    id: "opensrc",
+    version: qualifiedExpectedVersion,
+    async recall({
+      projectPath,
+      taskId,
+      query,
+      limit,
+      maxItemChars,
+      maxTotalChars,
+      timeoutMs,
+    } = {}) {
+      if (typeof projectPath !== "string" || !path.isAbsolute(projectPath) || /\p{Cc}/u.test(projectPath)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc projectPath must be an absolute path");
+      }
+      if (typeof taskId !== "string" || taskId.trim() === "") {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc taskId must be a non-empty string");
+      }
+      if (typeof query !== "string" || query.trim() === "" || /\p{Cc}/u.test(query)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc query must be a non-empty portable string");
+      }
+      const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+      const projectRoot = path.resolve(projectPath);
+      try {
+        await assertSafePath(projectRoot, ".");
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "OpenSrc target directory is unavailable or unsafe");
+      }
+      await assertCacheOutsideProject(qualifiedCacheRoot, projectRoot);
+
+      const childEnv = { ...(env ?? {}), OPENSRC_HOME: qualifiedCacheRoot };
+      const deadline = Date.now() + options.timeoutMs;
+      let versionResult;
+      try {
+        versionResult = await runAndReport(qualifiedExecutablePath, ["--version"], {
+          cwd: projectRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env: childEnv,
+          maxStdoutBytes: OPENSRC_PROCESS_LIMITS.maxStdoutBytes,
+          maxStderrBytes: OPENSRC_PROCESS_LIMITS.maxStderrBytes,
+          onTransport,
+          kind: "version",
+        });
+      } catch (error) {
+        throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "OpenSrc version probe failed");
+      }
+
+      let actualVersion;
+      try {
+        actualVersion = parseOpenSrcVersion(versionResult.stdout);
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc version probe was not qualified");
+      }
+      if (actualVersion !== qualifiedExpectedVersion) {
+        throw providerError(
+          E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+          "OpenSrc executable version does not match the expected qualified version",
+        );
+      }
+
+      const matches = [];
+      const sharedBudget = { remainingReadBytes: OPENSRC_SEARCH_LIMITS.maxTotalReadBytes };
+      const boundedSources = qualifiedSources.slice(0, MAX_SOURCES);
+      for (let sourceIndex = 0; sourceIndex < boundedSources.length; sourceIndex += 1) {
+        const source = boundedSources[sourceIndex];
+        const sourceRoot = await resolveSourceRoot({
+          executablePath: qualifiedExecutablePath,
+          source,
+          sourceIndex,
+          projectRoot,
+          cacheRoot: qualifiedCacheRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env: childEnv,
+          onTransport,
+        });
+        const sourceMatches = await searchSourceRoot({
+          sourceRoot,
+          sourceSpec: source,
+          sourceIndex,
+          query,
+          budget: sharedBudget,
+          deadline,
+        });
+        matches.push(...sourceMatches);
+      }
+
+      return normalizeOpenSrcResult(matches, options);
+    },
+  };
+
+  return Object.freeze(provider);
+}

package/src/adapters/opensrc/search.js

@@ -0,0 +1,264 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+
+export const OPENSRC_SEARCH_LIMITS = Object.freeze({
+  maxSources: 8,
+  maxFilesPerSource: 2000,
+  maxEntriesPerSource: 5000,
+  maxFileBytes: 256 * 1024,
+  maxTotalReadBytes: 8 * 1024 * 1024,
+  maxMatchesPerSource: 32,
+  maxSnippetLines: 7,
+});
+
+function searchTimeoutError() {
+  const error = new Error("OpenSrc search exceeded the recall deadline");
+  error.code = E_ADVISORY_CONTEXT_TIMEOUT;
+  return error;
+}
+
+function assertDeadline(deadline, clockImpl) {
+  if (deadline === null || deadline === undefined) return;
+  if (clockImpl() >= deadline) throw searchTimeoutError();
+}
+
+const SKIPPED_DIRECTORIES = new Set([
+  ".git",
+  "node_modules",
+  "target",
+  "dist",
+  "build",
+  "coverage",
+]);
+
+const BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".bmp", ".avif",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".zip", ".tar", ".gz", ".bz2", ".xz", ".7z", ".rar",
+  ".pdf", ".exe", ".dll", ".so", ".dylib", ".a", ".o",
+  ".mp3", ".mp4", ".wav", ".ogg", ".webm", ".mov",
+  ".pyc", ".pyo", ".class", ".wasm",
+]);
+
+function defaultHooks() {
+  return { lstat, readdir, readFile, realpath };
+}
+
+function tokenizeQuery(query) {
+  return query
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/u)
+    .filter((token) => token.length > 0);
+}
+
+function isProbablyBinary(buffer) {
+  const sample = buffer.subarray(0, Math.min(buffer.length, 8000));
+  for (let index = 0; index < sample.length; index += 1) {
+    if (sample[index] === 0) return true;
+  }
+  return false;
+}
+
+function scoreLine(lowerLine, lowerQuery, queryTokens) {
+  if (lowerLine.includes(lowerQuery)) return { fullMatch: true, tokenOverlap: queryTokens.length };
+  let tokenOverlap = 0;
+  for (const token of queryTokens) {
+    if (token.length > 1 && lowerLine.includes(token)) tokenOverlap += 1;
+  }
+  return { fullMatch: false, tokenOverlap };
+}
+
+function buildSnippet(lines, matchIndex, maxSnippetLines) {
+  const context = Math.max(0, Math.floor((maxSnippetLines - 1) / 2));
+  const start = Math.max(0, matchIndex - context);
+  const end = Math.min(lines.length, matchIndex + context + 1);
+  return {
+    startLine: start + 1,
+    endLine: end,
+    text: lines.slice(start, end).join("\n"),
+  };
+}
+
+async function resolveEntryTarget(resolvedRoot, absolutePath, stat, { lstatImpl, realpathImpl }) {
+  if (stat.isSymbolicLink()) {
+    let resolved;
+    try {
+      resolved = await realpathImpl(absolutePath);
+    } catch {
+      return { kind: "skip", stat };
+    }
+    const rootWithSep = resolvedRoot.endsWith(path.sep) ? resolvedRoot : `${resolvedRoot}${path.sep}`;
+    if (resolved !== resolvedRoot && !resolved.startsWith(rootWithSep)) return { kind: "skip", stat };
+    try {
+      stat = await lstatImpl(resolved);
+    } catch {
+      return { kind: "skip", stat };
+    }
+    return { kind: stat.isFile() ? "file" : "skip", stat };
+  }
+  if (stat.isDirectory()) return { kind: "directory", stat };
+  if (stat.isFile()) return { kind: "file", stat };
+  return { kind: "skip", stat };
+}
+
+async function processDirectoryEntry(resolvedRoot, relativePath, name, context) {
+  const { sourceSpec, sourceIndex, lowerQuery, queryTokens, limits, matches, state, budget,
+    lstatImpl, realpathImpl, readFileImpl, deadline, clockImpl } = context;
+  assertDeadline(deadline, clockImpl);
+  const absolutePath = path.join(resolvedRoot, relativePath);
+  let stat;
+  try {
+    stat = await lstatImpl(absolutePath);
+  } catch {
+    return "skip";
+  }
+  const entry = await resolveEntryTarget(resolvedRoot, absolutePath, stat, { lstatImpl, realpathImpl });
+  if (entry.kind === "directory") return "directory";
+  if (entry.kind !== "file") return "skip";
+  if (BINARY_EXTENSIONS.has(path.extname(name).toLowerCase())) return "skip";
+  if (entry.stat.size > limits.maxFileBytes) return "skip";
+  if (state.filesSeen >= limits.maxFilesPerSource) return "skip";
+  if (entry.stat.size > budget.remainingReadBytes) return "skip";
+  assertDeadline(deadline, clockImpl);
+  let buffer;
+  try {
+    buffer = await readFileImpl(absolutePath);
+  } catch {
+    return "skip";
+  }
+  assertDeadline(deadline, clockImpl);
+  state.filesSeen += 1;
+  budget.remainingReadBytes -= buffer.byteLength;
+  if (isProbablyBinary(buffer)) return "skip";
+  const text = buffer.toString("utf8");
+  if (/\u0000/u.test(text)) return "skip";
+  collectLineMatches(text.split("\n"), {
+    sourceSpec,
+    sourceIndex,
+    relativePath: relativePath.split(path.sep).join("/"),
+    lowerQuery,
+    queryTokens,
+    limits,
+    matches,
+  });
+  return "file";
+}
+
+function collectLineMatches(lines, { sourceSpec, sourceIndex, relativePath, lowerQuery, queryTokens, limits, matches }) {
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    if (matches.length >= limits.maxMatchesPerSource) break;
+    const line = lines[lineIndex];
+    const { fullMatch, tokenOverlap } = scoreLine(line.toLowerCase(), lowerQuery, queryTokens);
+    if (!fullMatch && tokenOverlap === 0) continue;
+    const snippet = buildSnippet(lines, lineIndex, limits.maxSnippetLines);
+    matches.push({
+      sourceSpec,
+      sourceIndex,
+      relativePath,
+      line: lineIndex + 1,
+      fullMatch,
+      tokenOverlap,
+      snippetStartLine: snippet.startLine,
+      snippetEndLine: snippet.endLine,
+      snippet: snippet.text,
+    });
+  }
+}
+
+function compareMatches(left, right) {
+  if (left.fullMatch !== right.fullMatch) return left.fullMatch ? -1 : 1;
+  if (left.tokenOverlap !== right.tokenOverlap) return right.tokenOverlap - left.tokenOverlap;
+  if (left.sourceIndex !== right.sourceIndex) return left.sourceIndex - right.sourceIndex;
+  if (left.relativePath !== right.relativePath) return left.relativePath < right.relativePath ? -1 : 1;
+  return left.line - right.line;
+}
+
+/**
+ * Deterministically search one resolved OpenSrc source root for query text.
+ *
+ * Traversal is lexicographically sorted, directory symlinks are never
+ * followed, file symlinks must resolve inside the source root, and every
+ * bound (entry count, file count, file size, shared byte budget, match count,
+ * recall deadline) is enforced before further allocation or reads. Generated
+ * directory names are skipped at any depth; ordinary files are never skipped
+ * by name. Stopping points are deterministic for identical trees, queries,
+ * and budgets.
+ */
+export async function searchSourceRoot({
+  sourceRoot,
+  sourceSpec,
+  sourceIndex = 0,
+  query,
+  limits = OPENSRC_SEARCH_LIMITS,
+  hooks = {},
+  budget = null,
+  deadline = null,
+  clockImpl = Date.now,
+} = {}) {
+  if (typeof sourceRoot !== "string" || sourceRoot === "" || typeof sourceSpec !== "string" || sourceSpec === "") {
+    throw new Error("OpenSrc search requires a source root and source spec");
+  }
+  if (typeof query !== "string" || query.trim() === "") {
+    throw new Error("OpenSrc search requires a non-empty query");
+  }
+  if (deadline !== null && deadline !== undefined && typeof clockImpl !== "function") {
+    throw new Error("OpenSrc search requires a clock implementation when a deadline is set");
+  }
+  const { lstat: lstatImpl, readdir: readdirImpl, readFile: readFileImpl, realpath: realpathImpl } = {
+    ...defaultHooks(),
+    ...hooks,
+  };
+  let resolvedRoot = path.resolve(sourceRoot);
+  try {
+    resolvedRoot = await realpathImpl(resolvedRoot);
+  } catch {
+    // The root is stat'ed lazily below; keep the resolved form on failure.
+  }
+  const lowerQuery = query.toLowerCase();
+  const queryTokens = tokenizeQuery(query);
+  const matches = [];
+  const state = { filesSeen: 0, entriesVisited: 0 };
+  const sharedBudget = budget ?? { remainingReadBytes: limits.maxTotalReadBytes ?? OPENSRC_SEARCH_LIMITS.maxTotalReadBytes };
+  const maxEntries = limits.maxEntriesPerSource ?? OPENSRC_SEARCH_LIMITS.maxEntriesPerSource;
+
+  const stack = ["."];
+  const context = {
+    resolvedRoot, sourceSpec, sourceIndex, lowerQuery, queryTokens, limits, matches, state,
+    budget: sharedBudget, deadline, clockImpl, maxEntries,
+    lstatImpl, realpathImpl, readdirImpl, readFileImpl,
+  };
+  while (stack.length > 0) {
+    assertDeadline(deadline, clockImpl);
+    if (await scanDirectory(stack, context)) break;
+  }
+
+  matches.sort(compareMatches);
+  return matches;
+}
+
+async function scanDirectory(stack, context) {
+  const { resolvedRoot, limits, matches, state, maxEntries, readdirImpl } = context;
+  const relativeDir = stack.pop();
+  const absoluteDir = path.join(resolvedRoot, relativeDir);
+  let entries;
+  try {
+    entries = await readdirImpl(absoluteDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  const names = entries.map((entry) => entry.name).sort();
+  for (let index = names.length - 1; index >= 0; index -= 1) {
+    if (matches.length >= limits.maxMatchesPerSource) return true;
+    if (state.entriesVisited >= maxEntries) return true;
+    state.entriesVisited += 1;
+    const name = names[index];
+    const relativePath = relativeDir === "." ? name : `${relativeDir}/${name}`;
+    const outcome = await processDirectoryEntry(resolvedRoot, relativePath, name, context);
+    if (outcome === "directory" && !SKIPPED_DIRECTORIES.has(name)) stack.push(relativePath);
+  }
+  return matches.length >= limits.maxMatchesPerSource || state.entriesVisited >= maxEntries;
+}

package/src/adapters/typesafe/client.js

@@ -0,0 +1,28 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { DECISION_ERROR_CODES, decisionError } from "../../core/decision/errors.js";
+import { PINNED_JEV_MODEL } from "../../core/decision/constants.js";
+
+export function hasTypesafeCredentials(env = process.env) {
+  return typeof env?.TYPESAFE_API_KEY === "string" && env.TYPESAFE_API_KEY.trim().length > 0;
+}
+
+export function validateTypesafeCredential(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw decisionError(DECISION_ERROR_CODES.AUTH_REQUIRED, "TYPESAFE_API_KEY is required for a semantic decision.");
+  }
+  if (value !== value.trim() || /[\r\n\u0000-\u001F\u007F]/u.test(value) || value.length > 4096) {
+    throw decisionError(DECISION_ERROR_CODES.AUTH_INVALID, "TYPESAFE_API_KEY has an invalid format.");
+  }
+  return true;
+}
+
+export function createTypesafeClient(policy, { env = process.env } = {}) {
+  validateTypesafeCredential(env?.TYPESAFE_API_KEY);
+  if (policy?.model !== PINNED_JEV_MODEL) throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "ForgeLoop requires the pinned Jev model.");
+  return new TypeSafeClient({
+    defaultModel: PINNED_JEV_MODEL,
+    timeout: policy.requestTimeoutMs,
+    retry: { maxRetries: policy.maxRetries },
+    logLevel: "warn",
+  });
+}

package/src/adapters/typesafe/engine.js

@@ -0,0 +1,63 @@
+import { choice, noul } from "@typesafe-ai/sdk";
+import { createTypesafeClient, hasTypesafeCredentials } from "./client.js";
+import { normalizeTypesafeResult } from "./normalize.js";
+import { DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "../../core/decision/constants.js";
+import { DECISION_ERROR_CODES, decisionError, safeDecisionError } from "../../core/decision/errors.js";
+
+function safeFailureFields(error) {
+  const diagnostics = error?.diagnostics;
+  if (!diagnostics) return {};
+  return {
+    httpStatus: diagnostics.httpStatus ?? null,
+    providerErrorType: diagnostics.providerErrorType ?? null,
+    requestId: diagnostics.requestId ?? null,
+    networkClass: diagnostics.networkClass ?? null,
+  };
+}
+
+function sdkQuestions(questionSet) {
+  return Object.fromEntries(Object.entries(questionSet.questions).map(([name, question]) => {
+    if (question.type === "choice") return [name, choice(`Answer the bounded ${name} question.`, question.criteria)];
+    return [name, noul(`Answer the bounded ${name} question.`, question.criteria)];
+  }));
+}
+
+export function createTypesafeEngine({ policy }) {
+  const engine = {
+    id: DECISION_ENGINE_ID,
+    model: PINNED_JEV_MODEL,
+    async evaluate(request) {
+      if (!hasTypesafeCredentials()) throw decisionError(DECISION_ERROR_CODES.AUTH_REQUIRED, "TYPESAFE_API_KEY is required for a semantic decision.");
+      const started = Date.now();
+      try {
+        const client = createTypesafeClient(policy);
+        const raw = await client.systemOne({ state: request.state, questions: sdkQuestions(request.questionSet), model: PINNED_JEV_MODEL }, { timeout: policy.requestTimeoutMs, retry: { maxRetries: policy.maxRetries } });
+        return { ...normalizeTypesafeResult(raw, request.questionSet), latencyMs: Date.now() - started };
+      } catch (error) {
+        throw safeDecisionError(error);
+      }
+    },
+    async health() {
+      if (!hasTypesafeCredentials()) return { status: "missing", engine: DECISION_ENGINE_ID, model: PINNED_JEV_MODEL };
+      const started = Date.now();
+      try {
+        const client = createTypesafeClient(policy);
+        const raw = await client.systemOne({ state: { healthCheck: true }, questions: { healthy: noul("Is this bounded health-check request well-formed?", { yes: "The request is well-formed", no: "The request is not well-formed" }) }, model: PINNED_JEV_MODEL }, { timeout: policy.requestTimeoutMs, retry: { maxRetries: 0 } });
+        if (raw.model !== PINNED_JEV_MODEL) throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "The semantic decision service returned an unsupported model.");
+        return { status: "healthy", engine: DECISION_ENGINE_ID, model: PINNED_JEV_MODEL, latencyMs: Date.now() - started, usage: raw.usage ?? null };
+      } catch (error) {
+        const normalized = safeDecisionError(error);
+        return {
+          status: normalized.code === DECISION_ERROR_CODES.RATE_LIMITED ? "rate-limited"
+            : normalized.code === DECISION_ERROR_CODES.AUTH_INVALID ? "invalid"
+              : "unreachable",
+          engine: DECISION_ENGINE_ID,
+          model: PINNED_JEV_MODEL,
+          errorCode: normalized.code,
+          ...safeFailureFields(normalized),
+        };
+      }
+    },
+  };
+  return Object.freeze(engine);
+}