@remnic/core 10.0.59 → 10.0.61

package/dist/chunk-JCL7RO2G.js

@@ -0,0 +1,674 @@
+import {
+  bufferTurnsEqual,
+  subtractBufferTurns
+} from "./chunk-U7MIMS2Y.js";
+import {
+  withHeldFileLock
+} from "./chunk-EBRG7ZIK.js";
+import {
+  SecureStoreDecryptError,
+  SecureStoreLockedError
+} from "./chunk-EYGOM6AI.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/storage/buffer-drain-claims.ts
+import { hostname } from "os";
+import { z } from "zod";
+import { existsSync } from "fs";
+import { mkdir, readdir as readdir2, rename, unlink as unlink2, writeFile } from "fs/promises";
+import path2 from "path";
+
+// src/storage/buffer-session-files.ts
+import { createHash } from "crypto";
+import { lstat, readdir, unlink } from "fs/promises";
+import path from "path";
+function isMissing(err) {
+  return err?.code === "ENOENT";
+}
+function asFsError(err) {
+  return err;
+}
+function bufferSessionFileName(key) {
+  return `s-${createHash("sha256").update(key).digest("hex")}.json`;
+}
+function legacyStateToEntries(state) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(state.entries ?? {})) {
+    if (value && Array.isArray(value.turns)) entries.set(key, value);
+  }
+  if (!entries.has("default")) {
+    entries.set("default", {
+      turns: Array.isArray(state.turns) ? state.turns : [],
+      lastExtractionAt: state.lastExtractionAt ?? null,
+      extractionCount: Number.isFinite(state.extractionCount) ? state.extractionCount : 0
+    });
+  }
+  return entries;
+}
+function entryFromBody(body) {
+  if (!body || !Array.isArray(body.turns) || (body.key?.length ?? 0) === 0) return null;
+  const entry = {
+    turns: body.turns,
+    lastExtractionAt: body.lastExtractionAt ?? null,
+    extractionCount: Number.isFinite(body.extractionCount) ? Number(body.extractionCount) : 0
+  };
+  if (Array.isArray(body.retainedTurns)) entry.retainedTurns = body.retainedTurns;
+  return { key: String(body.key), entry };
+}
+var BufferSessionFiles = class {
+  constructor(stateDir, io) {
+    this.stateDir = stateDir;
+    this.io = io;
+    this.claimsStore = new BufferDrainClaims(stateDir, io);
+  }
+  stateDir;
+  io;
+  dirVerified = false;
+  claimsStore;
+  /** The drain-claim store for this state dir (CLI scan + claim ops). */
+  get claims() {
+    return this.claimsStore;
+  }
+  /** Sync gate check: is this session claimed by a buffer drain? */
+  isClaimed(key) {
+    return this.claimsStore.isClaimed(key);
+  }
+  get dir() {
+    return path.join(this.stateDir, "buffer");
+  }
+  fileFor(key) {
+    return path.join(this.dir, bufferSessionFileName(key));
+  }
+  /**
+   * Refuse a symlinked buffer directory: following it would send buffered
+   * conversation data (and deletions) outside the memory root. One lstat of
+   * one directory, cached after it passes, so the observe path pays nothing
+   * per write; the cache is dropped on any failure.
+   */
+  async assertDirSafe() {
+    if (this.dirVerified) return;
+    let stat = null;
+    try {
+      stat = await lstat(this.dir);
+    } catch (err) {
+      if (!(err instanceof Error) || !isMissing(asFsError(err))) throw err;
+    }
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+      throw new Error(`buffer session directory must be a real directory, not a symlink or file: ${this.dir}`);
+    }
+    this.dirVerified = stat !== null;
+  }
+  /** Persist ONE session atomically. Compact JSON: machine-read state, and
+   * pretty-printing a large buffer costs CPU and bytes on every observe.
+   * A drain-claimed session is handed over instead (see class doc). */
+  async save(key, entry) {
+    if (this.isClaimed(key)) {
+      if (await this.claimsStore.isDrained(key)) {
+        const drained = await this.claimsStore.drainedTurns(key);
+        const fresh = { ...entry, turns: subtractBufferTurns(entry.turns, drained) };
+        if (entry.retainedTurns && entry.retainedTurns.length > 0) {
+          fresh.retainedTurns = subtractBufferTurns(entry.retainedTurns, drained);
+          if (fresh.retainedTurns.length === 0) delete fresh.retainedTurns;
+        }
+        await this.assertDirSafe();
+        await this.io.write(this.fileFor(key), JSON.stringify({ key, ...fresh }));
+        await this.claimsStore.release(key);
+        return { status: "saved", drainedTurns: drained };
+      }
+      await this.claimsStore.mergeIntoClaim(key, entry);
+      return { status: "handed_over" };
+    }
+    await this.assertDirSafe();
+    await this.io.write(this.fileFor(key), JSON.stringify({ key, ...entry }));
+    return { status: "saved" };
+  }
+  /** Remove one session's file. Idempotent: an absent file is fine. */
+  async remove(key) {
+    await this.assertDirSafe();
+    try {
+      await unlink(this.fileFor(key));
+    } catch (err) {
+      if (!(err instanceof Error) || !isMissing(asFsError(err))) throw err;
+    }
+  }
+  async listFiles() {
+    await this.assertDirSafe();
+    try {
+      const dirents = await readdir(this.dir, { withFileTypes: true });
+      return dirents.filter((d) => d.isFile() && d.name.endsWith(".json")).map((d) => d.name);
+    } catch (err) {
+      if (err instanceof Error && isMissing(asFsError(err))) return [];
+      throw err;
+    }
+  }
+  /** Read every per-session file. Corrupt files are skipped (and logged) so
+   * one bad file cannot nuke the other sessions' buffered turns. */
+  async readAll() {
+    const names = await this.listFiles();
+    const entries = /* @__PURE__ */ new Map();
+    for (const name of names) {
+      try {
+        const body = JSON.parse(await this.io.read(path.join(this.dir, name)));
+        const parsed = entryFromBody(body);
+        if (!parsed) throw new Error("invalid buffer session file shape");
+        if (entries.has(parsed.key)) {
+          log.warn(`buffer: duplicate session file for key ${parsed.key} (${name}); keeping the first`);
+          continue;
+        }
+        entries.set(parsed.key, parsed.entry);
+      } catch (err) {
+        if (err instanceof SecureStoreLockedError || err instanceof SecureStoreDecryptError) throw err;
+        log.warn(`buffer: skipping unreadable per-session buffer file ${name}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return { entries, fileCount: names.length };
+  }
+  /**
+   * Read the legacy single-file buffer.json for migration. Null when absent,
+   * or unreadable while session files exist (they are authoritative; a
+   * corrupt leftover must not block startup). With no session files a corrupt
+   * legacy file THROWS, preserving the old contract so callers can reset it.
+   */
+  async readLegacy(hasSessionFiles) {
+    let raw;
+    try {
+      raw = await this.io.read(path.join(this.stateDir, "buffer.json"));
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (err instanceof Error && isMissing(asFsError(err))) return null;
+      throw err;
+    }
+    try {
+      const legacy = JSON.parse(raw);
+      return legacy;
+    } catch (err) {
+      if (!hasSessionFiles) throw err;
+      log.warn(
+        `buffer: legacy buffer.json is unreadable but per-session buffer files exist; ignoring the legacy file (${err instanceof Error ? err.message : String(err)})`
+      );
+      return null;
+    }
+  }
+  /**
+   * Load the whole buffer, migrating a legacy buffer.json once. A per-session
+   * file that parsed wins over the legacy snapshot (a crash mid-migration
+   * leaves exactly that pair); legacy entries without a usable file are
+   * written out, then the legacy file is retired. Both steps are idempotent.
+   */
+  async load() {
+    const { entries, fileCount } = await this.readAll();
+    const legacy = await this.readLegacy(fileCount > 0);
+    if (legacy !== null) {
+      for (const [key, entry] of legacyStateToEntries(legacy)) {
+        if (entries.has(key)) continue;
+        entries.set(key, entry);
+        await this.save(key, entry);
+      }
+      try {
+        await unlink(path.join(this.stateDir, "buffer.json"));
+      } catch (err) {
+        if (!(err instanceof Error) || !isMissing(asFsError(err))) throw err;
+      }
+    }
+    const out = /* @__PURE__ */ Object.create(null);
+    for (const [key, entry] of entries) out[key] = entry;
+    const def = entries.get("default");
+    return {
+      turns: def?.turns ?? [],
+      lastExtractionAt: def?.lastExtractionAt ?? null,
+      extractionCount: def?.extractionCount ?? 0,
+      entries: out
+    };
+  }
+  /**
+   * Reconcile the files with a WHOLE buffer state: write every entry, then
+   * delete files for keys no longer present. Writes first, deletes last: a
+   * crash leaves stale extra files (removed by the next reconcile) but never
+   * loses sessions the state says exist. Not on the observe hot path.
+   */
+  async reconcile(state) {
+    const entries = legacyStateToEntries(state);
+    const existing = await this.listFiles();
+    for (const [key, entry] of entries) await this.save(key, entry);
+    const live = new Set([...entries.keys()].map((key) => bufferSessionFileName(key)));
+    for (const name of existing) {
+      if (live.has(name)) continue;
+      try {
+        await unlink(path.join(this.dir, name));
+      } catch (err) {
+        if (!(err instanceof Error) || !isMissing(asFsError(err))) throw err;
+      }
+    }
+  }
+};
+
+// src/storage/buffer-drain-claims.ts
+var CLAIM_LOCK_STALE_MS = 12e4;
+var CLAIM_LOCK_MAX_WAIT_MS = 12e4;
+function emptyEntry() {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+function mergeTurns(existing, incoming, isEqual) {
+  const merged = [...existing];
+  for (const turn of incoming) {
+    if (merged.some((kept) => isEqual(kept, turn))) continue;
+    merged.push(turn);
+  }
+  return merged;
+}
+function mergeEntries(claim, incoming) {
+  const entry = emptyEntry();
+  const gone = [...claim.drained ?? [], ...claim.drainedRetained ?? []];
+  entry.turns = mergeTurns(
+    subtractBufferTurns(claim.entry.turns, gone),
+    subtractBufferTurns(incoming.turns, gone),
+    bufferTurnsEqual
+  );
+  const retained = [
+    ...subtractBufferTurns(claim.entry.retainedTurns ?? [], gone),
+    ...subtractBufferTurns(incoming.retainedTurns ?? [], gone)
+  ];
+  const dedupedRetained = mergeTurns([], retained, bufferTurnsEqual);
+  if (dedupedRetained.length > 0) entry.retainedTurns = dedupedRetained;
+  const stamps = [claim.entry.lastExtractionAt, incoming.lastExtractionAt].filter(
+    (value) => value !== null && value !== void 0
+  );
+  entry.lastExtractionAt = stamps.sort().at(-1) ?? null;
+  entry.extractionCount = Math.max(claim.entry.extractionCount, incoming.extractionCount);
+  return { ...claim, entry };
+}
+function isOwnerAlive(lease) {
+  if (lease.host !== hostname()) return true;
+  if (!Number.isInteger(lease.pid) || lease.pid <= 0) return true;
+  try {
+    process.kill(lease.pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+function isLeaseExpired(lease, now = Date.now()) {
+  const heartbeat = Date.parse(lease.heartbeatAt);
+  return !Number.isFinite(heartbeat) || now - heartbeat > lease.leaseMs;
+}
+var claimBodySchema = z.object({
+  key: z.string().min(1),
+  entry: z.object({
+    turns: z.array(z.unknown()),
+    retainedTurns: z.array(z.unknown()).optional(),
+    lastExtractionAt: z.string().nullable().optional(),
+    extractionCount: z.number().optional()
+  }).optional(),
+  turns: z.array(z.unknown()).optional(),
+  retainedTurns: z.array(z.unknown()).optional(),
+  lastExtractionAt: z.string().nullable().optional(),
+  extractionCount: z.number().optional(),
+  claimedAt: z.string().optional(),
+  drained: z.array(z.unknown()).optional(),
+  drainedRetained: z.array(z.unknown()).optional()
+});
+function parseBody(raw) {
+  let body;
+  try {
+    body = claimBodySchema.parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+  const source = body.entry && Array.isArray(body.entry.turns) ? body.entry : body;
+  if (!Array.isArray(source.turns)) return null;
+  const entry = emptyEntry();
+  entry.turns = source.turns;
+  if (source.retainedTurns) {
+    entry.retainedTurns = source.retainedTurns;
+  }
+  entry.lastExtractionAt = source.lastExtractionAt ?? null;
+  entry.extractionCount = Number.isFinite(source.extractionCount) ? Number(source.extractionCount) : 0;
+  const claim = {
+    key: body.key,
+    entry,
+    claimedAt: body.claimedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (Array.isArray(body.drained)) {
+    claim.drained = body.drained;
+  }
+  if (Array.isArray(body.drainedRetained)) {
+    claim.drainedRetained = body.drainedRetained;
+  }
+  return claim;
+}
+var leaseSchema = z.object({
+  ownerId: z.string().min(1),
+  pid: z.number().optional(),
+  host: z.string().optional(),
+  acquiredAt: z.string().optional(),
+  heartbeatAt: z.string(),
+  leaseMs: z.number()
+});
+function parseLease(raw) {
+  let lease;
+  try {
+    lease = leaseSchema.parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+  return {
+    ownerId: lease.ownerId,
+    pid: lease.pid ?? 0,
+    host: lease.host ?? "",
+    acquiredAt: lease.acquiredAt ?? lease.heartbeatAt,
+    heartbeatAt: lease.heartbeatAt,
+    leaseMs: lease.leaseMs
+  };
+}
+var BufferDrainClaims = class {
+  constructor(stateDir, io) {
+    this.stateDir = stateDir;
+    this.io = io;
+  }
+  stateDir;
+  io;
+  get dir() {
+    return path2.join(this.stateDir, "buffer", "drain");
+  }
+  fileFor(key) {
+    return path2.join(this.dir, bufferSessionFileName(key));
+  }
+  leaseFileFor(key) {
+    return `${this.fileFor(key)}.lease.json`;
+  }
+  lockFileFor(key) {
+    return `${this.fileFor(key)}.lock`;
+  }
+  /** Sync existence check for hot-path gates (`SmartBuffer.isSessionClaimed`). */
+  isClaimed(key) {
+    return existsSync(this.fileFor(key));
+  }
+  /** Test + CLI seam: the lease file path for direct inspection. */
+  leasePathForTest(key) {
+    return this.leaseFileFor(key);
+  }
+  async readClaimBody(key) {
+    try {
+      return parseBody(await this.io.read(this.fileFor(key)));
+    } catch {
+      return null;
+    }
+  }
+  /** The claim content for `key`, or null when the key is not claimed. */
+  load(key) {
+    return this.readClaimBody(key);
+  }
+  async writeClaimBody(key, claim) {
+    await mkdir(this.dir, { recursive: true });
+    await this.io.write(this.fileFor(key), JSON.stringify({ ...claim, key }));
+  }
+  async readLease(key) {
+    try {
+      return parseLease(await this.io.read(this.leaseFileFor(key)));
+    } catch {
+      return null;
+    }
+  }
+  async writeLease(key, lease) {
+    await mkdir(this.dir, { recursive: true });
+    await this.io.write(this.leaseFileFor(key), JSON.stringify(lease));
+  }
+  /**
+   * Atomically move a session's persisted file into a claim. The rename is
+   * the handover: after it settles the turns exist ONLY as a claim, so no
+   * crash window can lose them or leave them in both places. Callers that
+   * lose the race (`already_claimed`) simply skip the key.
+   *
+   * The whole handover runs under the claim's mutation lock, so a claim
+   * create can never land on top of an existing claim (POSIX rename would
+   * silently replace it) and the lease write cannot race an adopter.
+   */
+  async claimFromSessionFile(key, lease) {
+    await mkdir(this.dir, { recursive: true });
+    const sessionPath = path2.join(this.stateDir, "buffer", bufferSessionFileName(key));
+    if (existsSync(sessionPath)) {
+      try {
+        const seeded = parseBody(await this.io.read(sessionPath));
+        if (seeded && seeded.entry.turns.length === 0 && (seeded.entry.retainedTurns?.length ?? 0) === 0) {
+          return "empty";
+        }
+      } catch {
+      }
+    }
+    return await withHeldFileLock(
+      this.lockFileFor(key),
+      { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS },
+      async (acquired) => {
+        if (!acquired) return "already_claimed";
+        if (this.isClaimed(key)) return "already_claimed";
+        try {
+          await rename(sessionPath, this.fileFor(key));
+        } catch (err) {
+          if (!existsSync(sessionPath)) {
+            if (this.isClaimed(key)) return "already_claimed";
+            return "empty";
+          }
+          throw err;
+        }
+        const claim = await this.readClaimBody(key);
+        if (!claim || claim.entry.turns.length === 0 && (claim.entry.retainedTurns?.length ?? 0) === 0) {
+          await unlink2(this.fileFor(key)).catch(() => {
+          });
+          return "empty";
+        }
+        await this.writeLease(key, lease);
+        return "claimed";
+      }
+    );
+  }
+  /**
+   * Take over a claim whose lease is missing, expired, or whose owner died.
+   * The whole judgement runs under the claim's mutation lock and re-reads
+   * the lease inside it, so exactly one concurrent adopter wins: the loser
+   * re-reads the winner's fresh lease and reports "busy" instead of
+   * unlinking it. A lease whose owner died is taken over in the same call.
+   */
+  async adopt(key, lease) {
+    if (!this.isClaimed(key)) return "busy";
+    return await withHeldFileLock(
+      this.lockFileFor(key),
+      { staleMs: CLAIM_LOCK_STALE_MS, maxWaitMs: CLAIM_LOCK_MAX_WAIT_MS },
+      async (acquired) => {
+        if (!acquired) return "busy";
+        const existing = await this.readLease(key);
+        if (existing && !isLeaseExpired(existing)) {
+          if (existing.ownerId === lease.ownerId) {
+            await this.writeLease(key, { ...existing, heartbeatAt: (/* @__PURE__ */ new Date()).toISOString(), leaseMs: lease.leaseMs });
+            return "adopted";
+          }
+          if (isOwnerAlive(existing)) return "busy";
+          await unlink2(this.leaseFileFor(key)).catch(() => {
+          });
+        } else if (existing) {
+          await unlink2(this.leaseFileFor(key)).catch(() => {
+          });
+        }
+        try {
+          await writeFile(this.leaseFileFor(key), JSON.stringify(lease), { flag: "wx" });
+        } catch (err) {
+          if (existsSync(this.leaseFileFor(key))) return "busy";
+          throw err;
+        }
+        return "adopted";
+      }
+    );
+  }
+  /**
+   * Merge a live owner's in-memory entry INTO the claim (the handover path a
+   * buffer owner takes instead of persisting a claimed session). Serialized
+   * against drainer progress writes on the same lock.
+   */
+  async mergeIntoClaim(key, incoming) {
+    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; retrying the save later`);
+      }
+      const claim = await this.readClaimBody(key);
+      if (!claim) {
+        return;
+      }
+      await this.writeClaimBody(key, mergeEntries(claim, incoming));
+    });
+  }
+  /** Drainer progress: replace the claim content with what is left to do.
+   *
+   * Fenced: `ownerId` must still match the claim's lease (checked under the
+   * same lock), so a drainer that lost its lease cannot write progress that
+   * would restore turns the new owner already extracted.
+   *
+   * `seen` is the entry the drainer LOADED (its snapshot of the claim). Only
+   * turns that were in that snapshot and are absent from BOTH of the
+   * drainer's lists were actually extracted and move to the tombstones — a
+   * turn the drainer moved into `entry.retainedTurns` is retained for retry,
+   * not extracted. Turns a live owner merged into the claim afterwards stay
+   * pending. Without `seen` the pre-existing behavior is kept (every claim
+   * turn missing from `entry` counts as extracted).
+   */
+  async writeEntry(key, ownerId, entry, seen) {
+    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) {
+        throw new Error(`buffer drain claim for ${key} is no longer owned by ${ownerId}; progress write skipped`);
+      }
+      const claim = await this.readClaimBody(key);
+      if (!claim) return;
+      const seenTurns = seen?.turns ?? claim.entry.turns;
+      const seenRetained = seen?.retainedTurns ?? claim.entry.retainedTurns ?? [];
+      const entryRetained = entry.retainedTurns ?? [];
+      const kept = (turn) => entry.turns.some((held) => bufferTurnsEqual(held, turn)) || entryRetained.some((held) => bufferTurnsEqual(held, turn));
+      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 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 late = claim.entry.turns.filter(
+        (turn) => !seenTurns.some((snapshot) => bufferTurnsEqual(snapshot, turn)) && !kept(turn)
+      );
+      const next = { ...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, bufferTurnsEqual);
+      await this.writeClaimBody(key, { ...claim, entry: next, drained, drainedRetained });
+    });
+  }
+  /** Extend the lease. "lost" means another drainer took the claim over.
+   * Serialized on the claim lock so a stale heartbeat can never overwrite a
+   * new owner's lease mid-takeover; a contended lock just skips this tick
+   * (usually the drainer's own progress write holds it). */
+  async heartbeat(key, ownerId, leaseMs) {
+    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";
+      await this.writeLease(key, { ...lease, heartbeatAt: (/* @__PURE__ */ new Date()).toISOString(), leaseMs });
+      return "ok";
+    });
+  }
+  /** Give the key back (content stays; the next run resumes it). */
+  async releaseLease(key, ownerId) {
+    const lease = await this.readLease(key);
+    if (!lease || lease.ownerId !== ownerId) return;
+    await unlink2(this.leaseFileFor(key)).catch(() => {
+    });
+  }
+  /**
+   * Finish a claim: only its owner may ack, and only when nothing is left to
+   * extract. Non-empty claims stay (deferred content is never dropped here).
+   */
+  async ack(key, ownerId) {
+    const lease = await this.readLease(key);
+    if (!lease || lease.ownerId !== ownerId) return "busy";
+    const claim = await this.readClaimBody(key);
+    if (!claim) {
+      await unlink2(this.leaseFileFor(key)).catch(() => {
+      });
+      return "acked";
+    }
+    if (claim.entry.turns.length > 0 || (claim.entry.retainedTurns?.length ?? 0) > 0) return "not_empty";
+    await unlink2(this.leaseFileFor(key)).catch(() => {
+    });
+    return "acked";
+  }
+  /** The turns a drain already extracted for `key` (tombstone content). */
+  async drainedTurns(key) {
+    const claim = await this.readClaimBody(key);
+    return claim?.drained ?? [];
+  }
+  /**
+   * Is the drain for `key` FINISHED (acked): the claim holds extracted turns
+   * and nothing pending, and the drainer dropped its lease. A claim with
+   * partial progress or a live lease is still being drained — its owner must
+   * merge into it, never release it.
+   */
+  async isDrained(key) {
+    const claim = await this.readClaimBody(key);
+    if (!claim) return false;
+    if ((claim.drained?.length ?? 0) === 0 && (claim.drainedRetained?.length ?? 0) === 0) return false;
+    if (claim.entry.turns.length > 0 || (claim.entry.retainedTurns?.length ?? 0) > 0) return false;
+    return await this.readLease(key) === null;
+  }
+  /** Drop the claim file entirely (its owner consumed the tombstone). */
+  async release(key) {
+    await unlink2(this.fileFor(key)).catch(() => {
+    });
+    await unlink2(this.leaseFileFor(key)).catch(() => {
+    });
+  }
+  /** Every claim with its lease state (CLI scan + summaries). */
+  async list() {
+    let names;
+    try {
+      names = (await readdir2(this.dir)).filter((name) => name.endsWith(".json") && !name.endsWith(".lease.json"));
+    } catch (err) {
+      if (err?.code === "ENOENT") return [];
+      throw err;
+    }
+    const out = [];
+    for (const name of names) {
+      const claim = await this.readClaimBodyByKey(name);
+      if (!claim) continue;
+      const lease = await this.readLease(claim.key);
+      out.push({
+        key: claim.key,
+        turnCount: claim.entry.turns.length + (claim.entry.retainedTurns?.length ?? 0),
+        leased: lease !== null,
+        leaseExpired: lease !== null ? isLeaseExpired(lease) : true
+      });
+    }
+    return out;
+  }
+  async readClaimBodyByKey(name) {
+    try {
+      return parseBody(await this.io.read(path2.join(this.dir, name)));
+    } catch (err) {
+      log.debug(`buffer drain: skipping unreadable claim file ${name}: ${err instanceof Error ? err.message : String(err)}`);
+      return null;
+    }
+  }
+};
+
+export {
+  BufferDrainClaims,
+  bufferSessionFileName,
+  legacyStateToEntries,
+  BufferSessionFiles
+};
+//# sourceMappingURL=chunk-JCL7RO2G.js.map