@wrongstack/tools 1.0.0 → 1.0.2

package/dist/codebase-index/index.js

@@ -1,6 +1,30 @@
 import {
+  ATLAS_DIR,
+  ATLAS_FILE_LIMIT,
+  ATLAS_JSON,
+  ATLAS_MANIFEST,
+  ATLAS_MARKDOWN,
+  ATLAS_SCHEMA,
+  BRIEF_HUB_LIMIT,
+  BRIEF_PACKAGE_LIMIT,
+  BRIEF_SUBSYSTEM_LIMIT,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_CONCURRENCY,
+  EXPORT_FILE_LIMIT,
+  EXPORT_PACKAGE_LIMIT,
+  MAX_CRUX_LINES,
+  MAX_EMBED_CHARS,
+  MAX_REPORTED_DRIFT,
+  MAX_SOURCE_CHARS,
+  MAX_SUMMARY_CHARS,
   PolyglotInvariantEngine,
+  buildAtlas,
+  buildAtlasBrief,
+  buildProjectAtlasBrief,
+  checkAtlasFreshness,
+  checkProjectAtlasFreshness,
   codebaseAstReplaceTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseIndexTool,
@@ -12,13 +36,22 @@ import {
   codebaseStatsTool,
   codebaseTargetedTestTool,
   deadCodeScanTool,
+  embedFiles,
+  embedProjectFiles,
+  enrichConcepts,
+  enrichProjectConcepts,
+  exportProjectAtlasHtml,
   extractDirectorySkeleton,
   extractFileSkeleton,
   generateRepoMap,
   polyglotInvariantEngine,
+  renderAtlasHtml,
   replaceSymbolInFile,
-  runDeadCodeScan
-} from "../chunk-YEISRT4S.js";
+  runDeadCodeScan,
+  setContextQueryEmbedder,
+  writeAtlas,
+  writeProjectAtlas
+} from "../chunk-HWXIRVKH.js";
 import "../chunk-XRNN44QY.js";
 import "../chunk-DRRY6SCM.js";
 import "../chunk-SCMRM6NL.js";
@@ -45,32 +78,58 @@ import {
   shutdownCodebaseIndexHost,
   shutdownCodebaseIndexServer,
   symbolGraphService
-} from "../chunk-ZTCJCYLN.js";
+} from "../chunk-TI5COGLY.js";
 import {
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath
-} from "../chunk-GDDXX27P.js";
+} from "../chunk-MBR5VAB5.js";
 import {
+  CONCEPT_RELATIONS,
+  CONTRADICTED_VISIBILITY_WEIGHT,
   CircuitOpenError,
+  DEFAULT_ITERATIONS,
+  DEFAULT_LIMIT,
+  DEFAULT_RESTART,
+  DEFAULT_SYMBOLS_PER_FILE,
+  FILE_VECTOR_PROVIDER_KEY,
   IndexCircuitBreaker,
   IndexStore,
   IndexTimeoutError,
+  RANK_REFRESH_FILE_THRESHOLD,
+  RANK_VERSION,
+  RANK_VERSION_KEY,
   SCHEMA_VERSION,
+  SEED_LIMIT,
+  UNVERIFIED_VISIBILITY_WEIGHT,
+  aggregateFileRank,
   buildBm25Index,
   buildIndexableText,
+  buildWiringGraph,
+  clearWiringSnapshot,
   codebaseIndexDirOverride,
+  decorateGraphNodes,
+  getWiringSnapshot,
   indexCircuitBreaker,
   internalKindToLspKind,
+  isConceptRelation,
   lspKindToInternalKind,
+  pageRank,
   resetIndexCircuitBreaker,
   resolveIndexDir,
+  retrieveContext,
+  runGraphRankPass,
   runIndexer,
+  shouldRefreshRanks,
+  toSymbolRankRows,
   tokenise
-} from "../chunk-N3K2SFEI.js";
-import "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+} from "../chunk-52UXXQMP.js";
+import "../chunk-DL2ARI4S.js";
+import "../chunk-3AU6CZWL.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import {
+  getCodebaseIndexPerfSnapshot,
+  resetCodebaseIndexPerfMetrics
+} from "../chunk-ZKC5UNGD.js";
 import {
   INDEXABLE_EXTENSIONS,
   detectLang,
@@ -83,18 +142,57 @@ import {
 import "../chunk-KE7A76VC.js";
 import "../chunk-ZUFHAHTE.js";
 export {
+  ATLAS_DIR,
+  ATLAS_FILE_LIMIT,
+  ATLAS_JSON,
+  ATLAS_MANIFEST,
+  ATLAS_MARKDOWN,
+  ATLAS_SCHEMA,
+  BRIEF_HUB_LIMIT,
+  BRIEF_PACKAGE_LIMIT,
+  BRIEF_SUBSYSTEM_LIMIT,
+  CONCEPT_RELATIONS,
+  CONTRADICTED_VISIBILITY_WEIGHT,
   CircuitOpenError,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_CONCURRENCY,
+  DEFAULT_ITERATIONS,
+  DEFAULT_LIMIT,
+  DEFAULT_RESTART,
+  DEFAULT_SYMBOLS_PER_FILE,
+  EXPORT_FILE_LIMIT,
+  EXPORT_PACKAGE_LIMIT,
+  FILE_VECTOR_PROVIDER_KEY,
   INDEXABLE_EXTENSIONS,
   IndexCircuitBreaker,
   IndexStore,
   IndexTimeoutError,
+  MAX_CRUX_LINES,
+  MAX_EMBED_CHARS,
+  MAX_REPORTED_DRIFT,
+  MAX_SOURCE_CHARS,
+  MAX_SUMMARY_CHARS,
   PolyglotInvariantEngine,
+  RANK_REFRESH_FILE_THRESHOLD,
+  RANK_VERSION,
+  RANK_VERSION_KEY,
   SCHEMA_VERSION,
+  SEED_LIMIT,
+  UNVERIFIED_VISIBILITY_WEIGHT,
+  aggregateFileRank,
+  buildAtlas,
+  buildAtlasBrief,
   buildBm25Index,
   buildIndexableText,
+  buildProjectAtlasBrief,
+  buildWiringGraph,
   cancelPendingReindexes,
+  checkAtlasFreshness,
   checkCodebaseIndexServerHealth,
+  checkProjectAtlasFreshness,
+  clearWiringSnapshot,
   codebaseAstReplaceTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseIndexDirOverride,
@@ -109,17 +207,26 @@ export {
   codebaseTargetedTestTool,
   compileGitignore,
   deadCodeScanTool,
+  decorateGraphNodes,
   detectLang,
+  embedFiles,
+  embedProjectFiles,
   enqueueReindex,
+  enrichConcepts,
+  enrichProjectConcepts,
   ensureCodebaseIndexServer,
+  exportProjectAtlasHtml,
   extractDirectorySkeleton,
   extractFileSkeleton,
   fileGraphService,
   generateRepoMap,
+  getCodebaseIndexPerfSnapshot,
   getIndexState,
+  getWiringSnapshot,
   incomingCallsService,
   indexCircuitBreaker,
   internalKindToLspKind,
+  isConceptRelation,
   isIndexReady,
   isIndexableFile,
   isIndexablePath,
@@ -129,20 +236,30 @@ export {
   onIndexStateChange,
   outgoingCallsService,
   packageGraphService,
+  pageRank,
   polyglotInvariantEngine,
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath,
+  renderAtlasHtml,
   replaceSymbolInFile,
+  resetCodebaseIndexPerfMetrics,
   resetIndexCircuitBreaker,
   resolveIndexDir,
   resolveProjectIndexDaemonAvailability,
+  retrieveContext,
   runDeadCodeScan,
+  runGraphRankPass,
   runIndexer,
   runStartupIndex,
   searchCodebaseIndex,
+  setContextQueryEmbedder,
+  shouldRefreshRanks,
   shutdownCodebaseIndexHost,
   shutdownCodebaseIndexServer,
   symbolGraphService,
-  tokenise
+  toSymbolRankRows,
+  tokenise,
+  writeAtlas,
+  writeProjectAtlas
 };
 //# sourceMappingURL=index.js.map

package/dist/codebase-index/parser-worker-script.js

@@ -1,9 +1,9 @@
 import {
   parseFilesContent
-} from "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+} from "../chunk-DL2ARI4S.js";
+import "../chunk-3AU6CZWL.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import "../chunk-ZKC5UNGD.js";
 import "../chunk-YOHO4DVT.js";
 import "../chunk-KE7A76VC.js";
 

package/dist/codebase-index/perf-metrics.d.ts

@@ -0,0 +1,19 @@
+/** Opt-in counters for controlled codebase-index performance measurements. */
+export interface CodebaseIndexPerfSnapshot {
+    filesystemBytesRead: number;
+    filesystemReadCount: number;
+    parserGateWaitMs: number;
+    parserGateCalls: number;
+    parserSubprocessCount: number;
+    ipcPendingPeak: number;
+    writeQueueWaitMs: number;
+    writeQueueCalls: number;
+}
+export declare function resetCodebaseIndexPerfMetrics(): void;
+export declare function getCodebaseIndexPerfSnapshot(): CodebaseIndexPerfSnapshot;
+export declare function recordFilesystemRead(bytes: number): void;
+export declare function recordParserGateWait(waitMs: number): void;
+export declare function recordParserSubprocess(): void;
+export declare function recordIpcPending(depth: number): void;
+export declare function recordWriteQueueWait(waitMs: number): void;
+//# sourceMappingURL=perf-metrics.d.ts.map

package/dist/codebase-index/project-server-protocol.d.ts

@@ -37,6 +37,8 @@ export interface ProjectIndexServerHealth {
     activeRequests: number;
     activeWrites: number;
     queuedWrites: number;
+    maxQueuedWrites?: number;
+    writeQueueWaitMs?: number;
     pendingExternalFiles: number;
     watchingExternal: boolean;
     /** Clients currently requesting ownership of the shared external watcher. */

package/dist/codebase-index/project-server-query-cache.d.ts

@@ -23,9 +23,11 @@
  *   transaction may have rolled back the visible generation) all caches are
  *   cleared.
  */
+import type { ContextResult } from './context-retrieval.js';
 import type { IncomingCallsResult, OutgoingCallsResult } from './index-service.js';
 import { GenerationLruCache } from './project-server-cache.js';
 import type { CodeMapGraph, IndexStats, SearchResult } from './schema.js';
+import type { VectorSearchOpResult } from './worker-protocol.js';
 /** The error the server answers a read it cannot serve with. */
 export declare function indexRefreshInProgressError(currentFile: number, totalFiles: number): Error;
 /**
@@ -76,6 +78,8 @@ export declare class ServerQueryCaches {
         total: number;
     }>;
     readonly statsCache: GenerationLruCache<IndexStats>;
+    readonly contextCache: GenerationLruCache<ContextResult>;
+    readonly vectorSearchCache: GenerationLruCache<VectorSearchOpResult>;
     readonly packageGraphCache: GenerationLruCache<CodeMapGraph>;
     readonly fileGraphCache: GenerationLruCache<CodeMapGraph>;
     readonly symbolGraphCache: GenerationLruCache<CodeMapGraph>;

package/dist/codebase-index/project-server.js

@@ -10,8 +10,9 @@ import {
   projectIndexServerBuildId,
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath
-} from "../chunk-GDDXX27P.js";
+} from "../chunk-MBR5VAB5.js";
 import {
+  contextService,
   fileGraphService,
   incomingCallsService,
   indexService,
@@ -21,12 +22,15 @@ import {
   resolveIndexDir,
   searchService,
   statsService,
-  symbolGraphService
-} from "../chunk-N3K2SFEI.js";
-import "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+  symbolGraphService,
+  vectorSearchService
+} from "../chunk-52UXXQMP.js";
+import "../chunk-DL2ARI4S.js";
+import "../chunk-3AU6CZWL.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import {
+  recordWriteQueueWait
+} from "../chunk-ZKC5UNGD.js";
 import {
   isIndexablePath
 } from "../chunk-YOHO4DVT.js";
@@ -252,6 +256,9 @@ var ServerQueryCaches = class {
    */
   searchCache = new GenerationLruCache(128);
   statsCache = new GenerationLruCache(1);
+  // Retrieval answers are query-shaped like search, so they cache the same way.
+  contextCache = new GenerationLruCache(64);
+  vectorSearchCache = new GenerationLruCache(64);
   packageGraphCache = new GenerationLruCache(1);
   fileGraphCache = new GenerationLruCache(32);
   symbolGraphCache = new GenerationLruCache(64);
@@ -260,6 +267,8 @@ var ServerQueryCaches = class {
   clear() {
     this.searchCache.clear();
     this.statsCache.clear();
+    this.contextCache.clear();
+    this.vectorSearchCache.clear();
     this.packageGraphCache.clear();
     this.fileGraphCache.clear();
     this.symbolGraphCache.clear();
@@ -271,6 +280,8 @@ var ServerQueryCaches = class {
     return {
       searchCache: this.searchCache.size,
       statsCache: this.statsCache.size,
+      contextCache: this.contextCache.size,
+      vectorSearchCache: this.vectorSearchCache.size,
       packageGraphCache: this.packageGraphCache.size,
       fileGraphCache: this.fileGraphCache.size,
       symbolGraphCache: this.symbolGraphCache.size,
@@ -368,6 +379,24 @@ async function dispatchOperation(ctx, state, message) {
       );
       return stale ? { ...value, stale: true } : value;
     }
+    case "context": {
+      const { value, stale } = staleAwareRead(
+        ctx.queryCaches.contextCache,
+        JSON.stringify(message.args),
+        indexActivity2,
+        () => contextService(fixedArgs(ctx, message.args))
+      );
+      return stale ? { ...value, stale: true } : value;
+    }
+    case "vectorSearch": {
+      const { value, stale } = staleAwareRead(
+        ctx.queryCaches.vectorSearchCache,
+        JSON.stringify(message.args),
+        indexActivity2,
+        () => vectorSearchService(fixedArgs(ctx, message.args))
+      );
+      return stale ? { ...value, stale: true } : value;
+    }
     case "stats":
       if (indexActivity2.indexing) {
         throw indexRefreshInProgressError(indexActivity2.currentFile, indexActivity2.totalFiles);
@@ -660,6 +689,8 @@ var writeChain = Promise.resolve();
 var activeRequests = 0;
 var activeWrites = 0;
 var queuedWrites = 0;
+var maxQueuedWrites = 0;
+var writeQueueWaitMs = 0;
 var activeFullIndex = null;
 var queryCaches = new ServerQueryCaches();
 var indexActivity = {
@@ -708,16 +739,30 @@ function send(state, message) {
 }
 function withWriteMutex(job) {
   queuedWrites++;
+  maxQueuedWrites = Math.max(maxQueuedWrites, queuedWrites);
   const guarded = async () => {
     queuedWrites--;
     activeWrites++;
     try {
+      const holdMs = Number(process.env["WRONGSTACK_INDEX_BENCH_WRITE_HOLD_MS"] ?? 0);
+      if (Number.isFinite(holdMs) && holdMs > 0) {
+        await new Promise((resolve3) => setTimeout(resolve3, Math.min(holdMs, 5e3)));
+      }
       return await job();
     } finally {
       activeWrites--;
     }
   };
-  const run = writeChain.then(guarded, guarded);
+  const queuedAt = performance.now();
+  const wrapped = async () => {
+    const elapsedWaitMs = performance.now() - queuedAt;
+    const holdMs = Number(process.env["WRONGSTACK_INDEX_BENCH_WRITE_HOLD_MS"] ?? 0);
+    const waitMs = Number.isFinite(holdMs) && holdMs > 0 ? Math.max(elapsedWaitMs, holdMs) : elapsedWaitMs;
+    writeQueueWaitMs += waitMs;
+    recordWriteQueueWait(waitMs);
+    return guarded();
+  };
+  const run = writeChain.then(wrapped, wrapped);
   writeChain = run.then(
     () => void 0,
     () => void 0
@@ -766,6 +811,8 @@ function serverHealth() {
     activeRequests,
     activeWrites,
     queuedWrites,
+    maxQueuedWrites,
+    writeQueueWaitMs,
     pendingExternalFiles: watcherManager.pendingFileCount,
     watchingExternal: watcherManager.isWatching,
     watchingClients,

package/dist/codebase-index/repo-map-fallback.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Filesystem repo map — the path taken when the index has no ranks yet.
+ *
+ * This is the original heuristic map: walk the tree, score each file by
+ * entry-point name and depth, and pack skeletons until the budget runs out.
+ * It knows nothing about who references whom, so it is strictly a stand-in
+ * for {@link generateRepoMap}'s graph-ranked output on a fresh clone, during
+ * the first index run, or in a directory that was never indexed at all.
+ *
+ * Two defects of the original are fixed here, because a stand-in that lies is
+ * worse than no stand-in: it no longer stops after ~500 files (this repo has
+ * 8,412, so the old cap meant the "map" described whichever directories the
+ * walk happened to reach first), and it honours `.gitignore` instead of a
+ * hardcoded list of four directory names.
+ */
+import type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+export declare function generateFallbackRepoMap(opts: RepoMapOptions): Promise<RepoMapResult>;
+//# sourceMappingURL=repo-map-fallback.d.ts.map

package/dist/codebase-index/repo-map-render.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Rendering half of the repo map: turning a ranked candidate list into
+ * budgeted skeleton sections. Shared by the graph-ranked generator and the
+ * filesystem fallback so the two produce the same section format.
+ */
+import { type SkeletonOptions } from './skeleton-extractor.js';
+export interface RepoMapCandidate {
+    /** Absolute path, for reading. */
+    absolute: string;
+    /** Project-relative POSIX path, for display. */
+    relative: string;
+}
+export interface RenderSectionsOptions {
+    skeleton?: SkeletonOptions | undefined;
+    /**
+     * Largest a single file's section may be. Without it one 9k-token type
+     * module consumes the entire budget and the "map" describes one file. The
+     * point of a map is breadth, so each file gets a slice and the rest of the
+     * budget goes to the next-most-central file.
+     */
+    maxSectionChars?: number | undefined;
+    /**
+     * Drop comment-only lines so the budget buys declarations, not prose.
+     * On for the map body; off for callers that want the skeleton verbatim.
+     */
+    signaturesOnly?: boolean | undefined;
+}
+export interface RenderedSections {
+    sections: string[];
+    /** Relative paths actually included, in order. */
+    files: string[];
+    /** Characters consumed by `sections`, including the blank-line separators. */
+    chars: number;
+}
+/**
+ * Extract skeletons for `candidates` in order until `charBudget` is exhausted.
+ *
+ * Unreadable and empty files are skipped rather than ending the walk, so one
+ * deleted-since-index path cannot truncate the whole map.
+ */
+export declare function renderSkeletonSections(candidates: readonly RepoMapCandidate[], charBudget: number, options?: RenderSectionsOptions): Promise<RenderedSections>;
+//# sourceMappingURL=repo-map-render.d.ts.map

package/dist/codebase-index/repo-map-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared shapes for the repo map. Split out so the graph-ranked generator and
+ * the filesystem fallback can import them without importing each other.
+ */
+import type { SkeletonOptions } from './skeleton-extractor.js';
+export interface RepoMapOptions {
+    projectRoot: string;
+    maxTokens?: number | undefined;
+    focusFiles?: string[] | undefined;
+    options?: SkeletonOptions | undefined;
+    /** Index directory override, for callers that do not use the default path. */
+    indexDir?: string | undefined;
+}
+export interface RepoMapResult {
+    map: string;
+    filesCount: number;
+    totalFilesScanned: number;
+    estimatedTokens: number;
+    rankedFiles: string[];
+}
+//# sourceMappingURL=repo-map-types.d.ts.map

package/dist/codebase-index/repo-map.d.ts

@@ -1,20 +1,32 @@
-import { type SkeletonOptions } from './skeleton-extractor.js';
-export interface RepoMapOptions {
-    projectRoot: string;
-    maxTokens?: number | undefined;
-    focusFiles?: string[] | undefined;
-    options?: SkeletonOptions | undefined;
-}
-export interface RepoMapResult {
-    map: string;
-    filesCount: number;
-    totalFilesScanned: number;
-    estimatedTokens: number;
-    rankedFiles: string[];
-}
 /**
- * Generate a reference-weighted, token-budgeted Repository Map.
- * Packs the most architecturally central symbols across the codebase into ~800-1500 tokens.
+ * Repository map — a token-budgeted orientation view of the codebase.
+ *
+ * The map is built from the index's graph centrality (`file_rank`), not from a
+ * filesystem walk. Two things follow from that:
+ *
+ *  - **It ranks by evidence.** The previous implementation never opened the
+ *    index at all: it walked the tree and scored files by whether their name
+ *    matched `index|main|app|server|…` plus a directory-depth bonus, stopping
+ *    after ~500 files. On a repo of 8,412 that produced a map of whichever
+ *    directories the walk reached first, ranked by filename. Centrality
+ *    instead answers the question the map is actually asked — what does the
+ *    rest of this codebase depend on?
+ *  - **It can group.** `files.package` gives every file an ecosystem-derived
+ *    cluster label, so the map opens with the shape of the repo (clusters and
+ *    their hubs, then global hotspots) before descending into signatures.
+ *
+ * When the index has no ranks — a fresh clone, the first index run, a
+ * directory that was never indexed — {@link generateFallbackRepoMap} takes
+ * over and the output degrades to the old heuristic rather than to nothing.
+ */
+import type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+export { generateFallbackRepoMap } from './repo-map-fallback.js';
+export type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+/**
+ * Generate a graph-ranked, token-budgeted repository map.
+ *
+ * Falls back to the filesystem heuristic whenever the index cannot answer —
+ * no ranks yet, or the store could not be opened at all.
  */
 export declare function generateRepoMap(opts: RepoMapOptions): Promise<RepoMapResult>;
 //# sourceMappingURL=repo-map.d.ts.map

package/dist/codebase-index/schema.d.ts

@@ -194,6 +194,26 @@ export interface GraphNode {
     scope?: string | undefined;
     /** True when this is a direct relation outside the current drill-down scope. */
     external?: boolean | undefined;
+    /**
+     * Global PageRank centrality, max-normalised to 1.0 across the whole index —
+     * so it is comparable between nodes of the same kind, not across kinds.
+     * Package nodes carry the sum of their files' ranks.
+     */
+    rank?: number | undefined;
+    /** Plain-language description of the node, from the concept layer. */
+    concept?: string | undefined;
+    /**
+     * The load-bearing source span the summary was drawn from, 1-based and
+     * inclusive. A summary can drift from the code; this cannot.
+     */
+    crux?: {
+        start: number;
+        end: number;
+    } | undefined;
+    /** Name of the subsystem this node's file belongs to, when one was derived. */
+    subsystem?: string | undefined;
+    /** `files.mtime_ms` — last modification, for recency shading. */
+    lastModifiedMs?: number | undefined;
 }
 /** A directed edge: source references / depends-on target. */
 export interface GraphEdge {

package/dist/codebase-index/worker-protocol.d.ts

@@ -4,8 +4,10 @@
  * Plain structured-cloneable shapes only — no class instances, no functions.
  * Errors cross the boundary as strings and are re-wrapped by the host.
  */
-import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
+import type { ContextResult } from './context-retrieval.js';
 import type { CodeMapGraph, IndexResult, IndexStats, SearchResult } from './schema.js';
+import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
+import type { VectorHit } from './writer-vectors.js';
 export interface IndexOpArgs {
     projectRoot: string;
     indexDir?: string | undefined;
@@ -61,6 +63,42 @@ export interface SearchOpResult {
      */
     stale?: boolean | undefined;
 }
+/**
+ * Personalised retrieval arguments.
+ *
+ * `vectorFiles` arrives already scored because the embedding model lives on
+ * the host: a function cannot cross this boundary, so the host embeds the
+ * query and only the resulting file scores travel as numbers.
+ */
+export interface ContextOpArgs extends StatsOpArgs {
+    query: string;
+    vectorFiles?: ReadonlyArray<{
+        file: string;
+        score: number;
+    }> | undefined;
+    limit?: number | undefined;
+    symbolsPerFile?: number | undefined;
+    pathPrefix?: string | undefined;
+}
+/**
+ * Nearest-vector search arguments.
+ *
+ * The vector is a plain number array rather than a `Float32Array` because
+ * only structured-cloneable plain shapes cross this protocol; the service
+ * re-wraps it before comparing.
+ */
+export interface VectorSearchOpArgs extends StatsOpArgs {
+    vector: number[];
+    limit: number;
+    minScore?: number | undefined;
+}
+export interface VectorSearchOpResult {
+    hits: VectorHit[];
+    /** Vectors currently stored — zero means the embedding pass has not run. */
+    total: number;
+    /** Set when the project server served a previous generation's cached answer. */
+    stale?: boolean | undefined;
+}
 /** Map of op name → { args, result } so host and worker stay in lockstep. */
 export interface OpShapes {
     index: {
@@ -95,6 +133,14 @@ export interface OpShapes {
         args: CallRefsOpArgs;
         result: OutgoingCallsResult;
     };
+    context: {
+        args: ContextOpArgs;
+        result: ContextResult;
+    };
+    vectorSearch: {
+        args: VectorSearchOpArgs;
+        result: VectorSearchOpResult;
+    };
 }
 export type OpName = keyof OpShapes;
 export type HostToWorker = {