@wrongstack/tools 1.0.1 → 1.0.2

package/dist/{chunk-GKSG5CPH.js → chunk-KVTEIUND.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-MSOAX3GC.js";
 import {
   enqueueReindex
-} from "./chunk-ZTCJCYLN.js";
+} from "./chunk-TI5COGLY.js";
 import {
   safeResolveReal,
   sha256hex,
@@ -179,4 +179,4 @@ async function finishWrite(input, ctx, prepared, signal) {
 export {
   writeTool
 };
-//# sourceMappingURL=chunk-GKSG5CPH.js.map
+//# sourceMappingURL=chunk-KVTEIUND.js.map

package/dist/{chunk-GDDXX27P.js → chunk-MBR5VAB5.js}

@@ -1,6 +1,6 @@
 import {
   resolveIndexDir
-} from "./chunk-N3K2SFEI.js";
+} from "./chunk-52UXXQMP.js";
 
 // src/codebase-index/project-server-endpoint.ts
 import { createHash } from "node:crypto";
@@ -120,4 +120,4 @@ export {
   PROJECT_INDEX_SERVER_MAX_FRAME_CHARS,
   encodeProjectServerMessage
 };
-//# sourceMappingURL=chunk-GDDXX27P.js.map
+//# sourceMappingURL=chunk-MBR5VAB5.js.map

package/dist/{chunk-7LQCT3LT.js → chunk-NFX2IUQA.js}

@@ -1,10 +1,10 @@
 import {
   builtinToolsPack
-} from "./chunk-E7JE3UEX.js";
+} from "./chunk-EL2NJXSK.js";
 import {
   TIER1_TOOLS,
   TIER2_TOOLS
-} from "./chunk-IAYMTTR2.js";
+} from "./chunk-UCXFTCAI.js";
 
 // src/tool-tier.ts
 function toolNameSet(tools) {
@@ -54,4 +54,4 @@ export {
   selectBuiltinToolsForTier,
   registerBuiltinToolTier
 };
-//# sourceMappingURL=chunk-7LQCT3LT.js.map
+//# sourceMappingURL=chunk-NFX2IUQA.js.map

package/dist/{chunk-ZTCJCYLN.js → chunk-TI5COGLY.js}

@@ -9,7 +9,7 @@ import {
   projectIndexServerBuildId,
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath
-} from "./chunk-GDDXX27P.js";
+} from "./chunk-MBR5VAB5.js";
 import {
   CircuitOpenError,
   IndexTimeoutError,
@@ -24,7 +24,10 @@ import {
   searchService,
   statsService,
   symbolGraphService
-} from "./chunk-N3K2SFEI.js";
+} from "./chunk-52UXXQMP.js";
+import {
+  recordIpcPending
+} from "./chunk-ZKC5UNGD.js";
 import {
   isIndexablePath
 } from "./chunk-YOHO4DVT.js";
@@ -385,6 +388,7 @@ var ProjectServerConnection = class {
         onAbort,
         onProgress: options.onProgress
       });
+      recordIpcPending(this.pending.size);
       if (signal && onAbort) {
         signal.addEventListener("abort", onAbort, { once: true });
         if (signal.aborted) {
@@ -1032,6 +1036,7 @@ async function callInline(op, args, opts) {
 }
 var chain = Promise.resolve();
 function withMutex(job) {
+  if (process.env["WRONGSTACK_INDEX_BENCH_NO_HOST_MUTEX"] === "1") return job();
   const run = chain.then(job, job);
   chain = run.then(
     () => void 0,
@@ -1048,6 +1053,7 @@ function circuitOpenError() {
 var DEFAULT_DEBOUNCE_MS = 400;
 var DEFAULT_COALESCE_WINDOW_MS = 50;
 var debounceTimers = /* @__PURE__ */ new Map();
+var pendingReindexCompletions = /* @__PURE__ */ new Map();
 var readyReindexBatches = /* @__PURE__ */ new Map();
 function debounceKey(projectRoot, indexDir, file) {
   return JSON.stringify([projectRoot, indexDir ?? "", file]);
@@ -1055,6 +1061,11 @@ function debounceKey(projectRoot, indexDir, file) {
 function reindexBatchKey(projectRoot, indexDir) {
   return JSON.stringify([projectRoot, indexDir ?? ""]);
 }
+function settleReindexCompletions(completions, _error) {
+  for (const completion of completions) {
+    completion.resolve();
+  }
+}
 function flushReadyReindexBatch(key) {
   const batch = readyReindexBatches.get(key);
   if (!batch) return;
@@ -1062,6 +1073,7 @@ function flushReadyReindexBatch(key) {
   if (!indexCircuitBreaker.allowRequest()) {
     const error = circuitOpenError();
     for (const onError of batch.onErrors) onError(error);
+    settleReindexCompletions(batch.completions, error);
     return;
   }
   void withMutex(
@@ -1075,21 +1087,28 @@ function flushReadyReindexBatch(key) {
       { timeoutMs: batch.timeoutMs }
     )
   ).then(
-    () => indexCircuitBreaker.recordSuccess(),
+    () => {
+      indexCircuitBreaker.recordSuccess();
+      settleReindexCompletions(batch.completions);
+    },
     (err) => {
       indexCircuitBreaker.recordFailure(err);
       for (const onError of batch.onErrors) onError(err);
+      settleReindexCompletions(batch.completions, err);
     }
   );
 }
 function addReadyReindex(opts) {
   const key = reindexBatchKey(opts.projectRoot, opts.indexDir);
   const windowMs = opts.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS;
+  const pending2 = pendingReindexCompletions.get(key);
+  pendingReindexCompletions.delete(key);
   const existing = readyReindexBatches.get(key);
   if (existing) {
     existing.files.add(opts.file);
     existing.timeoutMs = Math.max(existing.timeoutMs, opts.timeoutMs);
     if (opts.onError) existing.onErrors.add(opts.onError);
+    if (pending2) for (const completion of pending2) existing.completions.add(completion);
     if (windowMs > 0 && existing.flush) {
       clearTimeout(existing.flush);
       existing.flush = setTimeout(() => flushReadyReindexBatch(key), windowMs);
@@ -1102,7 +1121,8 @@ function addReadyReindex(opts) {
     indexDir: opts.indexDir,
     files: /* @__PURE__ */ new Set([opts.file]),
     timeoutMs: opts.timeoutMs,
-    onErrors: new Set(opts.onError ? [opts.onError] : [])
+    onErrors: new Set(opts.onError ? [opts.onError] : []),
+    completions: pending2 ?? /* @__PURE__ */ new Set()
   };
   batch.flush = setTimeout(() => flushReadyReindexBatch(key), Math.max(0, windowMs));
   batch.flush.unref?.();
@@ -1170,7 +1190,13 @@ async function runStartupIndex(opts) {
 }
 function enqueueReindex(opts) {
   const files = opts.files.filter(isIndexableFile);
-  if (files.length === 0) return;
+  if (files.length === 0) return Promise.resolve();
+  const completion = new Promise((resolve, reject) => {
+    const key = reindexBatchKey(opts.projectRoot, opts.indexDir);
+    const pending2 = pendingReindexCompletions.get(key) ?? /* @__PURE__ */ new Set();
+    pending2.add({ resolve, reject });
+    pendingReindexCompletions.set(key, pending2);
+  });
   const ms = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   for (const file of files) {
     const key = debounceKey(opts.projectRoot, opts.indexDir, file);
@@ -1190,6 +1216,7 @@ function enqueueReindex(opts) {
     timer.unref?.();
     debounceTimers.set(key, timer);
   }
+  return completion;
 }
 function cancelPendingReindexes() {
   for (const t of debounceTimers.values()) clearTimeout(t);
@@ -1197,7 +1224,15 @@ function cancelPendingReindexes() {
   for (const batch of readyReindexBatches.values()) {
     if (batch.flush) clearTimeout(batch.flush);
   }
+  const cancelled = new Error("pending reindex cancelled");
+  for (const batch of readyReindexBatches.values()) {
+    settleReindexCompletions(batch.completions, cancelled);
+  }
   readyReindexBatches.clear();
+  for (const completions of pendingReindexCompletions.values()) {
+    settleReindexCompletions(completions, cancelled);
+  }
+  pendingReindexCompletions.clear();
 }
 async function searchCodebaseIndex(args, opts = {}) {
   return callIndexOp("search", args, {
@@ -1211,6 +1246,12 @@ async function codebaseIndexStats(args, opts = {}) {
     signal: opts.signal
   });
 }
+async function codebaseContext(args) {
+  return callIndexOp("context", args, { timeoutMs: DEFAULT_QUERY_TIMEOUT_MS });
+}
+async function codebaseVectorSearch(args) {
+  return callIndexOp("vectorSearch", args, { timeoutMs: DEFAULT_QUERY_TIMEOUT_MS });
+}
 async function packageGraphService2(args) {
   return callIndexOp("packageGraph", args, { timeoutMs: DEFAULT_QUERY_TIMEOUT_MS });
 }
@@ -1260,6 +1301,8 @@ export {
   cancelPendingReindexes,
   searchCodebaseIndex,
   codebaseIndexStats,
+  codebaseContext,
+  codebaseVectorSearch,
   packageGraphService2 as packageGraphService,
   fileGraphService2 as fileGraphService,
   symbolGraphService2 as symbolGraphService,
@@ -1269,4 +1312,4 @@ export {
   checkCodebaseIndexServerHealth,
   ensureCodebaseIndexServer
 };
-//# sourceMappingURL=chunk-ZTCJCYLN.js.map
+//# sourceMappingURL=chunk-TI5COGLY.js.map

package/dist/{chunk-CGXTR34H.js → chunk-TU5MTW2S.js}

@@ -1,6 +1,6 @@
 import {
   enqueueReindex
-} from "./chunk-ZTCJCYLN.js";
+} from "./chunk-TI5COGLY.js";
 import {
   resolveRealInsideRoot,
   safeResolveReal,
@@ -395,4 +395,4 @@ function extractPatchedFiles(output) {
 export {
   patchTool
 };
-//# sourceMappingURL=chunk-CGXTR34H.js.map
+//# sourceMappingURL=chunk-TU5MTW2S.js.map

package/dist/{chunk-IAYMTTR2.js → chunk-UCXFTCAI.js}

@@ -3,6 +3,7 @@ import {
 } from "./chunk-RV7BVTDG.js";
 import {
   codebaseAstReplaceTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseIndexTool,
@@ -14,7 +15,7 @@ import {
   codebaseStatsTool,
   codebaseTargetedTestTool,
   deadCodeScanTool
-} from "./chunk-YEISRT4S.js";
+} from "./chunk-HWXIRVKH.js";
 import {
   planTool
 } from "./chunk-5KS24LTS.js";
@@ -62,7 +63,7 @@ import {
 } from "./chunk-AQ5YBURX.js";
 import {
   patchTool
-} from "./chunk-CGXTR34H.js";
+} from "./chunk-TU5MTW2S.js";
 import {
   jsonTool
 } from "./chunk-VZGPASGD.js";
@@ -88,7 +89,7 @@ import {
 } from "./chunk-7N5U2RAU.js";
 import {
   replaceTool
-} from "./chunk-IYH4OHBP.js";
+} from "./chunk-DKHMPKDG.js";
 import {
   globTool
 } from "./chunk-ASEXQRA7.js";
@@ -133,13 +134,13 @@ import {
 } from "./chunk-SOR7OCYP.js";
 import {
   readTool
-} from "./chunk-MK2JK35J.js";
+} from "./chunk-UOYRAS4J.js";
 import {
   writeTool
-} from "./chunk-GKSG5CPH.js";
+} from "./chunk-KVTEIUND.js";
 import {
   editTool
-} from "./chunk-DK4J2WMH.js";
+} from "./chunk-7XUEPBNT.js";
 import {
   resolvePowerShell
 } from "./chunk-KE7A76VC.js";
@@ -1233,7 +1234,8 @@ var BUILTIN_TOOL_DESCRIPTIONS = {
   "codebase-stats": "Report codebase-index health, indexed file and symbol counts, languages, and freshness. Use it before relying on indexed discovery results.",
   "codebase-search": "Search indexed symbols, signatures, and documentation with optional language, kind, path, or LSP-kind filters. Use it for semantic discovery before broad text search.",
   "codebase-skeleton": "Extract a compact structural skeleton from a source file or directory, preserving declarations while omitting implementation detail. Use it to understand unfamiliar code quickly.",
-  "codebase-repo-map": "Generate a reference-weighted, token-budgeted Repository Map of the codebase within ~1200 tokens by default. Use at the beginning of complex tasks or when navigating unfamiliar repositories to get a bird-eye view of the architecture.",
+  "codebase-context": "Find the files and declarations a task touches from a plain-language description. Ranked symbol search seeds a personalised walk over the reference graph, so results include what the matches are structurally attached to, not just what matched by name. Start here for any task spanning more than one file.",
+  "codebase-repo-map": "Generate a centrality-ranked, token-budgeted Repository Map within ~1200 tokens by default: package clusters with their hub file, the repo-wide hotspots, then the signatures of the most central files. Use at the beginning of complex tasks or when navigating unfamiliar repositories to get a bird-eye view of the architecture.",
   "codebase-impact-analysis": "Find likely callers, dependents, related tests, and change risk for a named symbol. Use it before changing a public or widely used declaration.",
   "codebase-targeted-test": "Discover and run tests that cover a specified symbol, source file, or explicit test files. Use it for focused regression validation after a change.",
   "security-ast-scan": "Statically scan source code for supported security patterns and return findings with locations. Use it as a focused code check, not as a substitute for a full security assessment.",
@@ -1305,6 +1307,7 @@ var TIER1_TOOLS = [
   codebaseSearchTool,
   codebaseSkeletonTool,
   codebaseRepoMapTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseTargetedTestTool,
   securityAstScanTool,
@@ -1366,6 +1369,7 @@ var rawBuiltinTools = [
   codebaseSearchTool,
   codebaseSkeletonTool,
   codebaseRepoMapTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseTargetedTestTool,
   securityAstScanTool,
@@ -1434,4 +1438,4 @@ export {
   TIER3_TOOLS,
   builtinTools
 };
-//# sourceMappingURL=chunk-IAYMTTR2.js.map
+//# sourceMappingURL=chunk-UCXFTCAI.js.map

package/dist/{chunk-MK2JK35J.js → chunk-UOYRAS4J.js}

@@ -1,10 +1,10 @@
 import {
   getIndexState,
   searchCodebaseIndex
-} from "./chunk-ZTCJCYLN.js";
+} from "./chunk-TI5COGLY.js";
 import {
   codebaseIndexDirOverride
-} from "./chunk-N3K2SFEI.js";
+} from "./chunk-52UXXQMP.js";
 import {
   isBinaryBuffer,
   safeResolveReal,
@@ -340,4 +340,4 @@ ${interesting.join("\n")}` : "symbols/imports: (none detected)"
 export {
   readTool
 };
-//# sourceMappingURL=chunk-MK2JK35J.js.map
+//# sourceMappingURL=chunk-UOYRAS4J.js.map

package/dist/{chunk-UCYQTZ7F.js → chunk-ZKC5UNGD.js}

@@ -94,10 +94,58 @@ function dedupeRefs(refs) {
   });
 }
 
+// src/codebase-index/perf-metrics.ts
+var counters = {
+  filesystemBytesRead: 0,
+  filesystemReadCount: 0,
+  parserGateWaitMs: 0,
+  parserGateCalls: 0,
+  parserSubprocessCount: 0,
+  ipcPendingPeak: 0,
+  writeQueueWaitMs: 0,
+  writeQueueCalls: 0
+};
+function resetCodebaseIndexPerfMetrics() {
+  for (const key of Object.keys(counters)) {
+    counters[key] = 0;
+  }
+}
+function getCodebaseIndexPerfSnapshot() {
+  return { ...counters };
+}
+function recordFilesystemRead(bytes) {
+  counters.filesystemBytesRead += Math.max(0, bytes);
+  counters.filesystemReadCount++;
+}
+function recordParserGateWait(waitMs) {
+  counters.parserGateWaitMs += Math.max(0, waitMs);
+  counters.parserGateCalls++;
+}
+function recordParserSubprocess() {
+  counters.parserSubprocessCount++;
+}
+function recordIpcPending(depth) {
+  counters.ipcPendingPeak = Math.max(counters.ipcPendingPeak, depth);
+}
+function recordWriteQueueWait(waitMs) {
+  counters.writeQueueWaitMs += Math.max(0, waitMs);
+  counters.writeQueueCalls++;
+}
+
 // src/codebase-index/spawn-gate.ts
 var chain = Promise.resolve();
 function withSpawnGate(fn) {
-  const run = chain.then(fn, fn);
+  const queuedAt = performance.now();
+  const run = chain.then(
+    () => {
+      recordParserGateWait(performance.now() - queuedAt);
+      return fn();
+    },
+    () => {
+      recordParserGateWait(performance.now() - queuedAt);
+      return fn();
+    }
+  );
   chain = run.then(
     () => void 0,
     () => void 0
@@ -108,6 +156,12 @@ function withSpawnGate(fn) {
 export {
   parseParserOutput,
   parseParserBatchOutput,
+  resetCodebaseIndexPerfMetrics,
+  getCodebaseIndexPerfSnapshot,
+  recordFilesystemRead,
+  recordParserSubprocess,
+  recordIpcPending,
+  recordWriteQueueWait,
   withSpawnGate
 };
-//# sourceMappingURL=chunk-UCYQTZ7F.js.map
+//# sourceMappingURL=chunk-ZKC5UNGD.js.map

package/dist/codebase-index/atlas-brief.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The Atlas brief — what an agent should already know before it asks anything.
+ *
+ * Every other part of this subsystem answers a question. This one answers the
+ * question nobody asks: *what is this repository?* An agent that has to
+ * discover the shape of an 8,000-file monorepo by search costs a dozen tool
+ * calls per session and rediscovers the same thing every session. A few
+ * hundred tokens of "here are the twenty files everything depends on, here is
+ * what each package is for" removes that repeatedly-paid cost.
+ *
+ * ## Why it is a structure, not a string
+ *
+ * The renderer lives with the caller because the budget does. The CLI's
+ * system-prompt contributor has a hard token ceiling and trims from the
+ * bottom; a webui panel or a `--brief` flag would want different cuts of the
+ * same data. Building a string here would force one budget on all of them.
+ *
+ * ## Why it reports staleness rather than hiding it
+ *
+ * A brief describing code that has since changed is worse than no brief: it
+ * is confidently wrong in a way the reader cannot detect. `staleFiles` is
+ * carried so the caller can say so out loud.
+ */
+import { type IndexStore } from './writer.js';
+/** Hubs named in the brief. Past roughly this many, it stops being a summary. */
+export declare const BRIEF_HUB_LIMIT = 20;
+/** Packages named in the brief. */
+export declare const BRIEF_PACKAGE_LIMIT = 12;
+/** Subsystem one-liners included when the concept layer has run. */
+export declare const BRIEF_SUBSYSTEM_LIMIT = 10;
+export interface AtlasBriefHub {
+    path: string;
+    /** Rank relative to the most central file in the repository. */
+    rank: number;
+    /** Concept-layer summary, when the layer has run for this file. */
+    concept?: string | undefined;
+}
+export interface AtlasBriefPackage {
+    name: string;
+    files: number;
+    /** The package's most central file. */
+    hub: string;
+}
+export interface AtlasBriefSubsystem {
+    name: string;
+    summary: string;
+}
+export interface AtlasBrief {
+    /** True once the rank pass has run; false means only counts are meaningful. */
+    ranked: boolean;
+    counts: {
+        files: number;
+        symbols: number;
+        packages: number;
+    };
+    hubs: AtlasBriefHub[];
+    packages: AtlasBriefPackage[];
+    subsystems: AtlasBriefSubsystem[];
+    /**
+     * Files whose content changed since the written atlas was generated, or
+     * `undefined` when no atlas has been written — a project that never ran
+     * `--write` is not stale, it simply has no projection.
+     */
+    staleFiles?: number | undefined;
+}
+/**
+ * Build the brief from an open store.
+ *
+ * Reads only what it names: the ranked head, not the whole ranking. On an
+ * index with no ranks this returns `ranked: false` and empty lists rather
+ * than falling back to a filename heuristic — a guess presented as the
+ * repository's structure is the failure mode this whole subsystem exists to
+ * remove.
+ */
+export declare function buildAtlasBrief(store: IndexStore, projectRoot: string): Promise<AtlasBrief>;
+/** Reported when a project has no index to summarise. */
+export type AtlasBriefIndexMissing = {
+    indexed: false;
+};
+/**
+ * Build a project's brief, owning the store lifetime.
+ *
+ * Refuses without an index for the same reason every other project-level
+ * entry point does: acquiring a store CREATES the database, and a prompt
+ * contributor must never be the thing that indexes a repository.
+ */
+export declare function buildProjectAtlasBrief(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<AtlasBrief | AtlasBriefIndexMissing>;
+//# sourceMappingURL=atlas-brief.d.ts.map

package/dist/codebase-index/atlas-export.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Single-file, dependency-free HTML rendering of the atlas.
+ *
+ * The WebUI's CodeMap is the interactive view, but it needs a running server, a
+ * built index and a browser pointed at localhost. This is the other half: one
+ * file you can attach to a pull request, publish as a CI artifact, or mail to
+ * somebody who will never install the toolchain.
+ *
+ * ## Why it embeds rather than fetches
+ *
+ * A page that fetches `atlas.json` beside it does not work from `file://` in
+ * any modern browser — the request is a cross-origin one to a null origin. The
+ * data is inlined as JSON so a double-click opens a working map.
+ *
+ * ## Why the layout is computed here, not in the page
+ *
+ * A force simulation in the page would make the same input produce a slightly
+ * different picture on every open. Positions are computed once, deterministic
+ * given the document, so two exports of the same index are byte-identical and
+ * a committed export diffs meaningfully.
+ */
+import type { AtlasDocument } from './atlas-types.js';
+/** Packages drawn on the canvas. Beyond this the picture stops being readable. */
+export declare const EXPORT_PACKAGE_LIMIT = 40;
+/** Files listed in the ranked table. */
+export declare const EXPORT_FILE_LIMIT = 120;
+export interface AtlasExportOptions {
+    /** Repository name shown in the header. */
+    projectName?: string | undefined;
+}
+/**
+ * Render the atlas as one self-contained HTML document.
+ *
+ * Deterministic: the same {@link AtlasDocument} always produces the same bytes,
+ * with no timestamp, no random ids and no measurement of the host.
+ */
+export declare function renderAtlasHtml(document: AtlasDocument, options?: AtlasExportOptions): string;
+//# sourceMappingURL=atlas-export.d.ts.map

package/dist/codebase-index/atlas-projection.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Atlas — a committable projection of the codebase index.
+ *
+ * The index itself is a 180 MB SQLite database under `~/.wrongstack/projects/`:
+ * machine-local, binary, and unreviewable. That means every fresh clone, every
+ * CI run and every teammate starts cold, and nobody can see in a pull request
+ * what the index believes about the code.
+ *
+ * The atlas is the derived, human-sized answer to that: a small, deterministic
+ * set of files written into the repository at `.wrongstack/atlas/`. The
+ * database stays canonical — this is strictly a one-way projection, and
+ * regenerating it from an unchanged index must produce byte-identical output.
+ *
+ * ## Determinism is a hard requirement
+ *
+ * Anything that varies between two runs over the same index turns every
+ * indexing run into a merge conflict. So: no timestamps, no host paths, keys
+ * emitted in sorted order, floats rounded to a fixed precision, and LF line
+ * endings (the pre-commit hook enforces those repo-wide anyway).
+ *
+ * ## Staleness is reported, never guessed
+ *
+ * A committed atlas describing code that has since moved is worse than no
+ * atlas, because it is confidently wrong. {@link checkAtlasFreshness} compares
+ * the recorded per-file content hashes against the live index and says exactly
+ * which files drifted.
+ */
+import type { AtlasDocument, AtlasEdge, AtlasFile, AtlasManifest, AtlasPackage, AtlasProjection, AtlasSymbol } from './atlas-types.js';
+import type { FileRankRow } from './graph-rank.js';
+import { type IndexStore } from './writer.js';
+/** Directory the projection is written to, relative to the project root. */
+export declare const ATLAS_DIR: string;
+export declare const ATLAS_JSON = "atlas.json";
+export declare const ATLAS_MARKDOWN = "ATLAS.md";
+export declare const ATLAS_MANIFEST = "manifest.json";
+/**
+ * Bumped when the emitted shape changes. A reader seeing a different schema
+ * reports the atlas as stale rather than misinterpreting its fields.
+ */
+export declare const ATLAS_SCHEMA = 2;
+/**
+ * Files carried in the projection. Enough to describe the architecture,
+ * small enough to read in a diff — the full 8k-file list would be neither.
+ */
+export declare const ATLAS_FILE_LIMIT = 300;
+export type { AtlasDocument, AtlasEdge, AtlasFile, AtlasManifest, AtlasPackage, AtlasProjection, AtlasSymbol, };
+/**
+ * Build the projection from the index. Pure with respect to the filesystem —
+ * {@link writeAtlas} is what touches disk.
+ */
+export declare function buildAtlas(store: IndexStore, projectRoot: string): AtlasProjection;
+export interface WrittenAtlas {
+    dir: string;
+    files: string[];
+    fileCount: number;
+    packageCount: number;
+}
+/** Write the projection into `<projectRoot>/.wrongstack/atlas/`. */
+export declare function writeAtlas(store: IndexStore, projectRoot: string): Promise<WrittenAtlas>;
+export interface AtlasFreshness {
+    fresh: boolean;
+    /** Why it is not fresh. Absent when `fresh`. */
+    reason?: 'missing' | 'unreadable' | 'schema' | 'drift' | undefined;
+    /** Atlas files whose content hash no longer matches the index. */
+    changed: string[];
+    /** Atlas files the index no longer knows about. */
+    removed: string[];
+    /** Indexed files absent from the atlas manifest. */
+    added: number;
+    /** True when the whole-repository digest still matches. */
+    digestMatches: boolean;
+}
+/** Files listed in a drift report before it is summarised rather than enumerated. */
+export declare const MAX_REPORTED_DRIFT = 20;
+/**
+ * Compare the committed atlas against the live index.
+ *
+ * Reads only the manifest — the atlas document and markdown are derived from
+ * the same data, so a manifest that matches means all three are current.
+ */
+export declare function checkAtlasFreshness(store: IndexStore, projectRoot: string): Promise<AtlasFreshness>;
+/**
+ * Project-level entry points.
+ *
+ * These own the store lifetime so callers outside this package never have to
+ * touch `indexStorePool`. Both refuse to run when there is no index yet:
+ * opening a store CREATES the database, and neither writing an atlas nor
+ * checking one should be the thing that indexes a project.
+ */
+export type AtlasIndexMissing = {
+    indexed: false;
+};
+/** Write the atlas for a project, or report that it has no index yet. */
+export declare function writeProjectAtlas(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<WrittenAtlas | AtlasIndexMissing>;
+/** Check a project's written atlas against its index. */
+export declare function checkProjectAtlasFreshness(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<AtlasFreshness | AtlasIndexMissing>;
+/**
+ * Build a project's static HTML atlas, or report that it has no index yet.
+ *
+ * Returns the markup rather than writing it: where the file belongs is the
+ * caller's decision (a CI artifact directory, a temp file the CLI opens, an
+ * HTTP response body), and this package should not guess.
+ */
+export declare function exportProjectAtlasHtml(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+    projectName?: string | undefined;
+}): Promise<string | AtlasIndexMissing>;
+/** Re-exported for callers that render rank rows next to atlas output. */
+export type { FileRankRow };
+//# sourceMappingURL=atlas-projection.d.ts.map