@wrongstack/tools 0.309.1 → 0.310.0

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

@@ -4,6 +4,22 @@ export declare class GenerationLruCache<T> {
     private readonly entries;
     constructor(maxEntries: number);
     get(key: string, generation: number): T | undefined;
+    /**
+     * Read an entry regardless of which generation wrote it, without touching
+     * LRU recency. Used by the project server to serve a previous-generation
+     * (stale) answer while an index refresh is publishing — the caller marks the
+     * response `stale` instead of failing the read.
+     */
+    peek(key: string): T | undefined;
+    /**
+     * Like {@link peek} but exposes the entry's generation, so the stale-read
+     * policy can bound how far a preserved entry may lag the publishing
+     * generation before it is too old to serve.
+     */
+    peekEntry(key: string): {
+        generation: number;
+        value: T;
+    } | undefined;
     set(key: string, generation: number, value: T): T;
     clear(): void;
     get size(): number;

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

@@ -1,6 +1,6 @@
+import { getProjectIndexServerConnectionState, isProjectIndexServerAvailable, onProjectIndexServerConnectionStateChange, type ProjectIndexDaemonAvailability, type ProjectIndexServerClientHealth, type ProjectIndexServerConnectionState, type ProjectIndexServerConnectionStatus, type ProjectIndexServerShutdownResult, type ProjectServerCallOptions, projectIndexServerExpectedBuildId, resolveProjectIndexDaemonAvailability } from './project-server-client-state.js';
 import type { OpName, OpShapes } from './worker-protocol.js';
-import { type ProjectServerCallOptions, type ProjectIndexServerShutdownResult, type ProjectIndexServerConnectionStatus, type ProjectIndexServerClientHealth, type ProjectIndexServerConnectionState, type ProjectIndexDaemonAvailability, resolveProjectIndexDaemonAvailability, projectIndexServerExpectedBuildId, isProjectIndexServerAvailable, getProjectIndexServerConnectionState, onProjectIndexServerConnectionStateChange } from './project-server-client-state.js';
-export { type ProjectServerCallOptions, type ProjectIndexServerShutdownResult, type ProjectIndexServerConnectionStatus, type ProjectIndexServerClientHealth, type ProjectIndexServerConnectionState, type ProjectIndexDaemonAvailability, resolveProjectIndexDaemonAvailability, projectIndexServerExpectedBuildId, isProjectIndexServerAvailable, getProjectIndexServerConnectionState, onProjectIndexServerConnectionStateChange, };
+export { getProjectIndexServerConnectionState, isProjectIndexServerAvailable, onProjectIndexServerConnectionStateChange, type ProjectIndexDaemonAvailability, type ProjectIndexServerClientHealth, type ProjectIndexServerConnectionState, type ProjectIndexServerConnectionStatus, type ProjectIndexServerShutdownResult, type ProjectServerCallOptions, projectIndexServerExpectedBuildId, resolveProjectIndexDaemonAvailability, };
 export declare function callProjectIndexServer<O extends OpName>(op: O, args: OpShapes[O]['args'], options: ProjectServerCallOptions): Promise<OpShapes[O]['result']>;
 export declare function ensureProjectIndexServer(options: {
     projectRoot: string;

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

@@ -0,0 +1,88 @@
+/**
+ * Read/completion policy for the detached project server's query caches.
+ *
+ * The server used to refuse every read for the duration of an index refresh
+ * and wipe all query caches on every completion (including single-file
+ * incremental runs). Together that made search/graph/stats unavailable both
+ * during a refresh and on the first reads after each incremental edit.
+ *
+ * The policy here instead:
+ *
+ * - **During a refresh** a cache HIT from any generation is served with a
+ *   `stale: true` marker. A miss still refuses: read ops share the server's
+ *   single pooled SQLite connection with the in-flight write transaction, so
+ *   loading fresh mid-run would be a dirty read of uncommitted rows, not a
+ *   merely-outdated read.
+ * - **On completion of an incremental run** the caches are kept. Entries are
+ *   re-tagged with the new generation as they are recomputed; surviving
+ *   previous-generation entries are what the next refresh's stale-serve
+ *   window hits. `stats` still refuses during a refresh — it is the progress
+ *   poll, and a cached pre-run answer would read as "finished with old
+ *   numbers".
+ * - **On completion of a full/forced run** (or a failed run whose
+ *   transaction may have rolled back the visible generation) all caches are
+ *   cleared.
+ */
+import type { IncomingCallsResult, OutgoingCallsResult } from './index-service.js';
+import { GenerationLruCache } from './project-server-cache.js';
+import type { CodeMapGraph, IndexStats, SearchResult } from './schema.js';
+/** The error the server answers a read it cannot serve with. */
+export declare function indexRefreshInProgressError(currentFile: number, totalFiles: number): Error;
+/**
+ * The slice of index activity a read decision needs. Structurally compatible
+ * with the server's `ProjectIndexServerActivity`, so the live activity object
+ * can be passed directly.
+ */
+export interface RefreshState {
+    generation: number;
+    indexing: boolean;
+    currentFile: number;
+    totalFiles: number;
+}
+/**
+ * How many completed generations a preserved cache entry may lag the
+ * publishing one and still be served stale during a refresh.
+ *
+ * Targeted runs preserve caches across completions, and generation only
+ * grows — an entry that survives many runs without being recomputed gets
+ * progressively older (a search answer from before several edits). Beyond
+ * this bound the entry is treated as too old to be useful and the read
+ * falls back to the refresh refusal, exactly like a cache miss.
+ */
+export declare const MAX_STALE_GENERATION_LAG = 2;
+/**
+ * One read against a generation cache under the stale-serve policy.
+ *
+ * - Refreshing + hit within {@link MAX_STALE_GENERATION_LAG} generations →
+ *   `{ value, stale: true }` from `peekEntry`.
+ * - Refreshing + miss (or entry older than the bound) → throws
+ *   `IndexRefreshInProgressError` (a fresh load would read uncommitted rows
+ *   through the shared pooled connection).
+ * - Idle + hit → `{ value, stale: false }`; idle + miss → `load()` and cache.
+ */
+export declare function staleAwareRead<T>(cache: GenerationLruCache<T>, key: string, refresh: RefreshState, load: () => T): {
+    value: T;
+    stale: boolean;
+};
+/** The project server's generation-scoped read caches, as a unit. */
+export declare class ServerQueryCaches {
+    /**
+     * Search answer (rows + total) keyed by the serialized query args. Rows and
+     * count are cached as ONE value: separate caches would let one half hit and
+     * the other miss, and a mid-refresh miss load would be a dirty read.
+     */
+    readonly searchCache: GenerationLruCache<{
+        results: SearchResult[];
+        total: number;
+    }>;
+    readonly statsCache: GenerationLruCache<IndexStats>;
+    readonly packageGraphCache: GenerationLruCache<CodeMapGraph>;
+    readonly fileGraphCache: GenerationLruCache<CodeMapGraph>;
+    readonly symbolGraphCache: GenerationLruCache<CodeMapGraph>;
+    readonly incomingCallsCache: GenerationLruCache<IncomingCallsResult>;
+    readonly outgoingCallsCache: GenerationLruCache<OutgoingCallsResult>;
+    clear(): void;
+    /** Cache sizes for the health snapshot. */
+    sizes(): Record<string, number>;
+}
+//# sourceMappingURL=project-server-query-cache.d.ts.map