sift-light 1.0.0

package/src/analysis-store.ts

@@ -0,0 +1,559 @@
+import { randomUUID } from "node:crypto";
+import {
+  ANALYSIS_TTL_MS,
+  ANALYSIS_METADATA_RESERVE_BYTES,
+  MAX_ANALYSIS_REASON_BYTES,
+  MAX_ANALYSIS_REASONS,
+  MAX_ANALYSIS_RESULTS,
+  MAX_ANALYSIS_SNAPSHOTS,
+  MAX_ANALYSIS_STORAGE_BYTES,
+} from "./analysis-limits.js";
+import {
+  SEMANTIC_JUDGE_CLASSIFICATIONS,
+  SEMANTIC_JUDGE_NON_PROOF_CLAIM,
+  type AnalysisItem,
+  type AnalysisResultSet,
+} from "./analysis-types.js";
+import { CursorError, SiftLightError } from "./errors.js";
+import type { SiftLightResult } from "./types.js";
+import { MAX_RESULT_BYTES } from "./types.js";
+import { modificationTimeBoundsText } from "./source.js";
+import {
+  analysisTermPage,
+  MAX_INLINE_TERM_COUNT_BYTES,
+  termCountRequest,
+} from "./analysis-term-pages.js";
+
+import { analysisExtraGroups, statisticsForItems } from "./result-statistics.js";
+interface StoredAnalysis {
+  id: string;
+  result: AnalysisResultSet;
+  bytes: number;
+  touched: number;
+}
+
+export type RetainedAnalysisSummary = (
+  items: readonly AnalysisItem[],
+) => Pick<AnalysisResultSet, "counts" | "termCounts">;
+
+function boundedReasons(reasons: readonly string[]): string[] {
+  const unsupportedSuffix = ": syntax unsupported; this source remains unclassified";
+  const unsupported = reasons
+    .filter((reason) => reason.endsWith(unsupportedSuffix))
+    .map((reason) => reason.slice(0, -unsupportedSuffix.length));
+  const unique = [
+    ...new Set(reasons.filter((reason) => !reason.endsWith(unsupportedSuffix))),
+    ...(unsupported.length
+      ? [
+          `${String(unsupported.length)} matching file(s) skipped because syntax is unsupported${unsupported.length ? `; examples: ${unsupported.slice(0, 3).join(", ")}` : ""}`,
+        ]
+      : []),
+  ];
+  const retained: string[] = [];
+  let bytes = 2;
+  let omitted = 0;
+  for (const reason of unique) {
+    const reasonBytes = Buffer.byteLength(JSON.stringify(reason)) + 1;
+    if (
+      retained.length >= MAX_ANALYSIS_REASONS ||
+      bytes + reasonBytes > MAX_ANALYSIS_REASON_BYTES
+    ) {
+      omitted += 1;
+      continue;
+    }
+    retained.push(reason);
+    bytes += reasonBytes;
+  }
+  if (omitted === 0) return retained;
+  let notice = `${String(omitted)} additional analysis reasons omitted within the ${String(MAX_ANALYSIS_REASONS)}-reason / ${String(MAX_ANALYSIS_REASON_BYTES)}-byte diagnostic limit`;
+  while (
+    retained.length > 0 &&
+    bytes + Buffer.byteLength(JSON.stringify(notice)) + 1 > MAX_ANALYSIS_REASON_BYTES
+  ) {
+    const removed = retained.pop();
+    if (removed === undefined) break;
+    bytes -= Buffer.byteLength(JSON.stringify(removed)) + 1;
+    omitted += 1;
+    notice = `${String(omitted)} additional analysis reasons omitted within the ${String(MAX_ANALYSIS_REASONS)}-reason / ${String(MAX_ANALYSIS_REASON_BYTES)}-byte diagnostic limit`;
+  }
+  retained.push(notice);
+  return retained;
+}
+
+function publicAnalysisLabel(result: AnalysisResultSet): string {
+  switch (result.kind) {
+    case "files":
+      return "file metadata";
+    case "outline":
+      return "symbol metadata";
+    case "imports":
+      return "import relationship metadata";
+    case "tests":
+      return "test candidate metadata";
+    case "structure":
+      return "structure match metadata";
+    case "roles":
+      return "role match metadata";
+    case "function-and":
+      return "function match metadata";
+    case "file-and":
+      return "file match metadata";
+    case "changes":
+      return "change metadata";
+    case "concept":
+      return "semantic candidate metadata";
+    case "hybrid":
+      return "combined evidence metadata";
+    case "any-of":
+      return "condition match metadata";
+    case "validate":
+      return "validation metadata";
+  }
+  throw new Error("Unknown analysis result kind");
+}
+
+function publicStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) return undefined;
+  return value;
+}
+
+function publicStructureDetails(item: AnalysisItem): Record<string, unknown> | undefined {
+  if (item.details?.kind !== "symbol") return undefined;
+  const details = item.details;
+  const scope = publicStringArray(details.scope);
+  return {
+    kind: "symbol",
+    ...(typeof details.language === "string" ? { language: details.language } : {}),
+    ...(typeof details.name === "string" ? { name: details.name } : {}),
+    ...(scope ? { scope } : {}),
+    ...(typeof details.hasBody === "boolean" ? { hasBody: details.hasBody } : {}),
+    ...(typeof details.exported === "boolean" ? { exported: details.exported } : {}),
+    ...(typeof details.syntax === "string" ? { syntax: details.syntax } : {}),
+    ...(typeof details.signatureTruncated === "boolean"
+      ? { signatureTruncated: details.signatureTruncated }
+      : {}),
+  };
+}
+
+function publicSemanticJudgeDetails(item: AnalysisItem): Record<string, unknown> | undefined {
+  const value = item.details?.semanticJudge;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const classification = Reflect.get(value, "classification");
+  const probability = Reflect.get(value, "probability");
+  const confidence = Reflect.get(value, "confidence");
+  const model = Reflect.get(value, "model");
+  const claim = Reflect.get(value, "claim");
+  if (
+    typeof classification !== "string" ||
+    !SEMANTIC_JUDGE_CLASSIFICATIONS.some((candidate) => candidate === classification) ||
+    typeof probability !== "number" ||
+    !Number.isFinite(probability) ||
+    probability < 0 ||
+    probability > 1 ||
+    (confidence !== undefined &&
+      (typeof confidence !== "number" ||
+        !Number.isFinite(confidence) ||
+        confidence < 0 ||
+        confidence > 1)) ||
+    typeof model !== "string" ||
+    model.length === 0 ||
+    model.length > 128 ||
+    /[\r\n\0]/u.test(model) ||
+    claim !== SEMANTIC_JUDGE_NON_PROOF_CLAIM
+  )
+    return undefined;
+  return {
+    classification,
+    probability,
+    ...(confidence === undefined ? {} : { confidence }),
+    model,
+    claim,
+  };
+}
+
+function publicItemDetails(item: AnalysisItem): Record<string, unknown> | undefined {
+  const structure = publicStructureDetails(item);
+  const semanticJudge = publicSemanticJudgeDetails(item);
+  const source =
+    item.details?.source === "literal" || item.details?.source === "concept"
+      ? item.details.source
+      : undefined;
+  if (!structure && !semanticJudge && !source) return undefined;
+  return {
+    ...structure,
+    ...(source ? { source } : {}),
+    ...(semanticJudge ? { semanticJudge } : {}),
+  };
+}
+
+function publicAnalysisItem(
+  result: AnalysisResultSet,
+  item: AnalysisItem,
+  index: number,
+  storedId: string,
+  modelOutput: boolean,
+): NonNullable<SiftLightResult["details"]["analysis"]>["items"][number] {
+  const inspect =
+    item.source && item.range
+      ? {
+          mode: "inspect" as const,
+          cursor: `${storedId}.analysis.0`,
+          matchIndex: index + 1,
+          ...(result.redact ? { redact: true } : {}),
+        }
+      : undefined;
+  const publicDetails = publicItemDetails(item);
+  return {
+    path: item.path,
+    line: item.line,
+    label: result.kind === "outline" && modelOutput ? item.label : publicAnalysisLabel(result),
+    index: index + 1,
+    ...(inspect ? { inspect } : {}),
+    ...(publicDetails ? { details: publicDetails } : {}),
+  };
+}
+
+function safeTermCounts(
+  termCounts: readonly { retainedOccurrences: number }[] | undefined,
+): { term: string; retainedOccurrences: number }[] | undefined {
+  return termCounts?.map((entry, index) => ({
+    term: `condition #${String(index + 1)}`,
+    retainedOccurrences: entry.retainedOccurrences,
+  }));
+}
+
+function hybridPreviewIndices(items: readonly AnalysisItem[]): number[] {
+  const literal: number[] = [];
+  const concept: number[] = [];
+  for (const [index, item] of items.entries()) {
+    if (item.details?.source === "literal" && literal.length < 3) literal.push(index);
+    if (item.details?.source === "concept") concept.push(index);
+  }
+  return [...literal, ...concept];
+}
+
+/** Stores only bounded display evidence and version references, never syntax trees. */
+export class AnalysisStore {
+  readonly #items = new Map<string, StoredAnalysis>();
+  readonly #expired = new Set<string>();
+  readonly #now: () => number;
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+  clear(): void {
+    for (const id of this.#items.keys()) this.#rememberExpired(id);
+    this.#items.clear();
+  }
+
+  create(result: AnalysisResultSet, summarize?: RetainedAnalysisSummary): string {
+    this.#expire();
+    const bounded: AnalysisResultSet = {
+      ...result,
+      reasons: boundedReasons(result.reasons),
+      items: [],
+      coverage: {
+        ...result.coverage,
+        retention: result.coverage?.retention ?? "complete",
+      },
+    };
+    let bytes = Buffer.byteLength(JSON.stringify(bounded));
+    const candidates = result.items.map((item, index) => ({ item, index }));
+    const retainedIndices: number[] = [];
+    const rebuildItems = (): void => {
+      const retained = new Set(retainedIndices);
+      bounded.items = result.items
+        .filter((_item, index) => retained.has(index))
+        .map((item) => structuredClone(item));
+    };
+    for (const candidate of candidates) {
+      const { item } = candidate;
+      const itemBytes = Buffer.byteLength(JSON.stringify(item)) + 1;
+      if (
+        retainedIndices.length >= MAX_ANALYSIS_RESULTS ||
+        bytes + itemBytes > MAX_ANALYSIS_STORAGE_BYTES - ANALYSIS_METADATA_RESERVE_BYTES
+      ) {
+        bounded.partial = true;
+        if (bounded.coverage) bounded.coverage.retention = "partial";
+        bounded.reasons.push("Analysis storage limit: 50,000 items / 32 MiB; narrow the query");
+        break;
+      }
+      retainedIndices.push(candidate.index);
+      bytes += itemBytes;
+    }
+    rebuildItems();
+    if (summarize) Object.assign(bounded, summarize(bounded.items));
+    bytes = Buffer.byteLength(JSON.stringify(bounded));
+    while (bytes > MAX_ANALYSIS_STORAGE_BYTES - 1024 && bounded.items.length > 0) {
+      retainedIndices.pop();
+      rebuildItems();
+      bounded.partial = true;
+      if (bounded.coverage) bounded.coverage.retention = "partial";
+      if (
+        !bounded.reasons.includes("Analysis storage limit: 50,000 items / 32 MiB; narrow the query")
+      )
+        bounded.reasons.push("Analysis storage limit: 50,000 items / 32 MiB; narrow the query");
+      if (summarize) Object.assign(bounded, summarize(bounded.items));
+      bytes = Buffer.byteLength(JSON.stringify(bounded));
+    }
+    bounded.reasons = boundedReasons(bounded.reasons);
+    bytes = Buffer.byteLength(JSON.stringify(bounded));
+    if (bytes > MAX_ANALYSIS_STORAGE_BYTES - 1024)
+      throw new SiftLightError("Analysis metadata exceeds the storage budget");
+    while (
+      this.#items.size >= MAX_ANALYSIS_SNAPSHOTS ||
+      this.#totalBytes() + bytes > MAX_ANALYSIS_STORAGE_BYTES ||
+      this.#totalItems() + bounded.items.length > MAX_ANALYSIS_RESULTS
+    ) {
+      const oldest = [...this.#items.values()].toSorted((a, b) => a.touched - b.touched)[0];
+      if (!oldest) throw new SiftLightError("Analysis metadata exceeds the storage budget");
+      this.#items.delete(oldest.id);
+      this.#rememberExpired(oldest.id);
+    }
+    const id = randomUUID();
+    this.#items.set(id, { id, result: bounded, bytes, touched: this.#now() });
+    return `${id}.${result.kind === "hybrid" ? "analysis-hybrid" : "analysis"}.0`;
+  }
+
+  resolve(cursor: string): {
+    stored: StoredAnalysis;
+    offset: number;
+    kind: "analysis" | "analysis-hybrid" | "analysis-terms";
+  } {
+    this.#expire();
+    const match = /^([a-f0-9-]+)\.(analysis|analysis-hybrid|analysis-terms)\.([0-9a-z]+)$/.exec(
+      cursor,
+    );
+    if (!match) throw new CursorError("Invalid analysis cursor");
+    const id = match[1];
+    const kind = match[2];
+    const rawOffset = match[3];
+    if (kind !== "analysis" && kind !== "analysis-hybrid" && kind !== "analysis-terms")
+      throw new CursorError("Invalid analysis cursor");
+    if (!id || !rawOffset) throw new CursorError("Invalid analysis cursor");
+    const offset = Number.parseInt(rawOffset, 36);
+    const stored = this.#items.get(id);
+    if (!stored)
+      throw new CursorError(
+        this.#expired.has(id)
+          ? "Analysis cursor expired or was evicted; run the query again"
+          : "Analysis cursor was not found; run the query again",
+        this.#expired.has(id) ? "E_CURSOR_EXPIRED" : "E_CURSOR_NOT_FOUND",
+      );
+    if (
+      !Number.isSafeInteger(offset) ||
+      offset < 0 ||
+      offset.toString(36) !== rawOffset ||
+      (kind === "analysis"
+        ? offset > stored.result.items.length
+        : kind === "analysis-hybrid"
+          ? offset !== 0 || stored.result.kind !== "hybrid"
+          : offset >= (stored.result.termCounts?.length ?? 0))
+    )
+      throw new CursorError("Invalid analysis offset", "E_CURSOR_OFFSET_INVALID");
+    stored.touched = this.#now();
+    return { stored, offset, kind };
+  }
+
+  item(cursor: string, index: number): AnalysisItem {
+    const { stored, kind } = this.resolve(cursor);
+    if (kind !== "analysis")
+      throw new CursorError("Term inventories do not contain source items", "E_CURSOR_WRONG_KIND");
+    if (!Number.isSafeInteger(index) || index < 1)
+      throw new CursorError("matchIndex must be a positive analysis item index");
+    const item = stored.result.items[index - 1];
+    if (!item) throw new CursorError("Analysis item is outside the retained result");
+    return structuredClone(item);
+  }
+
+  page(cursor: string, modelOutput = false): SiftLightResult {
+    const { stored, offset, kind } = this.resolve(cursor);
+    const { result } = stored;
+    if (kind === "analysis-terms") return analysisTermPage(result, stored.id, offset);
+    const hybridPreview = kind === "analysis-hybrid";
+    const hybridMatchesRequest = hybridPreview
+      ? { cursor: `${stored.id}.analysis.0`, ...(result.redact ? { redact: true } : {}) }
+      : undefined;
+    const pagedTerms =
+      result.termCounts &&
+      Buffer.byteLength(JSON.stringify(result.termCounts)) > MAX_INLINE_TERM_COUNT_BYTES;
+    const inlineTerms = pagedTerms ? undefined : safeTermCounts(result.termCounts);
+    const termsRequest = pagedTerms ? termCountRequest(stored.id, 0, result.redact) : undefined;
+    const items: NonNullable<SiftLightResult["details"]["analysis"]>["items"] = [];
+    const sources: NonNullable<SiftLightResult["details"]["analysis"]>["sources"] = [];
+    const sourceIds = new Map<string, number>();
+    const hybridInspectCursor = result.kind === "hybrid" ? `${stored.id}.analysis.0` : undefined;
+    const statistics = statisticsForItems(
+      result.items,
+      result.items.length,
+      result.unit,
+      analysisExtraGroups(result.counts, result.termCounts, result.items),
+    );
+    const scope = result.scope
+      ? ` Scope: ${result.scope.assertion === "project-wide" ? "project root" : "requested path"} ${JSON.stringify(result.scope.path)}${result.scope.expandedToProjectRoot ? `, expanded after ${JSON.stringify(result.scope.requestedPath)} had no matches` : ""}.${modificationTimeBoundsText(result.scope.modifiedAfterMs, result.scope.modifiedBeforeMs)}`
+      : "";
+    const coverage = result.coverage ? ` Coverage: ${JSON.stringify(result.coverage)}.` : "";
+    const stats = result.stats ? ` Stats: ${JSON.stringify(result.stats)}.` : "";
+    const semanticJudge = result.semanticJudge
+      ? ` Semantic judge: ${result.semanticJudge.status}; provider=${result.semanticJudge.provider}; judged ${String(result.semanticJudge.judgedCandidates)} of ${String(result.semanticJudge.candidatesConsidered)} candidates.`
+      : "";
+    const hasItemDetails = result.items.some((item) => publicItemDetails(item) !== undefined);
+    const header = `${result.kind}: ${result.items.length} retained ${result.unit} (${result.partial ? "PARTIAL" : "complete"}). ${publicAnalysisLabel(result)}. ${result.counts ? `Counts: ${JSON.stringify(result.counts)}. ` : ""}${inlineTerms ? `Term counts: ${JSON.stringify(inlineTerms)}. ` : ""}${termsRequest ? `Term counts are paginated: ${JSON.stringify(termsRequest)}. ` : ""}Counts use ${result.unit}; they are not ordinary matching-line counts.${hasItemDetails ? " Structured output retains per-item evidence details." : ""}${semanticJudge}${scope}${coverage}${stats}`;
+    const notice = result.reasons.length
+      ? `\n${result.reasons.map((reason) => `[${reason}]`).join("\n")}`
+      : "";
+    const rows: string[] = [];
+    let bytes = Buffer.byteLength(header + notice) + 1200;
+    let next = offset;
+    const appendItem = (index: number): boolean => {
+      const item = result.items[index];
+      if (!item) throw new Error("Analysis item unavailable");
+      const publicItem = publicAnalysisItem(result, item, index, stored.id, modelOutput);
+      const inspect = publicItem.inspect;
+      const exposeExcerpt =
+        result.kind === "concept" ||
+        (result.kind === "hybrid" && item.details?.source === "concept");
+      const row = `#${index + 1} ${item.path}:${item.line} ${publicItem.label}${exposeExcerpt && item.excerpt ? `\n${item.excerpt}` : ""}${inspect && !hybridInspectCursor ? `\nInspect: ${JSON.stringify(inspect)}` : ""}`;
+      const rowBytes = Buffer.byteLength(row) + 2;
+      if (bytes + rowBytes > MAX_RESULT_BYTES) {
+        if (items.length === 0)
+          throw new SiftLightError("Analysis item exceeds the response limit; narrow its source");
+        return false;
+      }
+      rows.push(row);
+      bytes += rowBytes;
+      if (hybridInspectCursor) {
+        const { inspect: _inspect, ...sharedPublicItem } = publicItem;
+        const publicHybridItem = {
+          ...sharedPublicItem,
+          ...(item.excerpt ? { excerpt: item.excerpt } : {}),
+        };
+        if (item.source) {
+          const sourceKey = JSON.stringify(item.source);
+          let sourceId = sourceIds.get(sourceKey);
+          if (sourceId === undefined) {
+            sourceId = sources.length;
+            sources.push(item.source);
+            sourceIds.set(sourceKey, sourceId);
+          }
+          items.push({ ...publicHybridItem, sourceId });
+        } else {
+          items.push(publicHybridItem);
+        }
+      } else {
+        items.push({
+          ...item,
+          label: publicItem.label,
+          index: index + 1,
+          ...(inspect ? { inspect } : {}),
+        });
+      }
+      if (!hybridPreview) next = index + 1;
+      return true;
+    };
+    if (hybridPreview) {
+      for (const index of hybridPreviewIndices(result.items)) {
+        if (items.length >= 30 || !appendItem(index)) break;
+      }
+    } else {
+      for (let index = offset; index < result.items.length && items.length < 30; index += 1) {
+        if (!appendItem(index)) break;
+      }
+    }
+    const nextRequest =
+      hybridMatchesRequest ??
+      (next < result.items.length
+        ? {
+            cursor: `${stored.id}.analysis.${next.toString(36)}`,
+            ...(result.redact ? { redact: true } : {}),
+          }
+        : undefined);
+    const text = [
+      header + notice,
+      ...rows,
+      ...(hybridInspectCursor
+        ? [
+            `Inspect item #N: ${JSON.stringify({ mode: "inspect", cursor: hybridInspectCursor, matchIndex: "N" })}`,
+          ]
+        : []),
+      ...(nextRequest ? [`Next request: ${JSON.stringify(nextRequest)}`] : []),
+    ].join("\n\n");
+    if (Buffer.byteLength(text) > MAX_RESULT_BYTES)
+      throw new SiftLightError("Analysis metadata exceeds the output limit");
+    return {
+      text,
+      details: {
+        version: 1,
+        mode:
+          result.kind === "concept" ||
+          result.kind === "hybrid" ||
+          result.kind === "structure" ||
+          result.kind === "files" ||
+          result.kind === "outline" ||
+          result.kind === "imports" ||
+          result.kind === "tests"
+            ? result.kind
+            : "matches",
+        status: result.partial ? "partial" : "complete",
+        snapshotComplete: !result.partial,
+        totalMatches: result.items.length,
+        storedMatches: result.items.length,
+        returnedMatches: items.length,
+        totalFiles: statistics.files,
+        statistics,
+        cursor: nextRequest?.cursor ?? `${stored.id}.analysis.0`,
+        ...(nextRequest ? { nextRequest } : {}),
+        analysis: {
+          kind: result.kind,
+          unit: result.unit,
+          totalItems: result.items.length,
+          returnedItems: items.length,
+          ...(modelOutput ? { modelOutput: true } : {}),
+          statistics,
+          items,
+          ...(sources.length ? { sources } : {}),
+          reasons: result.reasons,
+          ...(result.semanticJudge ? { semanticJudge: result.semanticJudge } : {}),
+          ...(result.filesRead !== undefined ? { filesRead: result.filesRead } : {}),
+          ...(result.bytesRead !== undefined ? { bytesRead: result.bytesRead } : {}),
+          ...(result.changes ? { changes: result.changes } : {}),
+          ...(result.counts ? { counts: result.counts } : {}),
+          ...(inlineTerms ? { termCounts: inlineTerms } : {}),
+          ...(termsRequest
+            ? { totalTerms: result.termCounts?.length ?? 0, termCountsNextRequest: termsRequest }
+            : {}),
+          ...(result.scope ? { scope: result.scope } : {}),
+          ...(result.chunks !== undefined ? { chunks: result.chunks } : {}),
+          ...(result.coverage ? { coverage: result.coverage } : {}),
+          ...(result.stats ? { stats: result.stats } : {}),
+          ...(result.sourceGeneration ? { sourceGeneration: result.sourceGeneration } : {}),
+          ...(hybridMatchesRequest ? { matchesRequest: hybridMatchesRequest } : {}),
+          ...(hybridInspectCursor ? { inspectCursor: hybridInspectCursor } : {}),
+        },
+        ...(result.scope ? { scope: result.scope } : {}),
+        ...(result.redact ? { redactionRequested: true } : {}),
+      },
+    };
+  }
+
+  #expire(): void {
+    for (const [id, item] of this.#items)
+      if (this.#now() - item.touched >= ANALYSIS_TTL_MS) {
+        this.#items.delete(id);
+        this.#rememberExpired(id);
+      }
+  }
+  #totalBytes(): number {
+    return [...this.#items.values()].reduce((n, item) => n + item.bytes, 0);
+  }
+  #totalItems(): number {
+    return [...this.#items.values()].reduce((n, item) => n + item.result.items.length, 0);
+  }
+  #rememberExpired(id: string): void {
+    this.#expired.add(id);
+    while (this.#expired.size > MAX_ANALYSIS_SNAPSHOTS * 4) {
+      const oldest = this.#expired.values().next().value;
+      if (oldest === undefined) break;
+      this.#expired.delete(oldest);
+    }
+  }
+}

package/src/analysis-term-pages.ts

@@ -0,0 +1,73 @@
+import type { AnalysisResultSet } from "./analysis-types.js";
+import type { SiftLightResult } from "./types.js";
+
+export const MAX_INLINE_TERM_COUNT_BYTES = 8 * 1024;
+
+export function termCountRequest(id: string, offset: number, redact = false) {
+  return {
+    cursor: `${id}.analysis-terms.${offset.toString(36)}`,
+    ...(redact ? { redact: true } : {}),
+  };
+}
+
+/** Term metadata has its own pages so even a complete empty result remains readable. */
+export function analysisTermPage(
+  result: AnalysisResultSet,
+  id: string,
+  offset: number,
+): SiftLightResult {
+  const all = result.termCounts ?? [];
+  const terms: { term: string; retainedOccurrences: number }[] = [];
+  const rows: string[] = [];
+  let bytes = 0;
+  for (let index = offset; index < all.length; index++) {
+    const term = all[index];
+    if (!term) throw new Error("Term inventory index unavailable");
+    const label = `condition #${String(index + 1)}`;
+    const row = `${label}: ${String(term.retainedOccurrences)} retained occurrences`;
+    const size = Buffer.byteLength(row) + 2;
+    if (bytes + size > MAX_INLINE_TERM_COUNT_BYTES) break;
+    rows.push(row);
+    terms.push({ term: label, retainedOccurrences: term.retainedOccurrences });
+    bytes += size;
+  }
+  const nextOffset = offset + terms.length;
+  const nextRequest =
+    nextOffset < all.length ? termCountRequest(id, nextOffset, result.redact) : undefined;
+  const matchesRequest = { cursor: `${id}.analysis.0`, ...(result.redact ? { redact: true } : {}) };
+  return {
+    text: [
+      `Condition inventory ${String(offset + 1)}-${String(nextOffset)} of ${String(all.length)} (${result.partial ? "PARTIAL evidence" : "complete evidence"}). Counts refer to retained occurrences.`,
+      ...rows,
+      ...(nextRequest ? [`Next request: ${JSON.stringify(nextRequest)}`] : []),
+      `Match metadata request: ${JSON.stringify(matchesRequest)}`,
+    ].join("\n\n"),
+    details: {
+      version: 1,
+      mode: "matches",
+      status: result.partial ? "partial" : "complete",
+      snapshotComplete: !result.partial,
+      totalMatches: result.items.length,
+      storedMatches: result.items.length,
+      returnedMatches: 0,
+      totalFiles: new Set(result.items.map((item) => item.path)).size,
+      cursor: nextRequest?.cursor ?? matchesRequest.cursor,
+      ...(nextRequest ? { nextRequest } : {}),
+      ...(result.redact ? { redactionRequested: true } : {}),
+      analysis: {
+        kind: result.kind,
+        unit: result.unit,
+        totalItems: result.items.length,
+        returnedItems: 0,
+        items: [],
+        reasons: result.reasons,
+        termCounts: terms,
+        termCountsOffset: offset,
+        totalTerms: all.length,
+        ...(nextRequest ? { termCountsNextRequest: nextRequest } : {}),
+        matchesRequest,
+        ...(result.coverage ? { coverage: result.coverage } : {}),
+      },
+    },
+  };
+}