@remnic/core 10.0.84 → 10.0.85

package/src/storage/buffer-drain-claims.ts

@@ -20,8 +20,9 @@
  *     extraction is not durably finished, so a kill at any point loses
  *     nothing and the next run resumes.
  *   - A live buffer owner that must persist a claimed session hands its
- *     in-memory entry INTO the claim (merge, identity-deduped) instead of
- *     writing a session file — it can never resurrect claimed turns.
+ *     in-memory entry INTO the claim (identity-aware, occurrence-preserving
+ *     merge) instead of writing a session file — it can never resurrect
+ *     turns the drain already finished.
  *   - Claims are idempotent: re-claiming, double-draining, and two
  *     concurrent drainers are all safe (per-key mutation lock + exclusive
  *     lease; the lock also fences lease takeover and progress writes).
@@ -38,7 +39,7 @@ import { mkdir, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import { bufferSessionFileName, type BufferFileIo } from "./buffer-session-files.js";
-import { bufferTurnsEqual, mergeBufferTurnsByIdentity, subtractBufferTurns } from "../buffer-turn-helpers.js";
+import { bufferTurnIdentityKey, subtractBufferTurns, type DrainedTurnSets } from "../buffer-turn-helpers.js";
 import { log } from "../logger.js";
 import { withHeldFileLock } from "../utils/serialize-mutations.js";
 import type { BufferEntryState, BufferTurn } from "../types.js";
@@ -47,11 +48,12 @@ import type { BufferEntryState, BufferTurn } from "../types.js";
 export interface BufferSessionSaveOutcome {
   /** "saved": the session file holds the entry. "handed_over": the entry moved into a drain claim. */
   status: "saved" | "handed_over";
-  /** Turns a drain already extracted (claim tombstone): the owner subtracts them from its copy. */
-  drainedTurns?: BufferTurn[];
+  /** Tombstoned turn identities by their original active/retained list. */
+  drainedTurns?: DrainedTurnSets;
 }
 
 export interface DrainLease {
+  /** Unique fencing token for one scheduler/process identity; never reuse it after restart. */
   ownerId: string;
   pid: number;
   /** Host the owner runs on: a takeover may only judge liveness on that host. */
@@ -74,6 +76,13 @@ export interface DrainClaimFile {
   drained?: BufferTurn[];
   /** Same tombstone for turns the drain extracted from `retainedTurns`. */
   drainedRetained?: BufferTurn[];
+  /**
+   * Pending turns whose only copy sits in the other list than the one they
+   * were claimed into (active to retained or back). When such a turn is
+   * extracted, its tombstone goes to BOTH lists: a live owner still holds
+   * the stale copy in the list the turn started in.
+   */
+  movedTurns?: BufferTurn[];
 }
 
 export type ClaimFromSessionOutcome = "claimed" | "empty" | "already_claimed";
@@ -95,29 +104,80 @@ function emptyEntry(): BufferEntryState {
   return { turns: [], lastExtractionAt: null, extractionCount: 0 };
 }
 
-/** Identity-dedupe `incoming` turns into `existing` (they are the same turns a
- * live owner still held after claiming; only genuinely NEW turns append). */
+function turnCounts(turns: readonly BufferTurn[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const turn of turns) {
+    const key = bufferTurnIdentityKey(turn);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
 function mergeTurns(existing: BufferTurn[], incoming: readonly BufferTurn[]): BufferTurn[] {
-  return mergeBufferTurnsByIdentity(existing, incoming);
+  const merged = [...existing];
+  const existingCounts = turnCounts(existing);
+  const incomingCounts = new Map<string, number>();
+  for (const turn of incoming) {
+    const key = bufferTurnIdentityKey(turn);
+    const count = (incomingCounts.get(key) ?? 0) + 1;
+    incomingCounts.set(key, count);
+    if (count > (existingCounts.get(key) ?? 0)) merged.push(turn);
+  }
+  return merged;
+}
+
+function preserveSourceOccurrences(
+  target: BufferTurn[],
+  source: readonly BufferTurn[],
+  identity: string,
+): void {
+  const targetCount = turnCounts(target).get(identity) ?? 0;
+  let sourceCount = 0;
+  for (const turn of source) {
+    if (bufferTurnIdentityKey(turn) !== identity) continue;
+    sourceCount += 1;
+    if (sourceCount > targetCount) target.push(turn);
+  }
+}
+
+function appendUnmatched(
+  snapshot: readonly BufferTurn[],
+  matchedCounts: ReadonlyMap<string, number>,
+  unmatched: BufferTurn[],
+): void {
+  const remaining = new Map(matchedCounts);
+  for (const turn of snapshot) {
+    const key = bufferTurnIdentityKey(turn);
+    const matched = remaining.get(key) ?? 0;
+    if (matched > 0) remaining.set(key, matched - 1);
+    else unmatched.push(turn);
+  }
+}
+
+function removeOneByIdentity(turns: BufferTurn[], identity: string): boolean {
+  const index = turns.findIndex((turn) => bufferTurnIdentityKey(turn) === identity);
+  if (index < 0) return false;
+  turns.splice(index, 1);
+  return true;
+}
+
+function takeByIdentity(source: readonly BufferTurn[], identity: string, count: number): BufferTurn[] {
+  return source.filter((turn) => bufferTurnIdentityKey(turn) === identity).slice(0, count);
 }
 
 function mergeEntries(claim: DrainClaimFile, incoming: BufferEntryState): DrainClaimFile {
   const entry = emptyEntry();
-  // Turns already extracted stay out of the pending entry even when the
-  // owner's incoming copy is stale and still carries them (either tombstone
-  // list counts — a turn in either one left the claim for good).
-  const gone = [...(claim.drained ?? []), ...(claim.drainedRetained ?? [])];
+  // The claim's own lists already exclude what was extracted; each tombstone
+  // applies only to the incoming copy in the list the turn was extracted from.
   entry.turns = mergeTurns(
-    subtractBufferTurns(claim.entry.turns, gone),
-    subtractBufferTurns(incoming.turns, gone),
+    claim.entry.turns,
+    subtractBufferTurns(incoming.turns, claim.drained ?? []),
   );
-  const retained = [
-    ...subtractBufferTurns(claim.entry.retainedTurns ?? [], gone),
-    ...subtractBufferTurns(incoming.retainedTurns ?? [], gone),
-  ];
-  // SAFETY: an empty accumulator of the same element type.
-  const dedupedRetained = mergeTurns([], retained);
-  if (dedupedRetained.length > 0) entry.retainedTurns = dedupedRetained;
+  entry.retainedTurns = mergeTurns(
+    claim.entry.retainedTurns ?? [],
+    subtractBufferTurns(incoming.retainedTurns ?? [], claim.drainedRetained ?? []),
+  );
+  if (entry.retainedTurns.length === 0) delete entry.retainedTurns;
   const stamps = [claim.entry.lastExtractionAt, incoming.lastExtractionAt].filter(
     (value): value is string => value !== null && value !== undefined,
   );
@@ -163,6 +223,7 @@ const claimBodySchema = z.object({
   claimedAt: z.string().optional(),
   drained: z.array(z.unknown()).optional(),
   drainedRetained: z.array(z.unknown()).optional(),
+  movedTurns: z.array(z.unknown()).optional(),
 });
 
 function parseBody(raw: string): DrainClaimFile | null {
@@ -204,6 +265,10 @@ function parseBody(raw: string): DrainClaimFile | null {
     // SAFETY: same boundary as the turns above (this module writes the file).
     claim.drainedRetained = body.drainedRetained as BufferTurn[];
   }
+  if (Array.isArray(body.movedTurns)) {
+    // SAFETY: same boundary as the turns above (this module writes the file).
+    claim.movedTurns = body.movedTurns as BufferTurn[];
+  }
   return claim;
 }
 
@@ -232,6 +297,10 @@ function parseLease(raw: string): DrainLease | null {
     leaseMs: lease.leaseMs,
   };
 }
+function leaseBelongsToProcess(lease: DrainLease | null, ownerId: string): boolean {
+  return lease !== null && lease.ownerId === ownerId && lease.pid === process.pid && lease.host === hostname();
+}
+
 
 /** Claim bodies `listPage` may read per requested entry: bounds one scan's
  *  I/O even when the directory is mostly empty tombstones. */
@@ -375,20 +444,19 @@ export class BufferDrainClaims {
       async (acquired) => {
         if (!acquired) return "busy";
         const existing = await this.readLease(key);
+        if (existing?.ownerId === lease.ownerId && existing.pid === lease.pid && existing.host === lease.host) {
+          // Reuse the token only from the same process identity.
+          await this.writeLease(key, { ...existing, heartbeatAt: new Date().toISOString(), leaseMs: lease.leaseMs });
+          return "adopted";
+        }
         if (existing && !isLeaseExpired(existing)) {
-          if (existing.ownerId === lease.ownerId) {
-            // The same drainer already holds it: renew the lease.
-            await this.writeLease(key, { ...existing, heartbeatAt: new Date().toISOString(), leaseMs: lease.leaseMs });
-            return "adopted";
-          }
           if (isOwnerAlive(existing)) return "busy";
           // The owner died without releasing the claim (killed worker):
           // take it over now instead of waiting for the lease to expire.
           await unlink(this.leaseFileFor(key)).catch(() => {});
         } else if (existing) {
           // Expired lease: clear it before the exclusive create. We hold the
-          // lock, so no concurrent adopter can interleave its own
-          // unlink/create between these steps.
+          // lock, so no concurrent adopter can interleave its own unlink/create.
           await unlink(this.leaseFileFor(key)).catch(() => {});
         }
         try {
@@ -444,7 +512,7 @@ export class BufferDrainClaims {
     await withHeldFileLock(this.lockFileFor(key), { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS }, async (acquired) => {
       if (!acquired) throw new Error(`buffer drain claim for ${key} is busy; progress write skipped`);
       const lease = await this.readLease(key);
-      if (!lease || lease.ownerId !== ownerId) {
+      if (!leaseBelongsToProcess(lease, ownerId)) {
         throw new Error(`buffer drain claim for ${key} is no longer owned by ${ownerId}; progress write skipped`);
       }
       const claim = await this.readClaimBody(key);
@@ -452,39 +520,87 @@ export class BufferDrainClaims {
       const seenTurns = seen?.turns ?? claim.entry.turns;
       const seenRetained = seen?.retainedTurns ?? claim.entry.retainedTurns ?? [];
       const entryRetained = entry.retainedTurns ?? [];
-      // Still held by the drainer: in its remaining turns OR retained for retry.
-      const kept = (turn: BufferTurn): boolean =>
-        entry.turns.some((held) => bufferTurnsEqual(held, turn)) || entryRetained.some((held) => bufferTurnsEqual(held, turn));
-      // Progress: the snapshot turns that vanished from the entry were extracted.
-      const drained = [...(claim.drained ?? [])];
-      for (const turn of claim.entry.turns) {
-        const extracted =
-          seenTurns.some((snapshot) => bufferTurnsEqual(snapshot, turn)) && !kept(turn);
-        if (!extracted) continue;
-        if (drained.some((gone) => bufferTurnsEqual(gone, turn))) continue;
-        drained.push(turn);
+      const seenActiveCounts = turnCounts(seenTurns);
+      const seenRetainedCounts = turnCounts(seenRetained);
+      const activeOutputCounts = turnCounts(entry.turns);
+      const retainedOutputCounts = turnCounts(entryRetained);
+      const matchedActiveCounts = new Map<string, number>();
+      const matchedRetainedCounts = new Map<string, number>();
+      const ambiguousIdentities = new Set<string>();
+      const identityKeys = new Set([
+        ...seenActiveCounts.keys(),
+        ...seenRetainedCounts.keys(),
+      ]);
+      const crossedCounts = new Map<string, number>();
+      for (const identity of identityKeys) {
+        const seenActive = seenActiveCounts.get(identity) ?? 0;
+        const seenRetainedCount = seenRetainedCounts.get(identity) ?? 0;
+        const activeOutput = activeOutputCounts.get(identity) ?? 0;
+        const retainedOutput = retainedOutputCounts.get(identity) ?? 0;
+        if (seenActive > 0 && seenRetainedCount > 0 && activeOutput + retainedOutput > 0) {
+          // Equal identities across source lists cannot reveal which original
+          // occurrence survived a cross-list move. Keep both source lists
+          // pending until a later progress write removes every copy.
+          matchedActiveCounts.set(identity, seenActive);
+          matchedRetainedCounts.set(identity, seenRetainedCount);
+          ambiguousIdentities.add(identity);
+          continue;
+        }
+        const matchedActive = Math.min(seenActive, activeOutput);
+        const matchedRetained = Math.min(seenRetainedCount, retainedOutput);
+        const activeMovedToRetained = Math.min(
+          seenActive - matchedActive,
+          retainedOutput - matchedRetained,
+        );
+        const retainedMovedToActive = Math.min(
+          seenRetainedCount - matchedRetained,
+          activeOutput - matchedActive,
+        );
+        matchedActiveCounts.set(identity, matchedActive + activeMovedToRetained);
+        matchedRetainedCounts.set(identity, matchedRetained + retainedMovedToActive);
+        const crossed = activeMovedToRetained + retainedMovedToActive;
+        if (crossed > 0) crossedCounts.set(identity, crossed);
+      }
+      // A pending copy that crossed lists stays tombstoned in its ORIGINAL
+      // list too once it is extracted. A copy that crosses back is home again.
+      const moved = [...(claim.movedTurns ?? [])];
+      for (const [identity, crossed] of crossedCounts) {
+        let returned = 0;
+        while (returned < crossed && removeOneByIdentity(moved, identity)) returned += 1;
+        moved.push(...takeByIdentity([...seenTurns, ...seenRetained], identity, crossed - returned));
       }
-      const drainedRetained = [...(claim.drainedRetained ?? [])];
-      for (const turn of claim.entry.retainedTurns ?? []) {
-        const extracted =
-          seenRetained.some((snapshot) => bufferTurnsEqual(snapshot, turn)) && !kept(turn);
-        if (!extracted) continue;
-        if (drained.some((gone) => bufferTurnsEqual(gone, turn)) || drainedRetained.some((gone) => bufferTurnsEqual(gone, turn))) continue;
-        drainedRetained.push(turn);
+      const extractedActive: BufferTurn[] = [];
+      appendUnmatched(seenTurns, matchedActiveCounts, extractedActive);
+      const extractedRetained: BufferTurn[] = [];
+      appendUnmatched(seenRetained, matchedRetainedCounts, extractedRetained);
+      const drained = [...(claim.drained ?? []), ...extractedActive];
+      const drainedRetained = [...(claim.drainedRetained ?? []), ...extractedRetained];
+      for (const turn of extractedActive) {
+        if (removeOneByIdentity(moved, bufferTurnIdentityKey(turn))) drainedRetained.push(turn);
       }
-      // Turns merged in after the drainer loaded stay pending, in extraction
-      // order behind the drainer's own remainder.
-      const late = claim.entry.turns.filter(
-        (turn) =>
-          !seenTurns.some((snapshot) => bufferTurnsEqual(snapshot, turn)) && !kept(turn),
-      );
-      const next: BufferEntryState = { ...entry, turns: [...entry.turns, ...late] };
-      const lateRetained = (claim.entry.retainedTurns ?? []).filter(
-        (turn) =>
-          !seenRetained.some((snapshot) => bufferTurnsEqual(snapshot, turn)) && !kept(turn),
-      );
-      if (lateRetained.length > 0) next.retainedTurns = mergeTurns(entryRetained, lateRetained);
-      await this.writeClaimBody(key, { ...claim, entry: next, drained, drainedRetained });
+      for (const turn of extractedRetained) {
+        if (removeOneByIdentity(moved, bufferTurnIdentityKey(turn))) drained.push(turn);
+      }
+      // Source occurrences of an ambiguous identity are restored BEFORE late
+      // arrivals are appended, so a late equal turn cannot stand in for them.
+      const keptTurns = [...entry.turns];
+      const keptRetained = [...entryRetained];
+      for (const identity of ambiguousIdentities) {
+        preserveSourceOccurrences(keptTurns, seenTurns, identity);
+        preserveSourceOccurrences(keptRetained, seenRetained, identity);
+      }
+      const late = subtractBufferTurns(claim.entry.turns, seenTurns);
+      const lateRetained = subtractBufferTurns(claim.entry.retainedTurns ?? [], seenRetained);
+      const next: BufferEntryState = { ...entry, turns: [...keptTurns, ...late] };
+      const nextRetained = [...keptRetained, ...lateRetained];
+      if (nextRetained.length > 0) next.retainedTurns = nextRetained;
+      await this.writeClaimBody(key, {
+        ...claim,
+        entry: next,
+        drained,
+        drainedRetained,
+        movedTurns: moved.length > 0 ? moved : undefined,
+      });
     });
   }
 
@@ -496,7 +612,7 @@ export class BufferDrainClaims {
     return await withHeldFileLock(this.lockFileFor(key), { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS }, async (acquired) => {
       if (!acquired) return "ok";
       const lease = await this.readLease(key);
-      if (!lease || lease.ownerId !== ownerId) return "lost";
+      if (!lease || !leaseBelongsToProcess(lease, ownerId)) return "lost";
       await this.writeLease(key, { ...lease, heartbeatAt: new Date().toISOString(), leaseMs });
       return "ok";
     });
@@ -504,9 +620,16 @@ export class BufferDrainClaims {
 
   /** Give the key back (content stays; the next run resumes it). */
   async releaseLease(key: string, ownerId: string): Promise<void> {
-    const lease = await this.readLease(key);
-    if (!lease || lease.ownerId !== ownerId) return;
-    await unlink(this.leaseFileFor(key)).catch(() => {});
+    await withHeldFileLock(
+      this.lockFileFor(key),
+      { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS },
+      async (acquired) => {
+        if (!acquired) return;
+        const lease = await this.readLease(key);
+        if (!leaseBelongsToProcess(lease, ownerId)) return;
+        await unlink(this.leaseFileFor(key)).catch(() => {});
+      },
+    );
   }
 
   /**
@@ -514,25 +637,48 @@ export class BufferDrainClaims {
    * extract. Non-empty claims stay (deferred content is never dropped here).
    */
   async ack(key: string, ownerId: string): Promise<AckOutcome> {
-    const lease = await this.readLease(key);
-    if (!lease || lease.ownerId !== ownerId) return "busy";
-    const claim = await this.readClaimBody(key);
-    if (!claim) {
-      await unlink(this.leaseFileFor(key)).catch(() => {});
-      return "acked";
-    }
-    if (claim.entry.turns.length > 0 || (claim.entry.retainedTurns?.length ?? 0) > 0) return "not_empty";
-    // Keep the (empty) claim file as a TOMBSTONE: a live buffer owner that
-    // still holds a stale copy subtracts the drained turns instead of
-    // writing them back. The owner consumes the tombstone on its next save.
-    await unlink(this.leaseFileFor(key)).catch(() => {});
-    return "acked";
+    return await withHeldFileLock(
+      this.lockFileFor(key),
+      { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS },
+      async (acquired) => {
+        if (!acquired) return "busy";
+        const lease = await this.readLease(key);
+        if (!leaseBelongsToProcess(lease, ownerId)) return "busy";
+        const claim = await this.readClaimBody(key);
+        if (!claim) {
+          await unlink(this.leaseFileFor(key)).catch(() => {});
+          return "acked";
+        }
+        if (claim.entry.turns.length > 0 || (claim.entry.retainedTurns?.length ?? 0) > 0) return "not_empty";
+        // Keep the empty claim as a tombstone until its live owner consumes it.
+        await unlink(this.leaseFileFor(key)).catch(() => {});
+        return "acked";
+      },
+    );
   }
 
-  /** The turns a drain already extracted for `key` (tombstone content). */
-  async drainedTurns(key: string): Promise<BufferTurn[]> {
+  /** Return extracted identities with their active/retained provenance intact. */
+  async drainedTurns(key: string): Promise<DrainedTurnSets> {
     const claim = await this.readClaimBody(key);
-    return claim?.drained ?? [];
+    return {
+      turns: claim?.drained ?? [],
+      retainedTurns: claim?.drainedRetained ?? [],
+    };
+  }
+
+  /** Return this lease owner's progress, fenced against claim takeover. */
+  async drainedTurnsForOwner(key: string, ownerId: string): Promise<DrainedTurnSets | null> {
+    return await withHeldFileLock(
+      this.lockFileFor(key),
+      { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS },
+      async (acquired) => {
+        if (!acquired) throw new Error(`buffer drain claim for ${key} is busy; cannot reconcile progress`);
+        const lease = await this.readLease(key);
+        if (!leaseBelongsToProcess(lease, ownerId)) return null;
+        const claim = await this.readClaimBody(key);
+        return claim ? { turns: claim.drained ?? [], retainedTurns: claim.drainedRetained ?? [] } : null;
+      }
+    );
   }
 
   /**

package/src/storage/buffer-session-files.ts

@@ -148,9 +148,9 @@ export class BufferSessionFiles {
         // the owner's fresh remainder back as a session file (the drained
         // turns are subtracted here too, so a caller that did not subtract
         // them cannot resurrect them) and release the tombstone.
-        const fresh: BufferEntryState = { ...entry, turns: subtractBufferTurns(entry.turns, drained) };
+        const fresh: BufferEntryState = { ...entry, turns: subtractBufferTurns(entry.turns, drained.turns) };
         if (entry.retainedTurns && entry.retainedTurns.length > 0) {
-          fresh.retainedTurns = subtractBufferTurns(entry.retainedTurns, drained);
+          fresh.retainedTurns = subtractBufferTurns(entry.retainedTurns, drained.retainedTurns);
           if (fresh.retainedTurns.length === 0) delete fresh.retainedTurns;
         }
         await this.assertDirSafe();

package/src/storage/content-hash-index.ts

@@ -99,6 +99,15 @@ export class FactHashIndexNotAuthoritativeError extends Error {
   }
 }
 
+/**
+ * One dedup lookup: whether the shared index holds the hash, and whether that
+ * answer can be trusted as a clean MISS. Both fields describe the same instant.
+ */
+export interface ContentHashLookup {
+  readonly present: boolean;
+  readonly authoritative: boolean;
+}
+
 type DiskFingerprint = {
   mtimeMs: number;
   size: number;

package/src/storage.ts

@@ -215,6 +215,7 @@ import {
   FactHashIndexNotAuthoritativeError,
   CONTENT_HASH_INDEX_RETRY_MAX_DELAY_MS,
   type ContentHashIndexLockOptions,
+  type ContentHashLookup,
 } from "./storage/content-hash-index.js";
 import {
   TombstoneBlockedCaptureIndexHost,
@@ -4172,6 +4173,20 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return await this.ensureFactHashIndexAuthoritative();
   }
 
+  /**
+   * Shared-index membership of `content` plus the authority of that answer,
+   * read in one synchronous step after the freshness check or locked rebuild.
+   * A separate probe and `isFactContentHashAuthoritative()` call can pair a
+   * stale MISS with authority from another moment, because each one may rebuild
+   * the index (#3312). Trust a MISS only when `authoritative`; otherwise
+   * confirm against the corpus.
+   */
+  async lookupContentHash(content: string): Promise<ContentHashLookup> {
+    const index = await this.getFactHashIndex();
+    await this.ensureFactHashIndexAuthoritative();
+    return { present: index.has(content), authoritative: this.factHashIndexAuthoritative === true };
+  }
+
   async writeArtifact(
     quote: string,
     options: {

package/src/transfer/capsule-gunzip.ts

@@ -0,0 +1,39 @@
+import { gunzipSync } from "node:zlib";
+
+import { isErrnoCode } from "../utils/errno.js";
+
+/**
+ * Hard cap on decompressed capsule JSON for import, merge and inspect. `gunzipSync` without
+ * `maxOutputLength` allocates whatever the stream claims, so a small
+ * highly-compressible gzip can OOM the process. 64 MiB is enough for ordinary
+ * capsules and stops classic bomb shapes at the zlib edge.
+ */
+export const CAPSULE_IMPORT_MAX_GUNZIP_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Gunzip a capsule archive buffer with a hard decompressed-size cap.
+ * `caller` is the public API name used in error messages (`importCapsule`,
+ * `mergeCapsule`, `capsule inspect`).
+ */
+export function gunzipCapsuleArchive(
+  raw: Buffer,
+  caller: string,
+  archiveAbs: string,
+): string {
+  try {
+    return gunzipSync(raw, {
+      maxOutputLength: CAPSULE_IMPORT_MAX_GUNZIP_BYTES,
+    }).toString("utf-8");
+  } catch (cause) {
+    if (isErrnoCode(cause, "ERR_BUFFER_TOO_LARGE")) {
+      throw new Error(
+        `${caller}: archive decompressed size exceeds limit of ${CAPSULE_IMPORT_MAX_GUNZIP_BYTES} bytes`,
+        cause instanceof Error ? { cause } : undefined,
+      );
+    }
+    throw new Error(
+      `${caller}: archive is not a valid gzip file: ${archiveAbs}`,
+      cause instanceof Error ? { cause } : undefined,
+    );
+  }
+}

package/src/transfer/capsule-import.test.ts

@@ -0,0 +1,73 @@
+/**
+ * capsule gunzip bounds — Finding C3 (gzip bomb / unbounded gunzip).
+ *
+ * importCapsule/mergeCapsule previously called gunzipSync with no
+ * maxOutputLength, so a small highly-compressible archive could expand into
+ * multi-gigabyte buffers. These tests pin the refusal of a real gzip-bomb
+ * shape and keep a normal capsule import green.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+
+import { makeTempDir } from "../testing/tmp-dir.js";
+import { exportCapsule } from "./capsule-export.js";
+import { CAPSULE_IMPORT_MAX_GUNZIP_BYTES } from "./capsule-gunzip.js";
+import { importCapsule } from "./capsule-import.js";
+
+async function writeFact(dir: string, id: string, body: string): Promise<void> {
+  await mkdir(path.join(dir, "facts"), { recursive: true });
+  await writeFile(
+    path.join(dir, "facts", `${id}.md`),
+    `---\nid: ${id}\n---\n${body}\n`,
+  );
+}
+
+test("importCapsule refuses a small gzip that expands past the output bound", async () => {
+  const dir = await makeTempDir("cap-gunzip-bomb-");
+  // Highly compressible payload one byte over the decompressed cap. gzip of
+  // 64 MiB of identical bytes stays ~65 KiB — a classic bomb shape.
+  const bombPayload = Buffer.alloc(CAPSULE_IMPORT_MAX_GUNZIP_BYTES + 1, 0x41);
+  const archivePath = path.join(dir, "bomb.capsule.json.gz");
+  await writeFile(archivePath, gzipSync(bombPayload));
+
+  const root = await makeTempDir("cap-gunzip-bomb-root-");
+  await assert.rejects(
+    () =>
+      importCapsule({
+        archivePath,
+        root,
+        mode: "skip",
+      }),
+    /importCapsule: archive decompressed size exceeds limit of \d+ bytes/,
+  );
+});
+
+test("importCapsule still imports a normal capsule archive", async () => {
+  const srcDir = await makeTempDir("cap-gunzip-ok-src-");
+  const dstDir = await makeTempDir("cap-gunzip-ok-dst-");
+  const outDir = await makeTempDir("cap-gunzip-ok-out-");
+
+  await writeFact(srcDir, "fact-ok", "Normal capsule fact.");
+  const exported = await exportCapsule({
+    name: "gunzip-ok-capsule",
+    root: srcDir,
+    outDir,
+    pluginVersion: "0.0.0-test",
+    now: 1_700_000_000_000,
+  });
+
+  const result = await importCapsule({
+    archivePath: exported.archivePath,
+    root: dstDir,
+    mode: "skip",
+  });
+
+  assert.equal(result.imported.length, 1);
+  assert.equal(result.skipped.length, 0);
+  const content = await readFile(path.join(dstDir, "facts", "fact-ok.md"), "utf-8");
+  assert.match(content, /Normal capsule fact\./);
+});

package/src/transfer/capsule-import.ts

@@ -1,7 +1,6 @@
 import { lstat, mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { gunzipSync } from "node:zlib";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import {
   HistoricalEntityCanonicalIdCache,
@@ -31,6 +30,7 @@ import {
   type ExportMemoryRecordV1,
 } from "./types.js";
 import { isEncryptedCapsuleFile, decryptCapsuleFileInMemory } from "./capsule-crypto.js";
+import { gunzipCapsuleArchive } from "./capsule-gunzip.js";
 
 /**
  * Conflict-resolution mode for {@link importCapsule}. Inverse of the
@@ -197,7 +197,7 @@ export async function importCapsule(
   } else {
     raw = await readFile(archiveAbs);
   }
-  const json = gunzipSync(raw).toString("utf-8");
+  const json = gunzipCapsuleArchive(raw, "importCapsule", archiveAbs);
   let parsedJson: unknown;
   try {
     parsedJson = JSON.parse(json);

package/src/transfer/capsule-merge.test.ts

@@ -0,0 +1,34 @@
+/**
+ * capsule-merge gunzip bounds — Finding C3 companion to capsule-import.test.ts.
+ *
+ * mergeCapsule reads the same gzip archive shape as importCapsule; the shared
+ * helper must refuse a real bomb with a clear oversize error.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+
+import { makeTempDir } from "../testing/tmp-dir.js";
+import { CAPSULE_IMPORT_MAX_GUNZIP_BYTES } from "./capsule-gunzip.js";
+import { mergeCapsule } from "./capsule-merge.js";
+
+test("mergeCapsule refuses a small gzip that expands past the output bound", async () => {
+  const dir = await makeTempDir("cap-merge-gunzip-bomb-");
+  const bombPayload = Buffer.alloc(CAPSULE_IMPORT_MAX_GUNZIP_BYTES + 1, 0x41);
+  const archivePath = path.join(dir, "bomb.capsule.json.gz");
+  await writeFile(archivePath, gzipSync(bombPayload));
+
+  const root = await makeTempDir("cap-merge-gunzip-bomb-root-");
+  await assert.rejects(
+    () =>
+      mergeCapsule({
+        sourceArchive: archivePath,
+        targetRoot: root,
+        conflictMode: "skip-conflicts",
+      }),
+    /mergeCapsule: archive decompressed size exceeds limit of \d+ bytes/,
+  );
+});