sift-light 1.0.0 → 1.0.2

package/src/mcp-server.ts

@@ -8,10 +8,7 @@ import {
   createDefaultSiftLightMcpService,
   startSiftLightMcpServer,
 } from "./mcp.js";
-import {
-  createMcpSemanticJudgeIntegration,
-  mcpSemanticJudgeConfigSource,
-} from "./mcp-semantic-judge.js";
+import { createMcpSearchFeatures, mcpSemanticJudgeConfigSource } from "./mcp-semantic-judge.js";
 import type { SemanticJudgeIntegration } from "./semantic-judge.js";
 import { parseSiftLightMcpTransport, SIFT_LIGHT_MCP_USAGE } from "./mcp-cli.js";
 import { parseSiftLightMcpOutputMode, type SiftLightMcpOutputMode } from "./mcp-output.js";
@@ -41,10 +38,6 @@ function allowedOrigins(): string[] {
     .filter((origin) => origin.length > 0);
 }
 
-async function configuredSemanticJudge(): Promise<SemanticJudgeIntegration> {
-  return createMcpSemanticJudgeIntegration();
-}
-
 function logSemanticJudgeStatus(integration: SemanticJudgeIntegration): void {
   const status = integration.config.enabled ? "enabled" : "disabled";
   process.stderr.write(
@@ -55,12 +48,13 @@ function logSemanticJudgeStatus(integration: SemanticJudgeIntegration): void {
 async function runHttpServer(
   outputMode: SiftLightMcpOutputMode,
   semanticJudge: SemanticJudgeIntegration | undefined,
+  vectorSearchEnabled: boolean,
 ): Promise<void> {
   const running = await startSiftLightMcpServer({
     cwd: process.env.SIFT_LIGHT_MCP_CWD ?? process.cwd(),
     host: process.env.SIFT_LIGHT_MCP_HOST ?? DEFAULT_MCP_HOST,
     port: environmentInteger("SIFT_LIGHT_MCP_PORT", DEFAULT_MCP_PORT, 0, 65_535),
-    createService: () => createDefaultSiftLightMcpService(semanticJudge),
+    createService: () => createDefaultSiftLightMcpService(semanticJudge, vectorSearchEnabled),
     maxSessions: environmentInteger(
       "SIFT_LIGHT_MCP_MAX_SESSIONS",
       DEFAULT_MCP_MAX_SESSIONS,
@@ -108,11 +102,12 @@ async function runHttpServer(
 async function runStdioServer(
   outputMode: SiftLightMcpOutputMode,
   semanticJudge: SemanticJudgeIntegration | undefined,
+  vectorSearchEnabled: boolean,
 ): Promise<void> {
   const running = await startSiftLightMcpStdioServer({
     cwd: process.env.SIFT_LIGHT_MCP_CWD ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
     outputMode,
-    createService: () => createDefaultSiftLightMcpService(semanticJudge),
+    createService: () => createDefaultSiftLightMcpService(semanticJudge, vectorSearchEnabled),
   });
   process.stderr.write("sift-light MCP serving one local client over stdio\n");
   process.stderr.write(`sift-light MCP working directory: ${running.cwd}\n`);
@@ -140,13 +135,16 @@ async function main(): Promise<void> {
     return;
   }
   const outputMode = parseSiftLightMcpOutputMode(process.env.SIFT_LIGHT_MCP_OUTPUT_MODE);
-  const semanticJudge = await configuredSemanticJudge();
+  const { semanticJudge, vectorSearchEnabled } = await createMcpSearchFeatures();
   logSemanticJudgeStatus(semanticJudge);
+  process.stderr.write(
+    `sift-light MCP vector search: ${vectorSearchEnabled ? "enabled" : "disabled"}\n`,
+  );
   if (transport === "stdio") {
-    await runStdioServer(outputMode, semanticJudge);
+    await runStdioServer(outputMode, semanticJudge, vectorSearchEnabled);
     return;
   }
-  await runHttpServer(outputMode, semanticJudge);
+  await runHttpServer(outputMode, semanticJudge, vectorSearchEnabled);
 }
 
 try {

package/src/mcp.ts

@@ -93,12 +93,14 @@ export interface SiftLightMcpService {
 
 export function createDefaultSiftLightMcpService(
   semanticJudge?: SemanticJudgeIntegration,
+  vectorSearchEnabled = false,
 ): SiftLightMcpService {
   const resolvedSemanticJudge =
     semanticJudge ?? createDisabledSemanticJudgeIntegration(DEFAULT_SEMANTIC_JUDGE_CONFIG);
   return new SiftLightService({
     runRipgrep: createRipgrepRunner(),
     structure: createCtagsStructureProvider(),
+    vectorSearchEnabled,
     semanticJudge: resolvedSemanticJudge,
   });
 }

package/src/model-error.ts

@@ -73,19 +73,14 @@ export interface RequestContractProjection {
   text: string;
 }
 
-function projectRequestContract(
-  projected: RequestContractDetails,
-  serialized: string,
-  message: string,
-): string {
-  const prefix = `sift-light failed: request rejected [${projected.code}]: ${message}`;
+function projectRequestContract(projected: RequestContractDetails, serialized: string): string {
   const recovery = projected.recovery;
   const next = recovery.nextRequest
     ? "\nCopy the nested recovery.nextRequest object unchanged; do not repeat the original query."
-    : `\nRecovery action: ${recovery.action}. ${recovery.reason}`;
+    : `\nRecovery action: ${recovery.action}.`;
   // Put the machine payload first so simple host adapters that locate the
   // first `nextRequest` marker see the exact nested request object.
-  return `\nError details: ${serialized}\n${prefix}${next}`;
+  return `\nsift-light failed: request rejected [${projected.code}].\nError details: ${serialized}${next}`;
 }
 
 /** Build the one bounded contract projection consumed by structured and text hosts. */
@@ -94,11 +89,10 @@ export function requestContractProjection(
 ): RequestContractProjection {
   const details = boundedRequestContractDetails(error.details);
   const serializedDetails = JSON.stringify(details);
-  const boundedMessage = error.message.toWellFormed().slice(0, 1_024);
-  const result = projectRequestContract(details, serializedDetails, boundedMessage);
+  const result = projectRequestContract(details, serializedDetails);
   if (Buffer.byteLength(result) <= MAX_REQUEST_RECOVERY_BYTES) return { details, text: result };
   const compact: RequestContractDetails = {
-    code: boundedMessage.length > 0 ? details.code : "E_REQUEST_CONTRACT_PAYLOAD",
+    code: details.code,
     ...(details.mode ? { mode: details.mode } : {}),
     issues: [
       {
@@ -111,10 +105,6 @@ export function requestContractProjection(
       reason: "Exact recovery was omitted; correct the request explicitly.",
     },
   };
-  const compactText = projectRequestContract(
-    compact,
-    JSON.stringify(compact),
-    "The request-contract error exceeded the bounded payload budget; correct the request explicitly.",
-  );
+  const compactText = projectRequestContract(compact, JSON.stringify(compact));
   return { details: compact, text: compactText };
 }

package/src/omp-index.ts

@@ -1,7 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
-  DEFAULT_SEMANTIC_JUDGE_CONFIG,
   normalizeSearchEnforcement,
   readSiftLightConfigFile,
   resolveSiftLightConfigPath,
@@ -27,7 +26,7 @@ import {
 } from "./search-policy.js";
 import { siftLightSchema } from "./tool-schema.js";
 import { modelErrorText } from "./model-error.js";
-import { createSemanticJudgeIntegration } from "./semantic-judge.js";
+import { createConfiguredSemanticJudgeIntegration } from "./semantic-judge.js";
 
 const SIFT_LIGHT_LABEL = "sift-light";
 const OMP_REPLACED_SEARCH_TOOLS = new Set(["grep", "glob"]);
@@ -188,13 +187,12 @@ export async function registerOmpSiftLightExtension(
     (await readSiftLightConfigFile(resolveSiftLightConfigPath(ompAgentDir()), {
       missing: process.env[SIFT_LIGHT_CONFIG_ENV]?.trim() ? "error" : "defaults",
     }));
-  const semanticJudge = createSemanticJudgeIntegration(
-    resolvedConfig.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG,
-  );
+  const semanticJudge = createConfiguredSemanticJudgeIntegration(resolvedConfig);
   const runtime = new SiftLightRuntime(
     new SiftLightService({
       runRipgrep: createRipgrepRunner(),
       structure: createCtagsStructureProvider(),
+      vectorSearchEnabled: resolvedConfig.vectorSearchEnabled === true,
       semanticJudge,
     }),
   );
@@ -218,7 +216,7 @@ export async function registerOmpSiftLightExtension(
     name: SIFT_LIGHT_LABEL,
     label: SIFT_LIGHT_LABEL,
     description:
-      "Search and navigate code with bounded, verifiable evidence. Use pattern for content or mode=files with query for filenames.",
+      "Search code with bounded evidence. Routine searches use pattern for fast exact content or mode=files with query for filenames; concept/hybrid require vectorSearchEnabled:true in sift-light.json.",
     approval: "read",
     promptSnippet: "Search file contents without flooding context",
     promptGuidelines: siftLightPromptGuidelines(),

package/src/prompt-guidelines.ts

@@ -5,7 +5,7 @@ const SOURCE_OUTPUT_GUIDANCE =
 
 export function siftLightPromptGuidelines(structuredOutput = true): string[] {
   return [
-    `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
+    `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} For routine development searches, start with fast exact content, filename or applicable structural modes when the request has a usable name, symbol, error text or other literal clue. Omitted mode is ordinary exact search and never loads the local embedding model. Vector search is disabled by default; concept/hybrid require vectorSearchEnabled:true in sift-light.json and an installed model. They can take tens of seconds on an uncached scope, so select them only when semantic recall is needed. Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
     `An omitted path searches the project cwd. Use scope:"strict" for a question restricted to one path; otherwise, if an explicit subpath has zero matches, ordinary and content-analysis searches retry from cwd and return project-wide counts with an expansion notice. Explicit absolute paths and .. traversal can search outside cwd, except protected external system areas and .git internals. Git changes mode remains cwd-scoped.`,
     `Search output includes counts, categories, ranked paths, coverage and continuation metadata. Source excerpts may contain the searched text. Use mode="inspect" or the host read capability when exact source is required for an edit or verification.`,
     `Use file and directory distributions to choose evidence. Reuse the visible cursor with path or paths for match metadata; mode="summary" pages the remaining file statistics. Match counts are not relevance scores.`,
@@ -14,7 +14,7 @@ export function siftLightPromptGuidelines(structuredOutput = true): string[] {
     `Use anyOf:["term1","term2"] when every exact occurrence of 2-64 literals is needed in one version-bound result. It is case-sensitive, reports anonymized condition counts, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
     `For a changed-code question, add changes:{base:"HEAD",scope:"lines",side:"new"}; omit target for the working tree, use side:"old" for deleted-side statistics. Copy returned continuation requests to preserve source versions.`,
     `Use mode:"capabilities" when the language or requested operation is unclear to get a compact lazy inventory. Use mode:"outline" with a concrete source file path for symbol counts and locations, mode:"imports" for static relationships, and mode:"tests" for related-test candidates. Their text pages summarize metadata; structured details can retain source evidence.`,
-    `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; business concepts belong in hybrid/concept. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
+    `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; use hybrid/concept only for business concepts that cannot be located by a literal clue. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
     `Use mode:"structure" only for JS/TS/TSX/Go, with a required nonempty ast-grep pattern such as "compare($X, $X)" or "send()" for code shapes across whitespace; the text page reports structural counts and locations; structured details can retain matched source evidence.`,
     `Use mode:"concept" plus a natural-language query when names are unknown. It runs a pinned local multilingual model only after explicit installation; no search downloads weights or sends code to a remote model. Results expose candidate counts, score statistics, paths and the bounded ranked passage behind each candidate. Similarity scores identify candidates, not correctness.`,
     `Use mode:"hybrid" plus query when wording may differ from the source. It reports exact and semantic counts separately, removes overlap, and retains one pageable evidence snapshot. conceptLimit changes only the semantic candidate count; retained candidates keep their bounded source passages.`,
@@ -28,9 +28,9 @@ export function siftLightPromptGuidelines(structuredOutput = true): string[] {
 
 function siftLightModelGuidelines(): string[] {
   return [
-    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Omit mode/limit for automatic detail/summary selection. Compact model analysis pages may defer source excerpts to inspect.`,
-    `Use ranked paths and condition counts to choose evidence. Cursor continuation pages the retained snapshot; summary file selection returns ordinary match metadata. Use mode="inspect" when an edit requires exact source.`,
-    `Modes: capabilities for language prerequisites; files+query for filenames; anyOf/allOf for literal condition statistics; outline/imports/tests for structural and relationship summaries; structure for AST match statistics; concept/hybrid for semantic candidate statistics. Similarity and static links are not proof.`,
+    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Default search is exact and model-free. concept/hybrid require vectorSearchEnabled:true in sift-light.json plus an installed model; uncached runs may take tens of seconds. Omit mode/limit for auto pages.`,
+    `Use ranked paths and counts; Cursor continuation pages retained results. Use mode="inspect" for exact source before editing.`,
+    `Modes: files+query for filenames; anyOf/allOf for literals; outline/imports/tests for static code; structure for AST; concept/hybrid for semantic candidates. Similarity is not proof.`,
     `On rejection keep the strongest applicable mode and apply the stated repair once. Do not repeat the rejected request or include its error. Only explicit capability-unavailable permits a visibly partial alternative.`,
   ];
 }

package/src/python-roles.ts

@@ -0,0 +1,247 @@
+import type { SourceDocument } from "./source-document.js";
+import type { SyntaxAnalysis, SyntaxRole } from "./syntax-types.js";
+
+/**
+ * Bounded lexical role scanner for Python.
+ *
+ * It separates comments, string literals and code exactly, and marks `def`/`class`
+ * names, import statements and call-shaped callees. It does not parse Python:
+ * comments, strings and code are lexical facts ("syntax" certainty); a call is a
+ * name followed by `(` in code and therefore stays a "candidate". Offsets are
+ * UTF-16 indices into `document.text`, like every other role provider.
+ */
+
+const KEYWORDS = new Set([
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "case",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "match",
+  "nonlocal",
+  "not",
+  "or",
+  "raise",
+  "return",
+  "while",
+  "with",
+  "yield",
+]);
+const STRING_PREFIX = /^(?:[rRbBuUfF]|[rR][bBfF]|[bBfF][rR])?$/u;
+const IDENTIFIER_START = /[\p{ID_Start}_]/u;
+const IDENTIFIER_PART = /[\p{ID_Continue}]/u;
+
+interface Span {
+  start: number;
+  end: number;
+}
+
+interface Lexed {
+  comments: Span[];
+  strings: Span[];
+  /** `true` at each UTF-16 index that belongs to code (outside comments/strings). */
+  code: Uint8Array;
+}
+
+function lex(text: string): Lexed {
+  const comments: Span[] = [];
+  const strings: Span[] = [];
+  const code = new Uint8Array(text.length).fill(1);
+  const mark = (start: number, end: number): void => {
+    code.fill(0, start, end);
+  };
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === "#") {
+      const newline = text.indexOf("\n", index);
+      const end = newline < 0 ? text.length : newline;
+      comments.push({ start: index, end });
+      mark(index, end);
+      index = end;
+      continue;
+    }
+    if (character !== "'" && character !== '"') {
+      index += 1;
+      continue;
+    }
+    // A string prefix (r, b, f, u and their pairs) is part of the literal.
+    let prefixStart = index;
+    while (prefixStart > 0 && /[rRbBuUfF]/u.test(text[prefixStart - 1] ?? "")) prefixStart -= 1;
+    const prefix = text.slice(prefixStart, index);
+    const beforePrefix = text[prefixStart - 1] ?? "";
+    const start =
+      STRING_PREFIX.test(prefix) && !IDENTIFIER_PART.test(beforePrefix) ? prefixStart : index;
+    const triple = text.slice(index, index + 3) === character.repeat(3);
+    const delimiter = triple ? character.repeat(3) : character;
+    let cursor = index + delimiter.length;
+    let end = text.length;
+    while (cursor < text.length) {
+      const current = text[cursor];
+      // A backslash always protects the next character from ending the literal,
+      // including in raw strings (where the backslash itself is kept).
+      if (current === "\\") {
+        cursor += 2;
+        continue;
+      }
+      if (!triple && current === "\n") {
+        end = cursor;
+        break;
+      }
+      if (text.startsWith(delimiter, cursor)) {
+        end = cursor + delimiter.length;
+        break;
+      }
+      cursor += 1;
+    }
+    strings.push({ start, end });
+    mark(start, end);
+    index = end;
+  }
+  return { comments, strings, code };
+}
+
+function codeRanges(code: Uint8Array): Span[] {
+  const ranges: Span[] = [];
+  let start = -1;
+  for (let index = 0; index <= code.length; index += 1) {
+    const inCode = index < code.length && code[index] === 1;
+    if (inCode && start < 0) start = index;
+    else if (!inCode && start >= 0) {
+      ranges.push({ start, end: index });
+      start = -1;
+    }
+  }
+  return ranges;
+}
+
+function identifierEnd(text: string, start: number): number {
+  let end = start;
+  while (end < text.length && IDENTIFIER_PART.test(text[end] ?? "")) end += 1;
+  return end;
+}
+
+function skipSpaces(text: string, index: number, code: Uint8Array): number {
+  let cursor = index;
+  while (cursor < text.length && code[cursor] === 1 && /[ \t]/u.test(text[cursor] ?? ""))
+    cursor += 1;
+  return cursor;
+}
+
+/** Index after the statement starting at `start`, following parenthesized continuation lines. */
+function statementEnd(text: string, start: number, code: Uint8Array): number {
+  let depth = 0;
+  for (let index = start; index < text.length; index += 1) {
+    if (code[index] !== 1) continue;
+    const character = text[index];
+    if (character === "(" || character === "[" || character === "{") depth += 1;
+    else if (character === ")" || character === "]" || character === "}")
+      depth = Math.max(0, depth - 1);
+    else if (character === "\\" && text[index + 1] === "\n") index += 1;
+    else if (character === "\n" && depth === 0) return index;
+  }
+  return text.length;
+}
+
+export function pythonRoleAnalysis(document: SourceDocument): SyntaxAnalysis {
+  const text = document.text;
+  const { comments, strings, code } = lex(text);
+  const roles: SyntaxRole[] = [];
+  const push = (
+    start: number,
+    end: number,
+    role: SyntaxRole["role"],
+    certainty: SyntaxRole["certainty"],
+    subkind?: string,
+  ): void => {
+    if (start < end)
+      roles.push({ start, end, role, certainty, node: 0, ...(subkind ? { subkind } : {}) });
+  };
+  for (const span of comments) push(span.start, span.end, "comment", "syntax");
+  for (const span of strings) push(span.start, span.end, "string", "syntax");
+  for (const span of codeRanges(code)) push(span.start, span.end, "code", "syntax");
+
+  let index = 0;
+  let lineStart = true;
+  while (index < text.length) {
+    const character = text[index] ?? "";
+    if (character === "\n") {
+      lineStart = true;
+      index += 1;
+      continue;
+    }
+    if (code[index] !== 1 || !IDENTIFIER_START.test(character)) {
+      if (!/[ \t]/u.test(character)) lineStart = false;
+      index += 1;
+      continue;
+    }
+    const previous = text[index - 1] ?? "";
+    if (IDENTIFIER_PART.test(previous)) {
+      index += 1;
+      continue;
+    }
+    const end = identifierEnd(text, index);
+    const word = text.slice(index, end);
+    const atStatementStart = lineStart;
+    lineStart = false;
+    if (atStatementStart && (word === "import" || word === "from")) {
+      const statement = statementEnd(text, index, code);
+      const body = text.slice(index, statement);
+      if (word === "import" || /\bimport\b/u.test(body)) {
+        push(index, statement, "import", "syntax", word === "from" ? "from-import" : "import");
+        index = statement;
+        continue;
+      }
+    }
+    if (word === "def" || word === "class") {
+      const nameStart = skipSpaces(text, end, code);
+      if (IDENTIFIER_START.test(text[nameStart] ?? "")) {
+        const nameEnd = identifierEnd(text, nameStart);
+        push(nameStart, nameEnd, "declaration", "syntax", word === "def" ? "function" : "class");
+        index = nameEnd;
+        continue;
+      }
+    }
+    // Attribute chains such as `client.fetch(` are one callee.
+    let chainEnd = end;
+    while (text[chainEnd] === "." && IDENTIFIER_START.test(text[chainEnd + 1] ?? "")) {
+      chainEnd = identifierEnd(text, chainEnd + 1);
+    }
+    const open = skipSpaces(text, chainEnd, code);
+    const lastSegment = text.slice(text.lastIndexOf(".", chainEnd - 1) + 1, chainEnd);
+    const before = text.slice(Math.max(0, index - 4), index);
+    if (
+      text[open] === "(" &&
+      code[open] === 1 &&
+      !KEYWORDS.has(word) &&
+      !KEYWORDS.has(lastSegment) &&
+      !/\bdef\s+$|\bclass\s+$/u.test(before)
+    ) {
+      push(index, open + 1, "call", "candidate", "lexical-call");
+    }
+    index = chainEnd;
+  }
+  roles.sort((a, b) => a.start - b.start || a.end - b.end || a.role.localeCompare(b.role));
+  return {
+    status: "ok",
+    nodes: [],
+    children: [],
+    symbols: [],
+    roles,
+    diagnostics: [],
+    limited: false,
+  };
+}

package/src/redaction.ts

@@ -7,6 +7,10 @@ const SENSITIVE_ASSIGNMENT = new RegExp(
   "gi",
 );
 const SENSITIVE_TOKEN = /\b(?:sk|ghp|xox[baprs])[-_][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/g;
+// An unquoted value that starts as a call or index expression (`env.get(`,
+// `os.environ[`) is source code that reads a secret, not the secret itself.
+// Masking it hides the evidence a reader needs, such as which key is read.
+const CODE_EXPRESSION = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\s*[([]/u;
 const TYPE_ONLY_VALUES = new Set([
   "boolean",
   "number",
@@ -27,9 +31,12 @@ function redactString(value: string): { value: string; count: number } {
     SENSITIVE_ASSIGNMENT,
     (match: string, prefix: string, rawValue: string) => {
       const unquoted = rawValue.replace(/^["']|["']$/g, "").toLowerCase();
-      if (TYPE_ONLY_VALUES.has(unquoted)) return match;
+      if (TYPE_ONLY_VALUES.has(unquoted) || CODE_EXPRESSION.test(rawValue)) return match;
       count += 1;
-      return `${prefix}"[REDACTED]"`;
+      // Keep the source's own quoting: adding quotes to an unquoted value would
+      // misrepresent the file (for example, a bare `.env` value shown as quoted).
+      const quote = rawValue.startsWith('"') || rawValue.startsWith("'") ? rawValue[0] : "";
+      return `${prefix}${quote}[REDACTED]${quote}`;
     },
   );
   redacted = redacted.replace(SENSITIVE_TOKEN, () => {

package/src/request-aliases.ts

@@ -0,0 +1,48 @@
+import { SiftLightError } from "./errors.js";
+import type { SiftLightInput } from "./service.js";
+
+/**
+ * Field names that callers commonly send as a mode. They are not modes: the field
+ * alone selects the multi-term search. The schema accepts them so the request can
+ * be served, and the result discloses the normalization.
+ */
+export const MODE_ALIASES = ["anyOf", "allOf"] as const;
+export type ModeAlias = (typeof MODE_ALIASES)[number];
+
+/** Public request shape before alias normalization. */
+export type SiftLightRequest = Omit<SiftLightInput, "mode"> & {
+  mode?: SiftLightInput["mode"] | ModeAlias;
+};
+
+export interface NormalizedRequest {
+  input: SiftLightInput;
+  notes: string[];
+}
+
+/**
+ * The single place where unambiguous request shapes are rewritten before the
+ * mode contract runs. Every rewrite preserves the requested scope and evidence
+ * semantics and is reported back as a note; anything ambiguous still fails.
+ */
+export function normalizeRequestAliases(request: SiftLightRequest): NormalizedRequest {
+  const notes: string[] = [];
+  const { mode, ...rest } = request;
+  let input: SiftLightInput = rest;
+  if (mode === "anyOf" || mode === "allOf") {
+    if (request[mode] === undefined)
+      throw new SiftLightError(`mode=${mode} is not a mode; pass ${mode}:[...terms] and omit mode`);
+    notes.push(`mode="${mode}" is not a mode; the ${mode} field alone selects this search.`);
+  } else if (mode === "summary" && request.anyOf !== undefined) {
+    notes.push(
+      "anyOf returns one analysis page whose header already carries per-file statistics; mode=summary was served by that page.",
+    );
+  } else if (mode !== undefined) {
+    input = { ...rest, mode };
+  }
+  if (input.sourceCursor !== undefined && input.line !== undefined) {
+    const { line: _line, ...withoutLine } = input;
+    input = withoutLine;
+    notes.push("line is ignored with sourceCursor; the continuation selects its own source range.");
+  }
+  return { input, notes };
+}

package/src/request-contract-catalog.ts

@@ -62,7 +62,17 @@ export const MODE_FIELDS_BY_MODE: Record<SiftLightMode, readonly RequestField[]>
   auto: ordinaryFields,
   summary: ordinaryFields,
   matches: ordinaryFields,
-  inspect: [...commonFields, "path", "line", "cursor", "matchIndex", "matchIndices", "targets"],
+  inspect: [
+    ...commonFields,
+    "path",
+    "paths",
+    "line",
+    "cursor",
+    "matchIndex",
+    "matchIndices",
+    "targets",
+    "scope",
+  ],
   outline: [...commonFields, "path", "line", "symbol", "cursor", "matchIndex", "maxFilesToParse"],
   imports: [
     ...commonFields,
@@ -82,7 +92,16 @@ export const MODE_FIELDS_BY_MODE: Record<SiftLightMode, readonly RequestField[]>
     "matchIndex",
     "maxFilesToParse",
   ],
-  files: [...commonFields, "query", ...sourceFilters, "modifiedAfter", "modifiedBefore"],
+  files: [
+    ...commonFields,
+    "query",
+    ...sourceFilters,
+    "ignorePolicy",
+    "limit",
+    "scope",
+    "modifiedAfter",
+    "modifiedBefore",
+  ],
   structure: [...commonFields, "pattern", ...sourceFilters, "maxFilesToParse"],
   concept: [...commonFields, "query", ...sourceFilters, "maxFilesToParse"],
   hybrid: [...commonFields, "query", ...sourceFilters, "conceptLimit", "maxFilesToParse"],
@@ -92,9 +111,7 @@ export const MODE_FIELDS_BY_MODE: Record<SiftLightMode, readonly RequestField[]>
   cancel: ["mode", "operationId"],
 };
 
-export const SAFE_DROP_FIELDS: Partial<Record<SiftLightMode, readonly RequestField[]>> = {
-  files: ["scope"],
-};
+export const SAFE_DROP_FIELDS: Partial<Record<SiftLightMode, readonly RequestField[]>> = {};
 
 export const SUPPORTED_OUTLINE_EXTENSIONS = new Set(
   DEFAULT_LANGUAGE_CAPABILITIES.flatMap((descriptor) =>
@@ -149,9 +166,9 @@ export const REQUEST_FIELD_GUIDANCE: Partial<Record<RequestField, string>> = {
   context: "context is an output-context budget and is never silently dropped",
   limit: "limit is an output/page budget and is never silently dropped",
   scope:
-    "scope applies to ordinary content search; mode=files rejects this field because its scope is fixed strict, and only redundant strict may be removed",
+    "scope applies to ordinary content search; mode=files is always strict, so it accepts only the redundant scope=strict",
   ignorePolicy:
-    "respect keeps repository ignore rules; include searches ignored files but always excludes .git internals and protected paths",
+    "respect keeps repository ignore rules and discloses ignored files; include also searches or lists ignored files but always excludes .git internals and protected paths",
   patterns: "audit accepts named exact-literal patterns and returns one closure receipt",
   maxFilesToParse:
     "concept/hybrid automatically batch the requested scope; this optional field sets an advanced hard file ceiling",