sift-light 1.0.0

package/src/concept-worker.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { env, pipeline } from "@huggingface/transformers";
+import { isUtf8 } from "node:buffer";
+import {
+  conceptEmbeddingKey,
+  enforceConceptCacheLimit,
+  readConceptEmbedding,
+  writeConceptEmbedding,
+  type CachedConceptEmbedding,
+} from "./concept-embedding-cache.js";
+import {
+  cosineSimilarity,
+  embedConceptInputs,
+  meanNormalized,
+  type PendingConceptEmbedding,
+} from "./concept-inference.js";
+import {
+  CONCEPT_ASSETS,
+  CONCEPT_CACHE_MAX_BYTES,
+  MAX_CONCEPT_CHARS,
+  MAX_CONCEPT_WORKER_INPUT_BYTES,
+  conceptCacheDirectory,
+  conceptModelDirectory,
+  verifyConceptModel,
+} from "./concept-model.js";
+import { installConceptModel } from "./concept-setup.js";
+import { isRecordValue } from "./record-value.js";
+
+const CACHE_IO_CONCURRENCY = 64;
+
+interface WorkerProgress {
+  phase: "cache-read" | "model-loading" | "embedding" | "cache-write" | "cache-cleanup";
+  completed?: number;
+  total?: number;
+  uniqueEmbeddings: number;
+  passages: number;
+}
+
+function emitProgress(progress: WorkerProgress): void {
+  process.stdout.write(`${JSON.stringify({ type: "progress", ...progress })}\n`);
+}
+
+async function readCachedEmbeddings(
+  root: string,
+  requested: readonly PendingConceptEmbedding[],
+  onProgress?: (completed: number, total: number) => void,
+) {
+  const cached = [];
+  for (let offset = 0; offset < requested.length; offset += CACHE_IO_CONCURRENCY) {
+    // oxlint-disable-next-line no-await-in-loop -- bounded batches avoid exhausting file descriptors.
+    const batch = await Promise.all(
+      requested
+        .slice(offset, offset + CACHE_IO_CONCURRENCY)
+        .map((item) => readConceptEmbedding(root, item.key)),
+    );
+    cached.push(...batch);
+    onProgress?.(Math.min(offset + batch.length, requested.length), requested.length);
+  }
+  return cached;
+}
+
+async function requestFromStdin(): Promise<{ query: string; passages: string[] }> {
+  const chunks: Buffer[] = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    chunks.push(buffer);
+    bytes += buffer.length;
+    if (bytes > MAX_CONCEPT_WORKER_INPUT_BYTES)
+      throw new Error("Concept worker input exceeds its 64 MiB source protocol budget");
+  }
+  const request: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  if (
+    !isRecordValue(request) ||
+    typeof request.query !== "string" ||
+    request.query.length === 0 ||
+    request.query.length > 256 ||
+    !request.query.isWellFormed() ||
+    /[\r\n\0]/u.test(request.query) ||
+    !Array.isArray(request.encodedPassages) ||
+    request.encodedPassages.some(
+      (item) =>
+        typeof item !== "string" ||
+        item.length === 0 ||
+        item.length % 4 !== 0 ||
+        item.length > Math.ceil((((MAX_CONCEPT_CHARS + 256) * 4) / 3) * 4) + 4 ||
+        !/^[A-Za-z0-9+/]+={0,2}$/u.test(item),
+    )
+  )
+    throw new Error("Invalid concept worker input");
+  const encodedPassages = request.encodedPassages.filter(
+    (item): item is string => typeof item === "string",
+  );
+  const buffers = encodedPassages.map((item) => Buffer.from(item, "base64"));
+  if (buffers.some((item) => !isUtf8(item)))
+    throw new Error("Invalid UTF-8 concept worker passage");
+  const passages = buffers.map((item) => item.toString("utf8"));
+  if (
+    passages.some(
+      (item) => !item.length || item.length > MAX_CONCEPT_CHARS + 256 || !item.isWellFormed(),
+    )
+  )
+    throw new Error("Invalid decoded concept worker passage");
+  return { query: request.query, passages };
+}
+
+async function search(): Promise<void> {
+  const request = await requestFromStdin();
+  const directory = conceptModelDirectory();
+  const cacheRoot = conceptCacheDirectory();
+  const stagingRoot = process.env.SIFT_LIGHT_CONCEPT_CACHE_STAGING_DIR ?? cacheRoot;
+  await verifyConceptModel(directory);
+  const requested: PendingConceptEmbedding[] = [
+    { key: conceptEmbeddingKey("query", request.query), role: "query", text: request.query },
+    ...request.passages.map((text): PendingConceptEmbedding => ({
+      key: conceptEmbeddingKey("passage", text),
+      role: "passage",
+      text,
+    })),
+  ];
+  const uniqueRequested = [...new Map(requested.map((item) => [item.key, item])).values()];
+  const progressContext = {
+    uniqueEmbeddings: uniqueRequested.length,
+    passages: request.passages.length,
+  };
+  const cached = await readCachedEmbeddings(cacheRoot, uniqueRequested, (completed, total) =>
+    emitProgress({ phase: "cache-read", completed, total, ...progressContext }),
+  );
+  const missing = uniqueRequested.filter((_item, index) => !cached[index]);
+  const warnings: string[] = [];
+  let created: CachedConceptEmbedding[] = [];
+  let cacheWriteFailed = false;
+  if (missing.length) {
+    env.allowRemoteModels = false;
+    env.useFSCache = false;
+    env.useBrowserCache = false;
+    env.localModelPath = "/";
+    emitProgress({ phase: "model-loading", ...progressContext });
+    const extractor = await pipeline("feature-extraction", directory, {
+      local_files_only: true,
+      dtype: "q8",
+      device: "cpu",
+      session_options: { intraOpNumThreads: 2, interOpNumThreads: 1 },
+    });
+    try {
+      created = await embedConceptInputs(extractor, missing, {
+        onCompletedEmbedding: async (embedding, completed, total) => {
+          try {
+            await writeConceptEmbedding(cacheRoot, embedding, stagingRoot);
+          } catch {
+            cacheWriteFailed = true;
+          }
+          emitProgress({ phase: "cache-write", completed, total, ...progressContext });
+        },
+        onBatch: (completed, total) =>
+          emitProgress({ phase: "embedding", completed, total, ...progressContext }),
+      });
+    } finally {
+      await extractor.dispose();
+    }
+    if (cacheWriteFailed)
+      warnings.push(
+        "Concept embedding cache write failed; ranking completed but some work may repeat",
+      );
+  }
+  const createdByKey = new Map(created.map((item) => [item.key, item]));
+  const embeddingsByKey = new Map(
+    uniqueRequested.map((item, index) => [item.key, cached[index] ?? createdByKey.get(item.key)]),
+  );
+  const embeddings = requested.map((item) => embeddingsByKey.get(item.key));
+  if (embeddings.some((item) => !item)) throw new Error("Missing concept embedding result");
+  const queryWindows = embeddings[0]?.windows;
+  if (!queryWindows?.length) throw new Error("Missing concept query embedding");
+  const query = meanNormalized(queryWindows.map((window) => window.vector));
+  const passageEmbeddings = embeddings.slice(1);
+  const scores = passageEmbeddings.map((embedding) => {
+    if (!embedding?.windows.length) throw new Error("Missing concept passage embedding");
+    return Math.max(...embedding.windows.map((window) => cosineSimilarity(query, window.vector)));
+  });
+  let cacheBytes: number | undefined;
+  try {
+    emitProgress({ phase: "cache-cleanup", ...progressContext });
+    cacheBytes = await enforceConceptCacheLimit(cacheRoot);
+  } catch {
+    warnings.push(
+      "Concept embedding cache cleanup failed; the configured 512 MiB bound was not verified",
+    );
+  }
+  process.stdout.write(
+    JSON.stringify({
+      type: "result",
+      scores,
+      cacheHits: cached.filter(Boolean).length,
+      cacheMisses: missing.length,
+      cacheMaxBytes: CONCEPT_CACHE_MAX_BYTES,
+      ...(cacheBytes === undefined ? {} : { cacheBytes }),
+      windowsRanked: passageEmbeddings.reduce(
+        (total, embedding) => total + (embedding?.windows.length ?? 0),
+        0,
+      ),
+      warnings: [...new Set(warnings)],
+      peakRssBytes: process.resourceUsage().maxRSS * 1024,
+      modelBytes: CONCEPT_ASSETS.reduce((sum, asset) => sum + asset.bytes, 0),
+    }),
+  );
+}
+
+if (process.argv.includes("--install-model")) await installConceptModel();
+else if (process.argv.includes("--infer")) await search();
+else throw new Error("Usage: sift-light-model --install-model");

package/src/config-reader.ts

@@ -0,0 +1,283 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const SIFT_LIGHT_CONFIG_FILE = "sift-light.json";
+export const SIFT_LIGHT_CONFIG_ENV = "SIFT_LIGHT_CONFIG";
+
+export type SiftLightLocale = "en" | "zh-CN";
+export type SearchEnforcementMode = "hard" | "prefer" | "off";
+
+export const SIFT_LIGHT_ENFORCEMENT_ENV = "SIFT_LIGHT_ENFORCE_SEARCH";
+
+export interface SiftLightConfig {
+  locale: SiftLightLocale;
+  enforceSearch?: SearchEnforcementMode;
+  semanticJudge?: SemanticJudgeConfig;
+}
+
+export type SemanticJudgeProvider = "jev";
+
+export const SEMANTIC_JUDGE_API_KEY_ENVS = ["TYPESAFE_API_KEY", "SIFT_LIGHT_JEV_API_KEY"] as const;
+
+export interface SemanticJudgeConfig {
+  enabled: boolean;
+  provider: SemanticJudgeProvider;
+  endpoint: string;
+  apiKeyEnv: string;
+  model: string;
+  timeoutMs: number;
+  maxCandidates: number;
+  maxRetries: number;
+}
+
+export const DEFAULT_SEMANTIC_JUDGE_CONFIG: Readonly<SemanticJudgeConfig> = {
+  enabled: false,
+  provider: "jev",
+  endpoint: "https://api.typesafe.ai/v1/systemone",
+  apiKeyEnv: SEMANTIC_JUDGE_API_KEY_ENVS[0],
+  model: "jev-latest",
+  timeoutMs: 120_000,
+  maxCandidates: 20,
+  maxRetries: 2,
+};
+
+export const DEFAULT_SIFT_LIGHT_CONFIG: Readonly<SiftLightConfig> = {
+  locale: "en",
+  enforceSearch: "hard",
+  semanticJudge: DEFAULT_SEMANTIC_JUDGE_CONFIG,
+};
+
+interface RawSiftLightConfig {
+  locale?: unknown;
+  enforceSearch?: unknown;
+  semanticJudge?: unknown;
+}
+
+export interface ReadSiftLightConfigOptions {
+  missing?: "defaults" | "error";
+}
+
+export function resolveSiftLightConfigPath(
+  agentDirectory: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  const configured = environment[SIFT_LIGHT_CONFIG_ENV]?.trim();
+  return configured || join(agentDirectory, SIFT_LIGHT_CONFIG_FILE);
+}
+
+interface RawSemanticJudgeConfig {
+  enabled?: unknown;
+  provider?: unknown;
+  endpoint?: unknown;
+  apiKeyEnv?: unknown;
+  model?: unknown;
+  timeoutMs?: unknown;
+  maxCandidates?: unknown;
+  maxRetries?: unknown;
+}
+
+function hasErrorCode(error: unknown, codes: string[]): boolean {
+  return error instanceof Error && "code" in error && codes.includes(String(error.code));
+}
+
+function isMissingFile(error: unknown): boolean {
+  return hasErrorCode(error, ["ENOENT"]);
+}
+
+function isRawSiftLightConfig(value: unknown): value is RawSiftLightConfig {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isRawSemanticJudgeConfig(value: unknown): value is RawSemanticJudgeConfig {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function boundedInteger(
+  value: unknown,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+  field: string,
+): number {
+  const candidate = value ?? fallback;
+  if (
+    typeof candidate !== "number" ||
+    !Number.isSafeInteger(candidate) ||
+    candidate < minimum ||
+    candidate > maximum
+  ) {
+    throw new Error(
+      `Invalid sift-light ${field}: expected an integer from ${String(minimum)} through ${String(maximum)}`,
+    );
+  }
+  return candidate;
+}
+
+function parseSemanticJudge(value: unknown, path: string): SemanticJudgeConfig {
+  if (value === undefined) return { ...DEFAULT_SEMANTIC_JUDGE_CONFIG };
+  if (!isRawSemanticJudgeConfig(value)) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge must be an object`);
+  }
+  const unknown = Object.keys(value).filter(
+    (key) =>
+      ![
+        "enabled",
+        "provider",
+        "endpoint",
+        "apiKeyEnv",
+        "model",
+        "timeoutMs",
+        "maxCandidates",
+        "maxRetries",
+      ].includes(key),
+  );
+  if (unknown.length > 0) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: unsupported semanticJudge fields; accepted fields are enabled, provider, endpoint, apiKeyEnv, model, timeoutMs, maxCandidates and maxRetries`,
+    );
+  }
+  const enabled = value.enabled ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.enabled;
+  if (typeof enabled !== "boolean") {
+    throw new Error(
+      `Invalid sift-light config at ${path}: semanticJudge.enabled must be a boolean`,
+    );
+  }
+  const provider = value.provider ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.provider;
+  if (provider !== "jev") {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.provider must be "jev"`);
+  }
+  const endpoint = value.endpoint ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.endpoint;
+  if (typeof endpoint !== "string" || endpoint.length === 0 || endpoint.length > 2_048) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: semanticJudge.endpoint must be a nonempty URL`,
+    );
+  }
+  let parsedEndpoint: URL;
+  try {
+    parsedEndpoint = new URL(endpoint);
+  } catch (error) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must be a URL`, {
+      cause: error,
+    });
+  }
+  const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+  const secureEndpoint =
+    parsedEndpoint.protocol === "https:" ||
+    (parsedEndpoint.protocol === "http:" && loopbackHosts.has(parsedEndpoint.hostname));
+  if (!secureEndpoint || parsedEndpoint.username || parsedEndpoint.password) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: semanticJudge.endpoint must use HTTPS, except that HTTP is allowed for localhost loopback development; URL credentials are not allowed`,
+    );
+  }
+  const apiKeyEnv = value.apiKeyEnv ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.apiKeyEnv;
+  if (typeof apiKeyEnv !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/u.test(apiKeyEnv)) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: semanticJudge.apiKeyEnv must be an uppercase environment variable name`,
+    );
+  }
+  const model = value.model ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.model;
+  if (
+    typeof model !== "string" ||
+    model.length === 0 ||
+    model.length > 128 ||
+    /[\r\n\0]/u.test(model)
+  ) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: semanticJudge.model must be bounded single-line text`,
+    );
+  }
+  return {
+    enabled,
+    provider,
+    endpoint,
+    apiKeyEnv,
+    model,
+    timeoutMs: boundedInteger(
+      value.timeoutMs,
+      DEFAULT_SEMANTIC_JUDGE_CONFIG.timeoutMs,
+      1_000,
+      1_200_000,
+      `config at ${path}: semanticJudge.timeoutMs`,
+    ),
+    maxCandidates: boundedInteger(
+      value.maxCandidates,
+      DEFAULT_SEMANTIC_JUDGE_CONFIG.maxCandidates,
+      1,
+      20,
+      `config at ${path}: semanticJudge.maxCandidates`,
+    ),
+    maxRetries: boundedInteger(
+      value.maxRetries,
+      DEFAULT_SEMANTIC_JUDGE_CONFIG.maxRetries,
+      0,
+      5,
+      `config at ${path}: semanticJudge.maxRetries`,
+    ),
+  };
+}
+
+function parseConfig(value: unknown, path: string): SiftLightConfig {
+  if (!isRawSiftLightConfig(value)) {
+    throw new Error(`Invalid sift-light config at ${path}: expected a JSON object`);
+  }
+  const unknown = Object.keys(value).filter(
+    (key) => !["locale", "enforceSearch", "semanticJudge"].includes(key),
+  );
+  if (unknown.length > 0) {
+    throw new Error(
+      `Invalid sift-light config at ${path}: unsupported configuration fields; only locale, enforceSearch and semanticJudge are accepted`,
+    );
+  }
+  const { locale, enforceSearch } = value;
+  if (locale !== undefined && locale !== "en" && locale !== "zh-CN") {
+    throw new Error(`Invalid sift-light config at ${path}: locale must be "en" or "zh-CN"`);
+  }
+  const enforcement = normalizeSearchEnforcement(enforceSearch, `config at ${path}`);
+  return {
+    locale: locale ?? DEFAULT_SIFT_LIGHT_CONFIG.locale,
+    enforceSearch: enforcement,
+    semanticJudge: parseSemanticJudge(value.semanticJudge, path),
+  };
+}
+
+export function normalizeSearchEnforcement(value: unknown, source: string): SearchEnforcementMode {
+  if (value === undefined || value === "hard") return "hard";
+  if (value === "prefer") return "prefer";
+  if (value === "off") return "off";
+  throw new Error(`Invalid sift-light ${source}: enforceSearch must be "hard", "prefer", or "off"`);
+}
+
+/** Native hooks inherit this setting from their host process; absent means fail-safe hard mode. */
+export function readNativeSearchEnforcement(
+  environment: NodeJS.ProcessEnv = process.env,
+): SearchEnforcementMode {
+  const value = environment[SIFT_LIGHT_ENFORCEMENT_ENV];
+  return normalizeSearchEnforcement(value, `environment variable ${SIFT_LIGHT_ENFORCEMENT_ENV}`);
+}
+
+/** Read and validate one host-selected config path. */
+export async function readSiftLightConfigFile(
+  path: string,
+  options: ReadSiftLightConfigOptions = {},
+): Promise<SiftLightConfig> {
+  try {
+    const content = await readFile(path, "utf8");
+    return parseConfig(JSON.parse(content), path);
+  } catch (error) {
+    if (isMissingFile(error)) {
+      if (options.missing === "error") {
+        throw new Error(
+          `sift-light config was not found at ${path}; create it or unset ${SIFT_LIGHT_CONFIG_ENV}`,
+          { cause: error },
+        );
+      }
+      return { ...DEFAULT_SIFT_LIGHT_CONFIG };
+    }
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid sift-light config at ${path}: ${error.message}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}

package/src/config.ts

@@ -0,0 +1,37 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  readSiftLightConfigFile,
+  resolveSiftLightConfigPath,
+  SIFT_LIGHT_CONFIG_ENV,
+  type SiftLightConfig,
+} from "./config-reader.js";
+
+export {
+  DEFAULT_SIFT_LIGHT_CONFIG,
+  DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  normalizeSearchEnforcement,
+  resolveSiftLightConfigPath,
+  SIFT_LIGHT_CONFIG_ENV,
+  type ReadSiftLightConfigOptions,
+  type SiftLightConfig,
+  type SiftLightLocale,
+  type SearchEnforcementMode,
+  type SemanticJudgeConfig,
+  type SemanticJudgeProvider,
+} from "./config-reader.js";
+
+export function siftLightConfigPath(
+  agentDir = getAgentDir(),
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolveSiftLightConfigPath(agentDir, environment);
+}
+
+export async function readSiftLightConfig(
+  agentDir = getAgentDir(),
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<SiftLightConfig> {
+  return readSiftLightConfigFile(siftLightConfigPath(agentDir, environment), {
+    missing: environment[SIFT_LIGHT_CONFIG_ENV]?.trim() ? "error" : "defaults",
+  });
+}

package/src/context-budget.ts

@@ -0,0 +1,26 @@
+import type { ContextUsage } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_BUDGET_POLICY, type ContextBudget, type ContextBudgetTier } from "./types.js";
+
+function budgetTier(contextRemainderPercent: number): ContextBudgetTier {
+  if (contextRemainderPercent > CONTEXT_BUDGET_POLICY.fullAboveRemainderPercent) {
+    return "full";
+  }
+  if (contextRemainderPercent < CONTEXT_BUDGET_POLICY.criticalBelowRemainderPercent) {
+    return "critical";
+  }
+  return "tight";
+}
+
+/** Resolve one stable budget decision from the host's pre-call context usage. */
+export function resolveContextBudget(usage: ContextUsage | undefined): ContextBudget | undefined {
+  if (!usage || usage.tokens === null || usage.percent === null) return undefined;
+  if (!Number.isFinite(usage.percent) || usage.percent < 0 || usage.percent > 100) return undefined;
+
+  const contextRemainderPercent = Number((100 - usage.percent).toFixed(1));
+  const tier = budgetTier(contextRemainderPercent);
+  return {
+    tier,
+    contextRemainderPercent,
+    resultTokenBudget: CONTEXT_BUDGET_POLICY.resultTokenBudgets[tier],
+  };
+}

package/src/discovery-errors.ts

@@ -0,0 +1,2 @@
+export const DISCOVERY_MODE_REQUIRED_ERROR =
+  'query requires an explicit discovery mode: use mode=files for filename/path discovery or mode=concept for semantic discovery; for example {"mode":"files","query":"<filename-or-path>"}';

package/src/errors.ts

@@ -0,0 +1,95 @@
+export class SiftLightError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SiftLightError";
+  }
+}
+
+export type SiftLightRecoveryAction = "retry" | "choose-capability" | "manual";
+
+export interface SiftLightDiagnosticIssue {
+  field: string;
+  reason: string;
+}
+
+export interface SiftLightDiagnosticRecovery {
+  action: SiftLightRecoveryAction;
+  reason: string;
+  nextRequest?: Record<string, unknown>;
+}
+
+export interface SiftLightDiagnosticDetails {
+  code: string;
+  mode?: string;
+  issues: readonly SiftLightDiagnosticIssue[];
+  recovery: SiftLightDiagnosticRecovery;
+}
+
+export interface SiftLightDiagnosticError extends Error {
+  readonly details: SiftLightDiagnosticDetails;
+}
+
+/** A bounded Concept provider failure that hybrid retrieval may expose as skipped coverage. */
+export class ConceptUnavailableError extends SiftLightError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ConceptUnavailableError";
+  }
+}
+
+export type RipgrepInputErrorCode = "E_REGEX_INVALID" | "E_SEARCH_PATH_NOT_FOUND";
+
+/** A bounded, non-retrying diagnostic for an invalid search input at ripgrep's boundary. */
+export class RipgrepInputError extends SiftLightError {
+  readonly code: RipgrepInputErrorCode;
+  readonly guidance: string;
+  readonly details: SiftLightDiagnosticDetails;
+
+  constructor(code: RipgrepInputErrorCode, message: string, guidance: string) {
+    super(`${message} ${guidance}`);
+    this.name = "RipgrepInputError";
+    this.code = code;
+    this.guidance = guidance;
+    this.details = {
+      code,
+      issues: [
+        {
+          field: code === "E_REGEX_INVALID" ? "pattern" : "path",
+          reason: guidance,
+        },
+      ],
+      recovery: { action: "manual", reason: guidance },
+    };
+  }
+}
+
+export class CursorError extends SiftLightError {
+  readonly code:
+    | "E_CURSOR_MALFORMED"
+    | "E_CURSOR_NOT_FOUND"
+    | "E_CURSOR_EXPIRED"
+    | "E_CURSOR_WRONG_KIND"
+    | "E_CURSOR_OPTIONS_CONFLICT"
+    | "E_CURSOR_OFFSET_INVALID";
+
+  constructor(
+    message: string,
+    code:
+      | "E_CURSOR_MALFORMED"
+      | "E_CURSOR_NOT_FOUND"
+      | "E_CURSOR_EXPIRED"
+      | "E_CURSOR_WRONG_KIND"
+      | "E_CURSOR_OPTIONS_CONFLICT"
+      | "E_CURSOR_OFFSET_INVALID" = "E_CURSOR_MALFORMED",
+  ) {
+    super(`${code}: ${message}`);
+    this.name = "CursorError";
+    this.code = code;
+  }
+}
+
+export function abortError(): Error {
+  const error = new Error("Operation aborted");
+  error.name = "AbortError";
+  return error;
+}