gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/storage/parsedfile-store.d.ts

@@ -24,11 +24,11 @@
  *
  * ## Shape
  *
- * `<storagePath>/parsedfile-store/<shardId>.json` — one shard per parse chunk,
- * a JSON array of `ParsedFile` serialized with the same `mapReplacer` the parse
- * cache uses (Scope.bindings / Scope.typeBindings are `Map`s). The store is
- * cleared at the start of each parse and after scope-resolution consumes it, so
- * it never lingers and never goes stale across runs.
+ * `<storagePath>/parsedfile-store/<shardId>.v8` — one shard per parse chunk,
+ * a V8 envelope of `ParsedFile[]` (Scope.bindings / Scope.typeBindings stay
+ * `Map`s). The store is cleared at the start of each parse and after
+ * scope-resolution consumes it, so it never lingers and never goes stale
+ * across runs.
  *
  * ## Durable sibling store (`parsedfile-cache/`, warm-cache coverage)
  *
@@ -41,11 +41,11 @@
  * that gap we ALSO write the worker's ParsedFiles to a second, CONTENT-ADDRESSED
  * store keyed by the parse chunk hash (`getDurableParsedFileDir`), which mirrors
  * the parse cache's lifecycle (persists across runs, pruned by `usedKeys`,
- * version-tied via `PARSE_CACHE_VERSION`). On a warm hit the chunk's durable
- * shards are byte-COPIED into the run-scoped store (no re-parse, no
- * re-serialize → byte-identical), so scope-resolution streams them exactly as
- * on a cold run. Content-addressing makes stale reuse impossible: a changed
- * file changes its chunk hash, which misses BOTH stores and re-dispatches.
+ * version-tied via `PARSE_CACHE_VERSION`). On a warm hit the chunk's immutable
+ * durable shards are hardlinked (or atomically copied) into the run store after
+ * their envelope metadata proves complete coverage. That pins a stable snapshot
+ * before workers are skipped, even when another branch refreshes the shared
+ * durable directory concurrently.
  */
 import type { ParsedFile, SymbolDefinition } from '../_shared/index.js';
 /**
@@ -73,30 +73,25 @@ export declare const getParsedFileStoreDir: (storagePath: string) => string;
 /** Remove any prior run's shards so a fresh parse starts clean. Idempotent. */
 export declare const clearParsedFileStore: (storagePath: string) => Promise<void>;
 /**
- * Write one parse chunk's `ParsedFile[]` to the store as a single shard (async).
- * No-op for an empty chunk. `shardId` must be unique within a run. Used by the
- * main-thread no-store-disabled fallback and any non-worker writer; the worker
- * store path uses {@link persistParsedFileShardSync}.
+ * Test seam for #3086. Production always calls {@link forceGc}; unit tests
+ * replace `run` to count cadence without requiring `--expose-gc`.
  */
-export declare const persistParsedFileChunk: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => Promise<void>;
+export declare const parsedFileLoadGc: {
+    run: () => void;
+    /** V8 envelope bytes visited between GCs (#3086). Tests may lower this. */
+    byteBudget: number;
+};
 /**
- * Synchronous shard writer for use INSIDE a parse worker (#1983 parallel
- * serialization). The worker is a dedicated thread, so a blocking write there
- * protects the main thread, and a sync write avoids threading `async`/`await`
- * through the synchronous per-file extract loop. Produces byte-identical shards
- * to {@link persistParsedFileChunk} via the shared {@link serializeParsedFileShard}.
- * No-op for an empty chunk. `shardId` must be globally unique for the run (the
- * worker uses `w<threadId>-<seq>`); a duplicate would silently overwrite.
+ * Write one parse chunk's `ParsedFile[]` to the store as a single `.v8` shard.
+ * No-op for an empty chunk. `shardId` must be unique within a run.
  */
-export declare const persistParsedFileShardSync: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => void;
+export declare const persistParsedFileChunk: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => Promise<boolean>;
 /**
- * Stream the store and return the `ParsedFile`s whose `filePath` is in
- * `wantPaths`, keyed by path. Loads one shard at a time and retains only the
- * matching entries, so peak heap is bounded by (matched set) + (one shard)
- * rather than the whole store. Returns an empty map when the store is absent
- * (e.g. tests, or a run with no worker pool) — callers fall back to a fresh
- * extract for the missing files.
+ * Synchronous shard writer for use INSIDE a parse worker (#1983 parallel
+ * serialization). Returns false on write failure so the worker can keep
+ * ParsedFiles in the result instead of dropping them.
  */
+export declare const persistParsedFileShardSync: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => boolean;
 export declare const loadParsedFilesForPaths: (storagePath: string, wantPaths: ReadonlySet<string>) => Promise<Map<string, ParsedFile>>;
 /** Durable store dir — a sibling of `parsedfile-store/`, NEVER cleared per run. */
 export declare const getDurableParsedFileDir: (storagePath: string) => string;
@@ -108,43 +103,29 @@ export declare const getDurableParsedFileDir: (storagePath: string) => string;
  * from accumulating across analyses.
  */
 export declare const prepareDurableParsedFileChunk: (durableDir: string, chunkHash: string) => Promise<void>;
+export declare const persistDurableParsedFileShardSync: (durableDir: string, chunkHash: string, threadId: number, shardSeq: number, parsedFiles: readonly ParsedFile[]) => boolean;
 /**
- * Synchronous durable-shard writer for use INSIDE a parse worker, alongside
- * {@link persistParsedFileShardSync}. Writes the SAME bytes to a content-addressed
- * durable location keyed by the parse chunk hash so a future warm hit can reuse
- * them. `chunkHash`+`threadId`+`shardSeq` is collision-free across the
- * N-shards-per-chunk fan-out and across worker-death retries — the same
- * uniqueness that makes the run-scoped `w<tid>-<seq>` name safe, prefixed by
- * content. No-op for an empty chunk.
- */
-export declare const persistDurableParsedFileShardSync: (durableDir: string, chunkHash: string, threadId: number, shardSeq: number, parsedFiles: readonly ParsedFile[]) => void;
-/**
- * Restore a cached chunk's durable shards into the run-scoped store on a warm
- * hit. A verbatim byte copy (no parse, no re-serialize), so the restored
- * ParsedFiles are byte-identical to a cold run and `loadParsedFilesForPaths`
- * (which keys on `filePath`, not shard name) gives scope-resolution full
- * coverage. The durable shard names already carry the chunk hash, so they never
- * collide with the worker's run-scoped `w<tid>-<seq>` shards. Returns the number
- * of shards restored (0 ⇒ no durable coverage for this chunk; caller treats it
- * as a miss).
+ * Validate and snapshot one durable chunk into the run store. Every envelope
+ * must be runtime-compatible and integrity-valid, and together they must match
+ * the path coverage recorded when the durable index was published. Linking
+ * before returning pins the inodes against concurrent branch-cache rotation.
  */
-export declare const restoreDurableParsedFileShard: (durableDir: string, runStoragePath: string, chunkHash: string) => Promise<number>;
-/**
- * Read the durable index and return the set of chunk hashes it vouches for,
- * gated on `expectedVersion` (`PARSE_CACHE_VERSION`). A version mismatch or a
- * missing/corrupt index returns the empty set — the caller then treats every
- * chunk as a durable miss and re-dispatches workers (NEVER the main-thread
- * `extractParsedFile` fallback), which rewrites the durable store under the new
- * version. Mirrors `loadParseCache`'s version-invalidation contract.
- */
-export declare const loadDurableParsedFileIndex: (durableDir: string, expectedVersion: string) => Promise<Set<string>>;
+export declare const durableChunkHasShards: (runStoragePath: string, chunkHash: string, expectedPaths: ReadonlySet<string>) => Promise<boolean>;
+export declare const loadDurableParsedFileIndex: (durableDir: string, expectedVersion: string) => Promise<Map<string, ReadonlySet<string>>>;
 /**
  * Prune the durable store to `keepKeys` and rewrite its index. `keepKeys` must
  * be the parse cache's surviving on-disk keys (so the two stores stay coherent:
  * a chunk is "cached" iff BOTH its parse-cache shard and its durable shards
  * exist; a quarantined chunk — no parse-cache shard — drops its durable subdir
- * here and re-dispatches next run). Only subdirs with ≥1 shard are indexed
- * (mirrors `saveParseCache`'s written-keys discipline — never vouch for a chunk
- * hash with no backing shard). The index write is tmp+rename atomic.
+ * here and re-dispatches next run). Only chunks whose envelopes all validate
+ * are indexed, together with their exact persisted path coverage (never vouch
+ * for a missing/corrupt shard). The index write is tmp+rename atomic.
  */
 export declare const pruneAndSaveDurableParsedFileStore: (durableDir: string, version: string, keepKeys: ReadonlySet<string>) => Promise<void>;
+/**
+ * Overlay this run's staged durable ParsedFile chunks onto the live store,
+ * then prune the live tree to `keepKeys`. Live chunks this run did not rewrite
+ * (other branches, unused hashes) stay until prune. No-op overlay when the
+ * staged dir is missing.
+ */
+export declare const mergeStagedDurableParsedFileStore: (liveStoragePath: string, stagedStoragePath: string, version: string, keepKeys: ReadonlySet<string>) => Promise<void>;