sift-light 1.0.0 → 1.0.2

package/plugins/sift-light/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": true,
   "type": "module",
   "omp": {

package/src/analysis-limits.ts

@@ -13,7 +13,7 @@ export const MAX_ANALYSIS_STORAGE_BYTES = 32 * 1024 * 1024;
 export const ANALYSIS_METADATA_RESERVE_BYTES = 64 * 1024;
 export const MAX_ANALYSIS_REASONS = 64;
 export const MAX_ANALYSIS_REASON_BYTES = 4 * 1024;
-export const MIN_ANY_OF_TERMS = 2;
+export const MIN_ANY_OF_TERMS = 1;
 export const MAX_ANY_OF_TERMS = 8;
 /** Public union size; execution keeps the proven eight-term scan boundary per chunk. */
 export const MAX_ANY_OF_TOTAL_TERMS = 64;

package/src/analysis-store.ts

@@ -206,7 +206,10 @@ function publicAnalysisItem(
   return {
     path: item.path,
     line: item.line,
-    label: result.kind === "outline" && modelOutput ? item.label : publicAnalysisLabel(result),
+    label:
+      (result.kind === "outline" && modelOutput) || result.kind === "files"
+        ? item.label
+        : publicAnalysisLabel(result),
     index: index + 1,
     ...(inspect ? { inspect } : {}),
     ...(publicDetails ? { details: publicDetails } : {}),
@@ -455,7 +458,8 @@ export class AnalysisStore {
         if (items.length >= 30 || !appendItem(index)) break;
       }
     } else {
-      for (let index = offset; index < result.items.length && items.length < 30; index += 1) {
+      const pageSize = result.pageSize ?? 30;
+      for (let index = offset; index < result.items.length && items.length < pageSize; index += 1) {
         if (!appendItem(index)) break;
       }
     }

package/src/analysis-types.ts

@@ -4,7 +4,12 @@ import type { SearchScopeDetails, ResultStatistics } from "./types.js";
 import type { ValidationDetails } from "./validation-types.js";
 import type { ConceptSourceSummary } from "./concept-source-generation.js";
 
-export type CoverageStatus = "complete" | "partial" | "skipped" | "not-applicable";
+export type CoverageStatus =
+  | "complete"
+  | "partial"
+  | "policy-filtered"
+  | "skipped"
+  | "not-applicable";
 
 export const SEMANTIC_JUDGE_CLASSIFICATIONS = [
   "implementation-candidate",
@@ -125,6 +130,8 @@ export interface AnalysisDetails {
     passagesRanked?: number;
     elapsedMs?: number;
     filesEnumerated?: number;
+    ignoredFiles?: number;
+    ignoredMatches?: number;
     filesAdmitted?: number;
     filesParsed?: number;
     filesSkipped?: number;
@@ -159,4 +166,6 @@ export interface AnalysisResultSet {
   stats?: AnalysisDetails["stats"];
   sourceGeneration?: ConceptSourceSummary;
   redact?: boolean;
+  /** Explicit output page size (`limit`); pages default to 30 items. */
+  pageSize?: number;
 }

package/src/concept-inference.ts

@@ -21,7 +21,9 @@ export interface ConceptEmbeddingCallbacks {
   ) => void | Promise<void>;
 }
 
-const INFERENCE_BATCH_SIZE = 16;
+// Bound each ONNX call to four model windows. Larger native batches raised peak
+// RSS without a useful cold-start gain on the measured workload.
+const INFERENCE_BATCH_SIZE = 4;
 
 /** Snap a candidate UTF-16 index so it never splits a surrogate pair. */
 export function safeUtf16End(text: string, end: number): number {
@@ -62,6 +64,10 @@ export function maximumTokenSafeEnd(
   text: string,
   start: number,
 ): number {
+  // Most source passages already fit the model window. Avoid repeatedly
+  // tokenizing prefixes of the same passage in the binary-search path.
+  if (tokenCount(extractor, `${prefix}${text.slice(start)}`) <= CONCEPT_MODEL_TOKENS)
+    return text.length;
   let low = start + 1;
   let high = text.length;
   let accepted = start;
@@ -142,30 +148,56 @@ export async function embedConceptInputs(
 ): Promise<CachedConceptEmbedding[]> {
   const layouts = pending.map((item) => tokenSafeWindows(extractor, item));
   const inputs = layouts.flatMap((windows) => windows.map((window) => window.input));
-  const vectors: number[][] = [];
+  const vectors: (number[] | undefined)[] = Array(inputs.length);
   const layoutEnds: number[] = [];
+  const remainingWindows = layouts.map((windows) => windows.length);
   let layoutEnd = 0;
   for (const windows of layouts) {
     layoutEnd += windows.length;
     layoutEnds.push(layoutEnd);
   }
+  const orderedInputs = inputs
+    .map((input, index) => ({ input, index, tokens: tokenCount(extractor, input) }))
+    // Start with the largest shapes so the native arena can reuse allocations
+    // for smaller batches instead of retaining a growing sequence of arenas.
+    .toSorted((left, right) => right.tokens - left.tokens || left.index - right.index);
+  const vectorFor = (index: number): number[] => {
+    const vector = vectors[index];
+    if (!vector) throw new Error("Missing concept embedding vector");
+    return vector;
+  };
+  const ownerOf = (index: number): number => {
+    let low = 0;
+    let high = layoutEnds.length;
+    while (low < high) {
+      const middle = Math.floor((low + high) / 2);
+      if (index < layoutEnds[middle]!) high = middle;
+      else low = middle + 1;
+    }
+    return low;
+  };
   let completedEmbedding = 0;
-  for (let offset = 0; offset < inputs.length; offset += INFERENCE_BATCH_SIZE) {
-    const batch = inputs.slice(offset, offset + INFERENCE_BATCH_SIZE);
+  let completedWindows = 0;
+  for (let offset = 0; offset < orderedInputs.length;) {
+    const orderedBatch = orderedInputs.slice(offset, offset + INFERENCE_BATCH_SIZE);
+    const batch = orderedBatch.map((item) => item.input);
     // oxlint-disable-next-line no-await-in-loop -- bounded batches cap native tensor memory.
     const tensor = await extractor(batch, { pooling: "mean", normalize: true });
     if (tensor.data.length !== batch.length * CONCEPT_EMBEDDING_DIMENSIONS)
       throw new Error("Unexpected concept embedding dimensions");
     for (let index = 0; index < batch.length; index += 1) {
       const start = index * CONCEPT_EMBEDDING_DIMENSIONS;
-      vectors.push(
-        Array.from(tensor.data.slice(start, start + CONCEPT_EMBEDDING_DIMENSIONS), Number),
+      const inputIndex = orderedBatch[index]!.index;
+      vectors[inputIndex] = Array.from(
+        tensor.data.slice(start, start + CONCEPT_EMBEDDING_DIMENSIONS),
+        Number,
       );
+      remainingWindows[ownerOf(inputIndex)]!--;
     }
-    const completedWindows = Math.min(offset + batch.length, inputs.length);
+    completedWindows += batch.length;
     while (
-      layoutEnds[completedEmbedding] !== undefined &&
-      layoutEnds[completedEmbedding]! <= completedWindows
+      remainingWindows[completedEmbedding] !== undefined &&
+      remainingWindows[completedEmbedding] === 0
     ) {
       const start = completedEmbedding === 0 ? 0 : layoutEnds[completedEmbedding - 1]!;
       const item = pending[completedEmbedding];
@@ -177,7 +209,7 @@ export async function embedConceptInputs(
           windows: (layouts[completedEmbedding] ?? []).map((window, index) => ({
             start: window.start,
             end: window.end,
-            vector: vectors[start + index] ?? [],
+            vector: vectorFor(start + index),
           })),
         },
         completedEmbedding + 1,
@@ -186,6 +218,7 @@ export async function embedConceptInputs(
       completedEmbedding += 1;
     }
     callbacks.onBatch?.(completedWindows, inputs.length);
+    offset += batch.length;
   }
   let vectorIndex = 0;
   return pending.map((item, index) => ({
@@ -193,7 +226,7 @@ export async function embedConceptInputs(
     windows: (layouts[index] ?? []).map((window) => ({
       start: window.start,
       end: window.end,
-      vector: vectors[vectorIndex++] ?? [],
+      vector: vectorFor(vectorIndex++),
     })),
   }));
 }

package/src/concept-model.ts

@@ -8,10 +8,10 @@ export const CONCEPT_MODEL = "Xenova/multilingual-e5-small";
 export const CONCEPT_REVISION = "761b726dd34fb83930e26aab4e9ac3899aa1fa78";
 export const MAX_CONCEPT_CHARS = 1_000;
 export const CONCEPT_PASSAGE_OVERLAP_CHARS = 160;
-export const CONCEPT_MODEL_TOKENS = 512;
+export const CONCEPT_MODEL_TOKENS = 256;
 export const CONCEPT_WINDOW_OVERLAP_TOKENS = 64;
 export const CONCEPT_EMBEDDING_DIMENSIONS = 384;
-export const CONCEPT_CACHE_VERSION = 1;
+export const CONCEPT_CACHE_VERSION = 2;
 export const CONCEPT_CACHE_MAX_BYTES = 512 * 1024 * 1024;
 export const CONCEPT_TIMEOUT_MS = 10 * 60_000;
 export const MIN_CONCEPT_TIMEOUT_MS = 1_000;

package/src/concept-search.ts

@@ -86,6 +86,14 @@ function scoreProfile(scores: readonly number[]): ConceptScoreProfile {
   };
 }
 
+/** E5 cosine scores favor very short, generic passages in close races. Keep the
+ * raw cosine as evidence and apply a bounded length correction only to rank. */
+export function conceptRankingScore(cosine: number, passageLength: number): number {
+  const referenceLength = 500;
+  const maximumCorrection = 0.02;
+  return cosine - maximumCorrection * (1 - Math.sqrt(Math.min(passageLength / referenceLength, 1)));
+}
+
 function passage(document: SourceDocument, start: number): { value: Passage; next: number } {
   let end = Math.min(document.text.length, start + MAX_CONCEPT_CHARS);
   if (end < document.text.length) {
@@ -433,6 +441,7 @@ async function runConceptSearch(
     const batchItems = passages.map((item, index) => {
       const similarity = inferred.scores[index];
       if (similarity === undefined) throw new Error("Missing concept similarity");
+      const rankingScore = conceptRankingScore(similarity, item.text.length);
       const evidence = rangeEvidence(item.document, item.range);
       return {
         path: item.document.path,
@@ -445,8 +454,9 @@ async function runConceptSearch(
           kind: "concept-candidate",
           certainty: "candidate",
           score: similarity,
+          rankingScore,
           rankingReason:
-            "local multilingual E5 cosine similarity; relevance candidate, no binding or execution claim",
+            "local multilingual E5 cosine similarity with bounded short-passage rank correction; relevance candidate, no binding or execution claim",
           model: CONCEPT_MODEL,
           revision: CONCEPT_REVISION,
           tokenTruncated: false,
@@ -457,7 +467,7 @@ async function runConceptSearch(
     });
     const ranked = [...result.items, ...batchItems].toSorted(
       (a, b) =>
-        Number(b.details?.score) - Number(a.details?.score) ||
+        Number(b.details?.rankingScore) - Number(a.details?.rankingScore) ||
         a.path.localeCompare(b.path) ||
         a.line - b.line,
     );

package/src/concept-worker.mjs

@@ -27,10 +27,10 @@ class SiftLightError extends Error {
 var CONCEPT_MODEL = "Xenova/multilingual-e5-small";
 var CONCEPT_REVISION = "761b726dd34fb83930e26aab4e9ac3899aa1fa78";
 var MAX_CONCEPT_CHARS = 1000;
-var CONCEPT_MODEL_TOKENS = 512;
+var CONCEPT_MODEL_TOKENS = 256;
 var CONCEPT_WINDOW_OVERLAP_TOKENS = 64;
 var CONCEPT_EMBEDDING_DIMENSIONS = 384;
-var CONCEPT_CACHE_VERSION = 1;
+var CONCEPT_CACHE_VERSION = 2;
 var CONCEPT_CACHE_MAX_BYTES = 512 * 1024 * 1024;
 var CONCEPT_TIMEOUT_MS = 10 * 60000;
 var MAX_CONCEPT_TIMEOUT_MS = 60 * 60000;
@@ -222,7 +222,7 @@ async function enforceConceptCacheLimit(root, maximumBytes = CONCEPT_CACHE_MAX_B
 }
 
 // src/concept-inference.ts
-var INFERENCE_BATCH_SIZE = 16;
+var INFERENCE_BATCH_SIZE = 4;
 function safeUtf16End(text, end) {
   if (end <= 0 || end >= text.length)
     return end;
@@ -247,6 +247,8 @@ function binarySearchBudget(span) {
   return 2 * Math.max(span, 1) + 32;
 }
 function maximumTokenSafeEnd(extractor, prefix, text, start) {
+  if (tokenCount(extractor, `${prefix}${text.slice(start)}`) <= CONCEPT_MODEL_TOKENS)
+    return text.length;
   let low = start + 1;
   let high = text.length;
   let accepted = start;
@@ -312,25 +314,49 @@ function tokenSafeWindows(extractor, pending) {
 async function embedConceptInputs(extractor, pending, callbacks = {}) {
   const layouts = pending.map((item) => tokenSafeWindows(extractor, item));
   const inputs = layouts.flatMap((windows) => windows.map((window) => window.input));
-  const vectors = [];
+  const vectors = Array(inputs.length);
   const layoutEnds = [];
+  const remainingWindows = layouts.map((windows) => windows.length);
   let layoutEnd = 0;
   for (const windows of layouts) {
     layoutEnd += windows.length;
     layoutEnds.push(layoutEnd);
   }
+  const orderedInputs = inputs.map((input, index) => ({ input, index, tokens: tokenCount(extractor, input) })).toSorted((left, right) => right.tokens - left.tokens || left.index - right.index);
+  const vectorFor = (index) => {
+    const vector = vectors[index];
+    if (!vector)
+      throw new Error("Missing concept embedding vector");
+    return vector;
+  };
+  const ownerOf = (index) => {
+    let low = 0;
+    let high = layoutEnds.length;
+    while (low < high) {
+      const middle = Math.floor((low + high) / 2);
+      if (index < layoutEnds[middle])
+        high = middle;
+      else
+        low = middle + 1;
+    }
+    return low;
+  };
   let completedEmbedding = 0;
-  for (let offset = 0;offset < inputs.length; offset += INFERENCE_BATCH_SIZE) {
-    const batch = inputs.slice(offset, offset + INFERENCE_BATCH_SIZE);
+  let completedWindows = 0;
+  for (let offset = 0;offset < orderedInputs.length; ) {
+    const orderedBatch = orderedInputs.slice(offset, offset + INFERENCE_BATCH_SIZE);
+    const batch = orderedBatch.map((item) => item.input);
     const tensor = await extractor(batch, { pooling: "mean", normalize: true });
     if (tensor.data.length !== batch.length * CONCEPT_EMBEDDING_DIMENSIONS)
       throw new Error("Unexpected concept embedding dimensions");
     for (let index = 0;index < batch.length; index += 1) {
       const start = index * CONCEPT_EMBEDDING_DIMENSIONS;
-      vectors.push(Array.from(tensor.data.slice(start, start + CONCEPT_EMBEDDING_DIMENSIONS), Number));
+      const inputIndex = orderedBatch[index].index;
+      vectors[inputIndex] = Array.from(tensor.data.slice(start, start + CONCEPT_EMBEDDING_DIMENSIONS), Number);
+      remainingWindows[ownerOf(inputIndex)]--;
     }
-    const completedWindows = Math.min(offset + batch.length, inputs.length);
-    while (layoutEnds[completedEmbedding] !== undefined && layoutEnds[completedEmbedding] <= completedWindows) {
+    completedWindows += batch.length;
+    while (remainingWindows[completedEmbedding] !== undefined && remainingWindows[completedEmbedding] === 0) {
       const start = completedEmbedding === 0 ? 0 : layoutEnds[completedEmbedding - 1];
       const item = pending[completedEmbedding];
       if (!item)
@@ -340,12 +366,13 @@ async function embedConceptInputs(extractor, pending, callbacks = {}) {
         windows: (layouts[completedEmbedding] ?? []).map((window, index) => ({
           start: window.start,
           end: window.end,
-          vector: vectors[start + index] ?? []
+          vector: vectorFor(start + index)
         }))
       }, completedEmbedding + 1, pending.length);
       completedEmbedding += 1;
     }
     callbacks.onBatch?.(completedWindows, inputs.length);
+    offset += batch.length;
   }
   let vectorIndex = 0;
   return pending.map((item, index) => ({
@@ -353,7 +380,7 @@ async function embedConceptInputs(extractor, pending, callbacks = {}) {
     windows: (layouts[index] ?? []).map((window) => ({
       start: window.start,
       end: window.end,
-      vector: vectors[vectorIndex++] ?? []
+      vector: vectorFor(vectorIndex++)
     }))
   }));
 }
@@ -504,7 +531,7 @@ async function search() {
       local_files_only: true,
       dtype: "q8",
       device: "cpu",
-      session_options: { intraOpNumThreads: 2, interOpNumThreads: 1 }
+      session_options: { intraOpNumThreads: 4, interOpNumThreads: 1 }
     });
     try {
       created = await embedConceptInputs(extractor, missing, {

package/src/concept-worker.ts

@@ -140,7 +140,7 @@ async function search(): Promise<void> {
       local_files_only: true,
       dtype: "q8",
       device: "cpu",
-      session_options: { intraOpNumThreads: 2, interOpNumThreads: 1 },
+      session_options: { intraOpNumThreads: 4, interOpNumThreads: 1 },
     });
     try {
       created = await embedConceptInputs(extractor, missing, {

package/src/config-reader.ts

@@ -12,6 +12,7 @@ export const SIFT_LIGHT_ENFORCEMENT_ENV = "SIFT_LIGHT_ENFORCE_SEARCH";
 export interface SiftLightConfig {
   locale: SiftLightLocale;
   enforceSearch?: SearchEnforcementMode;
+  vectorSearchEnabled?: boolean;
   semanticJudge?: SemanticJudgeConfig;
 }
 
@@ -44,12 +45,14 @@ export const DEFAULT_SEMANTIC_JUDGE_CONFIG: Readonly<SemanticJudgeConfig> = {
 export const DEFAULT_SIFT_LIGHT_CONFIG: Readonly<SiftLightConfig> = {
   locale: "en",
   enforceSearch: "hard",
+  vectorSearchEnabled: false,
   semanticJudge: DEFAULT_SEMANTIC_JUDGE_CONFIG,
 };
 
 interface RawSiftLightConfig {
   locale?: unknown;
   enforceSearch?: unknown;
+  vectorSearchEnabled?: unknown;
   semanticJudge?: unknown;
 }
 
@@ -221,21 +224,26 @@ function parseConfig(value: unknown, path: string): SiftLightConfig {
     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),
+    (key) => !["locale", "enforceSearch", "vectorSearchEnabled", "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`,
+      `Invalid sift-light config at ${path}: unsupported configuration fields; only locale, enforceSearch, vectorSearchEnabled and semanticJudge are accepted`,
     );
   }
-  const { locale, enforceSearch } = value;
+  const { locale, enforceSearch, vectorSearchEnabled } = 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"`);
   }
+  if (vectorSearchEnabled !== undefined && typeof vectorSearchEnabled !== "boolean") {
+    throw new Error(`Invalid sift-light config at ${path}: vectorSearchEnabled must be a boolean`);
+  }
   const enforcement = normalizeSearchEnforcement(enforceSearch, `config at ${path}`);
   return {
     locale: locale ?? DEFAULT_SIFT_LIGHT_CONFIG.locale,
     enforceSearch: enforcement,
+    vectorSearchEnabled:
+      vectorSearchEnabled ?? DEFAULT_SIFT_LIGHT_CONFIG.vectorSearchEnabled ?? false,
     semanticJudge: parseSemanticJudge(value.semanticJudge, path),
   };
 }

package/src/evidence-service.ts

@@ -39,7 +39,6 @@ import {
   continueSource,
   inspectDocuments,
   matchInspectionTarget,
-  inspectDocumentsMetadata,
   type SourceInspectionTarget,
 } from "./source-inspection.js";
 import { validateSavedEvidence } from "./evidence-validation.js";
@@ -48,6 +47,7 @@ import type { CodeStructureProvider } from "./structure.js";
 import { filterRoleOccurrences, findFunctionConjunctions } from "./syntax-search.js";
 import { syntaxLanguage } from "./syntax.js";
 import { parsePythonOutline } from "./python-outline.js";
+import { pythonRoleAnalysis } from "./python-roles.js";
 import {
   combineHybridSearch,
   hybridConceptLimit,
@@ -66,10 +66,12 @@ import {
   MAX_STRUCTURE_FILES,
 } from "./analysis-limits.js";
 import {
+  MAX_INSPECT_REQUEST_TARGETS,
   MAX_INSPECT_TARGETS,
   type SearchRequest,
   type SearchScopeDetails,
   type SiftLightResult,
+  type StructureDetails,
 } from "./types.js";
 
 export function isEvidenceRequest(input: SiftLightInput): boolean {
@@ -95,6 +97,100 @@ export function isEvidenceRequest(input: SiftLightInput): boolean {
   );
 }
 
+/**
+ * Splits one inspect request into the page served now and an exact request for
+ * the rest. `paths` without a cursor opens each file from line 1.
+ */
+function pageInspectRequest(input: SiftLightInput): {
+  current: SiftLightInput;
+  remaining?: SiftLightInput;
+} {
+  if (input.scope === "expand")
+    throw new SiftLightError(
+      "mode=inspect reads exact locations; scope=expand does not apply (omit scope)",
+    );
+  const { scope: _scope, paths, ...rest } = input;
+  let request: SiftLightInput = rest;
+  if (paths !== undefined) {
+    if (
+      input.cursor !== undefined ||
+      input.targets !== undefined ||
+      input.matchIndices !== undefined ||
+      input.path !== undefined ||
+      input.line !== undefined ||
+      input.matchIndex !== undefined
+    )
+      throw new SiftLightError(
+        "mode=inspect paths opens files from line 1 and cannot be combined with cursor, targets, matchIndices, path, line or matchIndex",
+      );
+    request = { ...rest, targets: paths.map((path) => ({ path, line: 1 })) };
+  }
+  const redact = input.redact ? { redact: true } : {};
+  const requested = request.targets?.length ?? request.matchIndices?.length ?? 0;
+  if (requested > MAX_INSPECT_REQUEST_TARGETS)
+    throw new SiftLightError(
+      `mode=inspect accepts at most ${String(MAX_INSPECT_REQUEST_TARGETS)} targets per request; ${String(MAX_INSPECT_TARGETS)} are inspected per response`,
+    );
+  if (request.targets && request.targets.length > MAX_INSPECT_TARGETS)
+    return {
+      current: { ...request, targets: request.targets.slice(0, MAX_INSPECT_TARGETS) },
+      remaining: {
+        mode: "inspect",
+        targets: request.targets.slice(MAX_INSPECT_TARGETS),
+        ...redact,
+      },
+    };
+  if (request.matchIndices && request.matchIndices.length > MAX_INSPECT_TARGETS)
+    return {
+      current: { ...request, matchIndices: request.matchIndices.slice(0, MAX_INSPECT_TARGETS) },
+      remaining: {
+        mode: "inspect",
+        ...(request.cursor !== undefined ? { cursor: request.cursor } : {}),
+        matchIndices: request.matchIndices.slice(MAX_INSPECT_TARGETS),
+        ...redact,
+      },
+    };
+  return { current: request };
+}
+
+/** The unserved targets stay explicit: the page is partial and names its exact continuation. */
+function withRemainingInspection(
+  result: SiftLightResult,
+  remaining: SiftLightInput,
+): SiftLightResult {
+  const count = remaining.targets?.length ?? remaining.matchIndices?.length ?? 0;
+  return {
+    text: `${result.text}\n\n[${String(count)} more target(s) were not inspected; one response inspects ${String(MAX_INSPECT_TARGETS)}.]\nNext request: ${JSON.stringify(remaining)}`,
+    details: {
+      ...result.details,
+      status: "partial",
+      snapshotComplete: false,
+      nextRequest: remaining,
+    },
+  };
+}
+
+/** Structure facts already proven by the analysis that produced a bounded item. */
+function analysisItemStructure(item: AnalysisItem): StructureDetails {
+  const details = item.details ?? {};
+  const language = typeof details.language === "string" ? details.language : undefined;
+  const name = typeof details.name === "string" ? details.name : undefined;
+  const scope = Array.isArray(details.scope)
+    ? details.scope.filter((entry): entry is string => typeof entry === "string")
+    : typeof details.scope === "string"
+      ? [details.scope]
+      : [];
+  const kind = details.kind === "function" ? "function" : (item.label.split(" ", 1)[0] ?? "symbol");
+  return {
+    status: "available",
+    provider: language === "python" ? "python-outline" : "tree-sitter",
+    ...(language ? { language } : {}),
+    ...(name
+      ? { symbol: { name, kind, scope, range: { startLine: item.line, endLine: item.line } } }
+      : {}),
+  };
+}
+
 export interface EvidenceSearchOptions {
   modelOutput?: boolean;
   onProgress?: (progress: OperationProgress) => void;
@@ -126,12 +222,12 @@ function validateTerms(input: SiftLightInput): string[] | undefined {
   }
   if (
     !Array.isArray(terms) ||
-    terms.length < 2 ||
+    terms.length < 1 ||
     terms.length > 3 ||
     terms.some((term) => typeof term !== "string" || !term.trim() || /[\r\n\0]/.test(term)) ||
     new Set(terms).size !== terms.length
   )
-    throw new SiftLightError("allOf requires 2–3 distinct, nonempty, single-line literal terms");
+    throw new SiftLightError("allOf requires 1–3 distinct, nonempty, single-line literal terms");
   if (
     input.pattern !== undefined ||
     input.roles !== undefined ||
@@ -396,13 +492,13 @@ export class EvidenceService {
       if (typeof input.sourceCursor !== "string" || !input.sourceCursor.trim())
         throw new CursorError("A nonempty sourceCursor is required");
       if (input.mode !== "inspect") throw new SiftLightError("sourceCursor requires mode=inspect");
-      return continueSource(input.sourceCursor, access, this.#continuations);
+      return continueSource(input.sourceCursor, access, this.#continuations, input.path);
     }
     if (input.mode === "inspect") {
-      const targets = this.#inspectionTargets(input, cwd);
-      return targets.some((target) => target.range !== undefined)
-        ? inspectDocumentsMetadata(targets, access, this.#structure)
-        : inspectDocuments(targets, access, this.#continuations, this.#structure);
+      const { current, remaining } = pageInspectRequest(input);
+      const targets = this.#inspectionTargets(current, cwd);
+      const result = await inspectDocuments(targets, access, this.#continuations, this.#structure);
+      return remaining ? withRemainingInspection(result, remaining) : result;
     }
     if (input.mode === "concept") {
       const execution = await this.#conceptSearch(input, access, options.onProgress);
@@ -518,7 +614,7 @@ export class EvidenceService {
           "anyOf is an explicit case-sensitive literal union; omit pattern, allOf, within, roles, literal and ignoreCase",
         );
       if (input.mode !== undefined && input.mode !== "auto" && input.mode !== "matches")
-        throw new SiftLightError("anyOf mode must be omitted, auto, or matches");
+        throw new SiftLightError("anyOf mode must be omitted, auto, matches or summary");
       const chunks = Array.from(
         { length: Math.ceil(anyOf.length / MAX_ANY_OF_TERMS) },
         (_, index) => anyOf.slice(index * MAX_ANY_OF_TERMS, (index + 1) * MAX_ANY_OF_TERMS),
@@ -696,8 +792,12 @@ export class EvidenceService {
           );
           if (item) result.items.push(item);
         } else if (terms || input.roles) {
-          if (syntaxLanguage(file.document.path)) syntaxCapableFiles += 1;
-          const syntax = await access.syntax(file.document);
+          // Python roles come from a bounded lexical scanner; other languages parse.
+          const pythonRoles = !terms && /\.py$/iu.test(file.document.path);
+          if (pythonRoles || syntaxLanguage(file.document.path)) syntaxCapableFiles += 1;
+          const syntax = pythonRoles
+            ? pythonRoleAnalysis(file.document)
+            : await access.syntax(file.document);
           const classified = terms
             ? findFunctionConjunctions(
                 file.document,
@@ -790,12 +890,16 @@ export class EvidenceService {
       const item = this.#analyses.item(input.cursor, input.matchIndex);
       if (!item.source || !item.range)
         throw new CursorError("This analysis item has no verified source range");
-      const metadataOnly = item.details?.kind === "symbol" || item.details?.kind === "function";
+      // Outline symbols and function conjunctions carry their exact syntax range,
+      // so inspection returns that version-checked range as source (issue #96).
+      const bounded = item.details?.kind === "symbol" || item.details?.kind === "function";
       return {
         path: item.path,
         line: item.line,
         reference: item.source,
-        ...(metadataOnly ? { range: item.range } : { absoluteFocus: item.range.start }),
+        ...(bounded
+          ? { range: item.range, structure: analysisItemStructure(item) }
+          : { absoluteFocus: item.range.start }),
       };
     }
     return {