@peac/capture-node 0.10.12

package/dist/index.cjs

@@ -0,0 +1,864 @@
+'use strict';
+
+var fs2 = require('fs/promises');
+var path = require('path');
+var captureCore = require('@peac/capture-core');
+var os = require('os');
+var fs = require('fs');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var fs2__namespace = /*#__PURE__*/_interopNamespace(fs2);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
+
+// src/fs-spool-store.ts
+
+// src/errors.ts
+var SpoolFullError = class extends Error {
+  constructor(current, max, unit) {
+    super(`Spool full: ${current}/${max} ${unit}`);
+    this.current = current;
+    this.max = max;
+    this.unit = unit;
+    this.name = "SpoolFullError";
+  }
+  code = "E_SPOOL_FULL";
+};
+var SpoolCorruptError = class extends Error {
+  constructor(reason, corruptAtSequence, details) {
+    super(
+      `Spool corrupt: ${reason}` + (corruptAtSequence !== void 0 ? ` at sequence ${corruptAtSequence}` : "") + (details ? ` -- ${details}` : "")
+    );
+    this.reason = reason;
+    this.corruptAtSequence = corruptAtSequence;
+    this.details = details;
+    this.name = "SpoolCorruptError";
+  }
+  code = "E_SPOOL_CORRUPT";
+};
+var LockfileError = class extends Error {
+  constructor(lockPath, holderPid) {
+    const pidInfo = holderPid !== void 0 ? ` PID: ${holderPid}.` : "";
+    super(
+      `Another PEAC instance holds the lock.${pidInfo} If stale, delete ${lockPath} or set allowStaleLockBreak: true`
+    );
+    this.lockPath = lockPath;
+    this.holderPid = holderPid;
+    this.name = "LockfileError";
+  }
+  code = "E_LOCKFILE";
+};
+async function acquireLock(filePath, options) {
+  const lockPath = filePath + ".lock";
+  const allowStaleBreak = options?.allowStaleLockBreak ?? false;
+  const staleMaxAge = options?.staleLockMaxAgeMs ?? 36e5;
+  const payload = {
+    pid: process.pid,
+    startTime: Date.now(),
+    hostname: getHostname(),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  try {
+    await fs2__namespace.writeFile(lockPath, JSON.stringify(payload, null, 2) + "\n", {
+      flag: "wx",
+      mode: 420
+    });
+  } catch (err) {
+    if (!isEnoent(err) && isEexist(err)) {
+      if (allowStaleBreak) {
+        const broke = await tryBreakStaleLock(lockPath, staleMaxAge);
+        if (broke) {
+          try {
+            await fs2__namespace.writeFile(lockPath, JSON.stringify(payload, null, 2) + "\n", {
+              flag: "wx",
+              mode: 420
+            });
+          } catch (retryErr) {
+            if (isEexist(retryErr)) {
+              const holder = await readLockHolder(lockPath);
+              throw new LockfileError(lockPath, holder?.pid);
+            }
+            throw retryErr;
+          }
+        } else {
+          const holder = await readLockHolder(lockPath);
+          throw new LockfileError(lockPath, holder?.pid);
+        }
+      } else {
+        const holder = await readLockHolder(lockPath);
+        throw new LockfileError(lockPath, holder?.pid);
+      }
+    } else {
+      throw err;
+    }
+  }
+  let released = false;
+  return {
+    lockPath,
+    async release() {
+      if (released) return;
+      released = true;
+      try {
+        await fs2__namespace.unlink(lockPath);
+      } catch {
+      }
+    }
+  };
+}
+async function readLockHolder(lockPath) {
+  try {
+    const content = await fs2__namespace.readFile(lockPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+async function tryBreakStaleLock(lockPath, maxAgeMs) {
+  try {
+    const stat3 = await fs2__namespace.stat(lockPath);
+    const ageMs = Date.now() - stat3.mtimeMs;
+    if (ageMs > maxAgeMs) {
+      await fs2__namespace.unlink(lockPath);
+      return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+function getHostname() {
+  try {
+    return os.hostname();
+  } catch {
+    return "unknown";
+  }
+}
+function isEexist(err) {
+  return err?.code === "EEXIST";
+}
+function isEnoent(err) {
+  return err?.code === "ENOENT";
+}
+function stripTrailingCR(buf) {
+  if (buf.length > 0 && buf[buf.length - 1] === 13) {
+    return buf.subarray(0, buf.length - 1);
+  }
+  return buf;
+}
+async function* streamLines(options) {
+  const { filePath, maxLineBytes, highWaterMark = 64 * 1024 } = options;
+  const stream = fs.createReadStream(filePath, { highWaterMark });
+  let chunks = [];
+  let accumulatedBytes = 0;
+  let lineStartOffset = 0;
+  let fileOffset = 0;
+  let lineTooLarge = false;
+  try {
+    for await (const rawChunk of stream) {
+      const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+      let chunkOffset = 0;
+      while (chunkOffset < chunk.length) {
+        const newlineIndex = chunk.indexOf(10, chunkOffset);
+        if (newlineIndex === -1) {
+          const remainder = chunk.subarray(chunkOffset);
+          accumulatedBytes += remainder.length;
+          if (accumulatedBytes > maxLineBytes) {
+            if (!lineTooLarge) {
+              chunks = [];
+              lineTooLarge = true;
+            }
+            accumulatedBytes = maxLineBytes + 1;
+          } else {
+            chunks.push(Buffer.from(remainder));
+          }
+          fileOffset += remainder.length;
+          chunkOffset = chunk.length;
+        } else {
+          const segment = chunk.subarray(chunkOffset, newlineIndex);
+          const segmentLength = segment.length;
+          accumulatedBytes += segmentLength;
+          if (lineTooLarge || accumulatedBytes > maxLineBytes) {
+            yield {
+              kind: "line_too_large",
+              byteOffset: lineStartOffset,
+              accumulatedBytes: lineTooLarge ? maxLineBytes + 1 : accumulatedBytes
+            };
+          } else {
+            chunks.push(Buffer.from(segment));
+            let lineBuffer = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+            lineBuffer = stripTrailingCR(lineBuffer);
+            const line = lineBuffer.toString("utf-8");
+            yield {
+              kind: "line",
+              line,
+              byteOffset: lineStartOffset,
+              byteLength: accumulatedBytes
+            };
+          }
+          fileOffset += segmentLength + 1;
+          lineStartOffset = fileOffset;
+          chunks = [];
+          accumulatedBytes = 0;
+          lineTooLarge = false;
+          chunkOffset = newlineIndex + 1;
+        }
+      }
+    }
+    if (accumulatedBytes > 0) {
+      if (lineTooLarge || accumulatedBytes > maxLineBytes) {
+        yield {
+          kind: "line_too_large",
+          byteOffset: lineStartOffset,
+          accumulatedBytes: lineTooLarge ? maxLineBytes + 1 : accumulatedBytes
+        };
+      } else {
+        let lineBuffer = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+        lineBuffer = stripTrailingCR(lineBuffer);
+        const line = lineBuffer.toString("utf-8");
+        yield {
+          kind: "incomplete_tail",
+          line,
+          byteOffset: lineStartOffset,
+          byteLength: accumulatedBytes
+        };
+      }
+    }
+  } finally {
+    stream.destroy();
+  }
+}
+async function truncateFile(filePath, byteOffset) {
+  const { truncate } = await import('fs/promises');
+  await truncate(filePath, byteOffset);
+}
+
+// src/fs-spool-store.ts
+var META_VERSION = 1;
+var DEFAULT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+async function createFsSpoolStore(options) {
+  const store = new FsSpoolStore(options);
+  await store.init();
+  return store;
+}
+function getFsSpoolDiagnostics(store) {
+  if (store !== null && typeof store === "object" && "diagnostics" in store && typeof store.diagnostics === "function") {
+    return store.diagnostics();
+  }
+  return void 0;
+}
+var FsSpoolStore = class {
+  filePath;
+  metaPath;
+  maxEntries;
+  maxFileBytes;
+  maxLineBytes;
+  autoCommitIntervalMs;
+  lockOptions;
+  onWarning;
+  // In-memory state (loaded on init, updated on append)
+  sequence = 0;
+  headDigest = captureCore.GENESIS_DIGEST;
+  entryCount = 0;
+  fileBytes = 0;
+  // File handle for appending
+  fd = null;
+  lock = null;
+  closed = false;
+  corrupt = false;
+  corruptReason;
+  corruptAtSequence;
+  firstCreate = false;
+  // Auto-commit
+  dirty = false;
+  autoCommitTimer = null;
+  constructor(options) {
+    this.filePath = options.filePath;
+    this.metaPath = options.filePath + ".meta.json";
+    this.maxEntries = options.maxEntries ?? 1e5;
+    this.maxFileBytes = options.maxFileBytes ?? 100 * 1024 * 1024;
+    this.maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+    this.autoCommitIntervalMs = options.autoCommitIntervalMs ?? 5e3;
+    this.lockOptions = options.lockOptions;
+    this.onWarning = options.onWarning ?? (() => {
+    });
+  }
+  /**
+   * Initialize: acquire lock, load or recover state, open file handle.
+   */
+  async init() {
+    const dirPath = path__namespace.dirname(this.filePath);
+    await fs2__namespace.mkdir(dirPath, { recursive: true });
+    this.lock = await acquireLock(this.filePath, this.lockOptions);
+    try {
+      let fileExists;
+      try {
+        await fs2__namespace.access(this.filePath);
+        fileExists = true;
+      } catch {
+        fileExists = false;
+      }
+      this.firstCreate = !fileExists;
+      const metaLoaded = fileExists && await this.tryLoadMeta();
+      if (!metaLoaded && fileExists) {
+        await this.fullScan();
+      }
+      this.fd = await fs2__namespace.open(this.filePath, "a");
+      if (this.autoCommitIntervalMs > 0) {
+        this.autoCommitTimer = setInterval(() => {
+          if (this.dirty && !this.closed) {
+            this.commit().catch((err) => {
+              this.onWarning(`Auto-commit failed: ${String(err)}`);
+            });
+          }
+        }, this.autoCommitIntervalMs);
+        if (typeof this.autoCommitTimer === "object" && "unref" in this.autoCommitTimer) {
+          this.autoCommitTimer.unref();
+        }
+      }
+    } catch (err) {
+      await this.lock.release();
+      this.lock = null;
+      throw err;
+    }
+  }
+  // ===========================================================================
+  // SpoolStore Interface
+  // ===========================================================================
+  async append(entry) {
+    this.assertWritable();
+    if (this.entryCount >= this.maxEntries) {
+      throw new SpoolFullError(this.entryCount, this.maxEntries, "entries");
+    }
+    const line = JSON.stringify(entry) + "\n";
+    const lineBytes = Buffer.byteLength(line, "utf-8");
+    if (this.fileBytes + lineBytes > this.maxFileBytes) {
+      throw new SpoolFullError(this.fileBytes, this.maxFileBytes, "bytes");
+    }
+    if (entry.prev_entry_digest !== this.headDigest) {
+      throw new Error(
+        `Invalid chain: expected prev_entry_digest ${this.headDigest}, got ${entry.prev_entry_digest}`
+      );
+    }
+    if (entry.sequence !== this.sequence + 1) {
+      throw new Error(`Invalid sequence: expected ${this.sequence + 1}, got ${entry.sequence}`);
+    }
+    await this.fd.write(line, null, "utf-8");
+    this.headDigest = entry.entry_digest;
+    this.sequence = entry.sequence;
+    this.entryCount++;
+    this.fileBytes += lineBytes;
+    this.dirty = true;
+    return entry.sequence;
+  }
+  async commit() {
+    this.assertNotClosed();
+    if (!this.dirty || !this.fd) return;
+    await this.fd.sync();
+    this.dirty = false;
+    if (this.firstCreate) {
+      this.firstCreate = false;
+      await this.fsyncDir().catch((err) => {
+        this.onWarning(`Directory fsync failed (non-critical): ${String(err)}`);
+      });
+    }
+    await this.writeMeta().catch((err) => {
+      this.onWarning(`Meta file write failed: ${String(err)}`);
+    });
+  }
+  async read(fromSequence, limit) {
+    this.assertNotClosed();
+    const entries = [];
+    const effectiveLimit = limit !== void 0 && limit > 0 ? limit : Infinity;
+    for await (const result of streamLines({
+      filePath: this.filePath,
+      maxLineBytes: this.maxLineBytes
+    })) {
+      if (result.kind === "line_too_large") {
+        this.onWarning(
+          `Line at byte offset ${result.byteOffset} exceeds maxLineBytes (${result.accumulatedBytes}/${this.maxLineBytes}) -- marking corrupt`
+        );
+        this.setCorrupt("LINE_TOO_LARGE", this.sequence);
+        break;
+      }
+      if (!result.line.trim()) continue;
+      let entry;
+      try {
+        entry = JSON.parse(result.line);
+      } catch {
+        continue;
+      }
+      if (entry.sequence >= fromSequence) {
+        entries.push(entry);
+        if (entries.length >= effectiveLimit) {
+          break;
+        }
+      }
+    }
+    return entries;
+  }
+  async getHeadDigest() {
+    this.assertNotClosed();
+    return this.headDigest;
+  }
+  async getSequence() {
+    this.assertNotClosed();
+    return this.sequence;
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.autoCommitTimer !== null) {
+      clearInterval(this.autoCommitTimer);
+      this.autoCommitTimer = null;
+    }
+    if (this.fd) {
+      if (this.dirty) {
+        try {
+          await this.fd.sync();
+          this.dirty = false;
+          await this.writeMeta().catch(() => {
+          });
+        } catch {
+        }
+      }
+      await this.fd.close();
+      this.fd = null;
+    }
+    if (this.lock) {
+      await this.lock.release();
+      this.lock = null;
+    }
+  }
+  // ===========================================================================
+  // Diagnostics (P0-7: queryable without parsing error strings)
+  // ===========================================================================
+  /**
+   * Get a diagnostic snapshot for operator tooling.
+   *
+   * Use `getFsSpoolDiagnostics(store)` if you have a generic SpoolStore
+   * reference and need to probe for this method via type guard.
+   */
+  diagnostics() {
+    const full = this.entryCount >= this.maxEntries || this.fileBytes >= this.maxFileBytes;
+    return {
+      mode: full || this.corrupt ? "read_only" : "active",
+      spoolFull: full,
+      spoolCorrupt: this.corrupt,
+      corruptReason: this.corruptReason,
+      corruptAtSequence: this.corruptAtSequence,
+      entryCount: this.entryCount,
+      fileBytes: this.fileBytes,
+      maxEntries: this.maxEntries,
+      maxFileBytes: this.maxFileBytes,
+      filePath: this.filePath
+    };
+  }
+  /** Whether the spool has reached its hard-cap limit. */
+  get isFull() {
+    return this.entryCount >= this.maxEntries || this.fileBytes >= this.maxFileBytes;
+  }
+  /** Whether linkage corruption was detected on load. */
+  get isCorrupt() {
+    return this.corrupt;
+  }
+  /** Current entry count. */
+  get currentEntryCount() {
+    return this.entryCount;
+  }
+  /** Current file size in bytes. */
+  get currentFileBytes() {
+    return this.fileBytes;
+  }
+  /** Configured max entries. */
+  get maxEntryLimit() {
+    return this.maxEntries;
+  }
+  /** Configured max file bytes. */
+  get maxBytesLimit() {
+    return this.maxFileBytes;
+  }
+  // ===========================================================================
+  // Initialization Internals
+  // ===========================================================================
+  /**
+   * Try to load state from meta file (fast path).
+   * Returns true if meta was valid and loaded.
+   */
+  async tryLoadMeta() {
+    try {
+      let metaContent;
+      try {
+        metaContent = await fs2__namespace.readFile(this.metaPath, "utf-8");
+      } catch {
+        const legacyMetaPath = this.filePath.replace(/\.jsonl$/, ".meta.json");
+        if (legacyMetaPath !== this.metaPath) {
+          try {
+            metaContent = await fs2__namespace.readFile(legacyMetaPath, "utf-8");
+          } catch {
+            return false;
+          }
+        } else {
+          return false;
+        }
+      }
+      const fileStat = await fs2__namespace.stat(this.filePath);
+      const meta = JSON.parse(metaContent);
+      if (meta.metaVersion !== META_VERSION) {
+        this.onWarning(
+          `Meta file version mismatch (expected ${META_VERSION}, got ${meta.metaVersion}) -- falling back to full scan`
+        );
+        return false;
+      }
+      if (meta.fileBytes !== fileStat.size || meta.mtimeMs !== fileStat.mtimeMs) {
+        this.onWarning(
+          `Meta file mismatch (fileBytes: ${meta.fileBytes}/${fileStat.size}, mtimeMs: ${meta.mtimeMs}/${fileStat.mtimeMs}) -- falling back to full scan`
+        );
+        return false;
+      }
+      this.sequence = meta.sequence;
+      this.headDigest = meta.headDigest;
+      this.entryCount = meta.entryCount;
+      this.fileBytes = meta.fileBytes;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Full JSONL scan: stream line by line, verify linkage, recover from crash.
+   *
+   * Uses the custom streaming line parser (streamLines) which enforces
+   * maxLineBytes BEFORE materializing the line as a JS string. This prevents
+   * memory blowup from a single giant line -- the primary "local file DoS" vector.
+   *
+   * Crash recovery rules:
+   * - Incomplete last line (no trailing newline + invalid JSON): truncate tail only.
+   * - Invalid JSON mid-file (before the last line): mark spool_corrupt, do NOT auto-repair.
+   *   Auto-repair mid-file would mask real tampering.
+   */
+  async fullScan() {
+    let prevDigest = captureCore.GENESIS_DIGEST;
+    let shouldTruncateAt;
+    let lineNumber = 0;
+    for await (const result of streamLines({
+      filePath: this.filePath,
+      maxLineBytes: this.maxLineBytes
+    })) {
+      lineNumber++;
+      if (result.kind === "line_too_large") {
+        this.onWarning(
+          `Line ${lineNumber} exceeds maxLineBytes (${result.accumulatedBytes}/${this.maxLineBytes}) -- marking spool corrupt`
+        );
+        this.setCorrupt("LINE_TOO_LARGE", this.sequence);
+        break;
+      }
+      const lineStr = result.line;
+      if (!lineStr.trim()) continue;
+      let entry;
+      try {
+        entry = JSON.parse(lineStr);
+      } catch {
+        if (result.kind === "incomplete_tail") {
+          this.onWarning(
+            `Incomplete last line detected (${result.byteLength} bytes) -- truncating`
+          );
+          shouldTruncateAt = result.byteOffset;
+        } else {
+          this.onWarning(`Malformed JSON at line ${lineNumber} -- marking spool corrupt`);
+          this.setCorrupt("MALFORMED_JSON", this.sequence);
+        }
+        break;
+      }
+      if (entry.prev_entry_digest !== prevDigest) {
+        this.onWarning(
+          `Chain linkage broken at sequence ${entry.sequence}: expected ${prevDigest}, got ${entry.prev_entry_digest}`
+        );
+        this.setCorrupt("CHAIN_BROKEN", entry.sequence);
+        break;
+      }
+      prevDigest = entry.entry_digest;
+      this.sequence = entry.sequence;
+      this.headDigest = entry.entry_digest;
+      this.entryCount++;
+    }
+    if (shouldTruncateAt !== void 0 && !this.corrupt) {
+      await truncateFile(this.filePath, shouldTruncateAt);
+    }
+    try {
+      const stat3 = await fs2__namespace.stat(this.filePath);
+      this.fileBytes = stat3.size;
+    } catch {
+      this.fileBytes = 0;
+    }
+  }
+  /**
+   * Write meta file for fast startup.
+   */
+  async writeMeta() {
+    const stat3 = await fs2__namespace.stat(this.filePath);
+    const meta = {
+      metaVersion: META_VERSION,
+      sequence: this.sequence,
+      headDigest: this.headDigest,
+      entryCount: this.entryCount,
+      fileBytes: stat3.size,
+      mtimeMs: stat3.mtimeMs
+    };
+    const tmpPath = this.metaPath + ".tmp";
+    await fs2__namespace.writeFile(tmpPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
+    await fs2__namespace.rename(tmpPath, this.metaPath);
+  }
+  /**
+   * fsync the parent directory for directory entry durability on first creation.
+   * Best-effort: not all platforms support this (e.g. Windows).
+   */
+  async fsyncDir() {
+    const dirPath = path__namespace.dirname(this.filePath);
+    const dirFd = await fs2__namespace.open(dirPath, "r");
+    try {
+      await dirFd.sync();
+    } finally {
+      await dirFd.close();
+    }
+  }
+  // ===========================================================================
+  // Guards
+  // ===========================================================================
+  /**
+   * Mark the spool as corrupt with a specific reason.
+   */
+  setCorrupt(reason, atSequence) {
+    this.corrupt = true;
+    this.corruptReason = reason;
+    this.corruptAtSequence = atSequence;
+  }
+  assertNotClosed() {
+    if (this.closed) {
+      throw new Error("FsSpoolStore is closed");
+    }
+  }
+  assertWritable() {
+    this.assertNotClosed();
+    if (this.corrupt) {
+      throw new SpoolCorruptError(this.corruptReason ?? "CHAIN_BROKEN", this.corruptAtSequence);
+    }
+  }
+};
+async function createFsDedupeIndex(options) {
+  const index = new FsDedupeIndex(options);
+  await index.init();
+  return index;
+}
+var FsDedupeIndex = class {
+  filePath;
+  entries = /* @__PURE__ */ new Map();
+  fd = null;
+  closed = false;
+  firstCreate = false;
+  constructor(options) {
+    this.filePath = options.filePath;
+  }
+  /**
+   * Initialize: load existing entries from file.
+   */
+  async init() {
+    await fs2__namespace.mkdir(path__namespace.dirname(this.filePath), { recursive: true });
+    try {
+      await fs2__namespace.access(this.filePath);
+      this.firstCreate = false;
+    } catch {
+      this.firstCreate = true;
+    }
+    await this.loadFromFile();
+    this.fd = await fs2__namespace.open(this.filePath, "a");
+  }
+  // ===========================================================================
+  // DedupeIndex Interface
+  // ===========================================================================
+  async get(actionId) {
+    this.assertNotClosed();
+    return this.entries.get(actionId);
+  }
+  async set(actionId, entry) {
+    this.assertNotClosed();
+    this.entries.set(actionId, { ...entry });
+    await this.appendOp({ op: "set", actionId, entry });
+  }
+  async has(actionId) {
+    this.assertNotClosed();
+    return this.entries.has(actionId);
+  }
+  async markEmitted(actionId) {
+    this.assertNotClosed();
+    const entry = this.entries.get(actionId);
+    if (!entry) return false;
+    entry.emitted = true;
+    await this.appendOp({ op: "emit", actionId });
+    return true;
+  }
+  async delete(actionId) {
+    this.assertNotClosed();
+    const existed = this.entries.delete(actionId);
+    if (existed) {
+      await this.appendOp({ op: "delete", actionId });
+    }
+    return existed;
+  }
+  async size() {
+    this.assertNotClosed();
+    return this.entries.size;
+  }
+  async clear() {
+    this.assertNotClosed();
+    this.entries.clear();
+    if (this.fd) {
+      await this.fd.close();
+    }
+    await fs2__namespace.writeFile(this.filePath, "", "utf-8");
+    this.fd = await fs2__namespace.open(this.filePath, "a");
+  }
+  // ===========================================================================
+  // Extra: commit() -- not on DedupeIndex interface
+  //
+  // Callers use type guard:
+  //   if ('commit' in dedupe && typeof dedupe.commit === 'function')
+  //     await dedupe.commit();
+  // ===========================================================================
+  /**
+   * Flush pending writes to durable storage.
+   *
+   * Not part of the DedupeIndex interface (capture-core stays stable).
+   * Callers use type guard to detect this method on the concrete type.
+   */
+  async commit() {
+    this.assertNotClosed();
+    if (this.fd) {
+      await this.fd.sync();
+    }
+    if (this.firstCreate) {
+      this.firstCreate = false;
+      await this.fsyncDir().catch(() => {
+      });
+    }
+  }
+  // ===========================================================================
+  // Close
+  // ===========================================================================
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.fd) {
+      try {
+        await this.fd.sync();
+      } catch {
+      }
+      await this.fd.close();
+      this.fd = null;
+    }
+  }
+  // ===========================================================================
+  // Internals
+  // ===========================================================================
+  /**
+   * Load entries from the dedupe file.
+   * Last-write-wins for duplicate actionIds (handles crash replay).
+   */
+  async loadFromFile() {
+    let content;
+    try {
+      content = await fs2__namespace.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        return;
+      }
+      throw err;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let op;
+      try {
+        op = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      switch (op.op) {
+        case "set":
+          if (op.actionId && op.entry) {
+            this.entries.set(op.actionId, op.entry);
+          }
+          break;
+        case "emit":
+          if (op.actionId) {
+            const entry = this.entries.get(op.actionId);
+            if (entry) {
+              entry.emitted = true;
+            }
+          }
+          break;
+        case "delete":
+          if (op.actionId) {
+            this.entries.delete(op.actionId);
+          }
+          break;
+        case "clear":
+          this.entries.clear();
+          break;
+      }
+    }
+  }
+  /**
+   * Append an operation to the dedupe file (no fsync).
+   */
+  async appendOp(op) {
+    if (!this.fd) return;
+    const line = JSON.stringify(op) + "\n";
+    await this.fd.write(line, null, "utf-8");
+  }
+  /**
+   * fsync the parent directory for directory entry durability on first creation.
+   * Best-effort: not all platforms support this (e.g. Windows).
+   */
+  async fsyncDir() {
+    const dirPath = path__namespace.dirname(this.filePath);
+    const dirFd = await fs2__namespace.open(dirPath, "r");
+    try {
+      await dirFd.sync();
+    } finally {
+      await dirFd.close();
+    }
+  }
+  assertNotClosed() {
+    if (this.closed) {
+      throw new Error("FsDedupeIndex is closed");
+    }
+  }
+};
+
+exports.FsDedupeIndex = FsDedupeIndex;
+exports.FsSpoolStore = FsSpoolStore;
+exports.LockfileError = LockfileError;
+exports.SpoolCorruptError = SpoolCorruptError;
+exports.SpoolFullError = SpoolFullError;
+exports.acquireLock = acquireLock;
+exports.createFsDedupeIndex = createFsDedupeIndex;
+exports.createFsSpoolStore = createFsSpoolStore;
+exports.getFsSpoolDiagnostics = getFsSpoolDiagnostics;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map