@code-yeongyu/senpi 2026.10.26-1 → 2026.10.26-2

package/dist/modes/rpc/compact-content-store.js

@@ -1,6 +1,5 @@
-import { join } from "node:path";
-import { createSpoolDir, removeSpoolDir } from "./compact-spool-dir.js";
-import { CompactStorageReadError, describeCause, nodeCompactStorageIo, } from "./compact-storage-io.js";
+import { CompactSpoolStorage, RECLAIM_WORK_ALLOWANCE_BYTES } from "./compact-spool-storage.js";
+import { nodeCompactStorageIo } from "./compact-storage-io.js";
 /**
  * Owned bounded leaves for compact current state (senpi#4272, R3.C6.4 / R3.C2.4).
  *
@@ -11,30 +10,16 @@ import { CompactStorageReadError, describeCause, nodeCompactStorageIo, } from ".
  */
 /** 32,768 UTF-16 code units (64 KiB as UTF-16LE), so a split surrogate survives a leaf boundary exactly. */
 export const COMPACT_LEAF_CODE_UNITS = 32_768;
-const RECLAIM_WORK_ALLOWANCE_BYTES = 1024 * 1024;
-const RECLAIM_RETRY_DELAYS_MS = [100, 400, 1_600, 6_400, 25_600];
-const FAILURE_HISTORY = 32;
-export class CompactContentStore {
+export class CompactContentStore extends CompactSpoolStorage {
     constructor(options) {
+        super(options.dir, options.io ?? nodeCompactStorageIo);
         this.leaves = new Map();
         /** Resident leaves in creation order, so each spill takes the oldest without rescanning committed ones. */
         this.ramLeaves = new Set();
-        this.failures = [];
         this.nextLeafId = 1;
-        this.nextFile = 1;
-        this.chain = Promise.resolve();
-        this.queued = 0;
-        this.spillQueued = false;
-        this.halted = false;
-        this.retired = false;
         this.residentPayloadBytes = 0;
-        this.pendingIoCopyBytes = 0;
         this.pinnedOnlyBytes = 0;
         this.spilledLiveBytes = 0;
-        this.spillBytesWritten = 0;
-        this.reclaimDebtBytes = 0;
-        this.dir = options.dir;
-        this.io = options.io ?? nodeCompactStorageIo;
         this.spillAboveBytes = options.spillAboveBytes ?? 4 * 1024 * 1024;
         this.spillTargetBytes = options.spillTargetBytes ?? 2 * 1024 * 1024;
     }
@@ -68,6 +53,9 @@ export class CompactContentStore {
         }
         this.residentPayloadBytes -= leaf.units * 2;
     }
+    isCommitted(id) {
+        return this.leaves.get(id)?.state === "committed";
+    }
     /** Reads a leaf the caller still references, from RAM or its committed file. */
     async readLeaf(id) {
         const leaf = this.leaves.get(id);
@@ -77,23 +65,6 @@ export class CompactContentStore {
             return leaf.text;
         return (await this.readFile(leaf.path ?? "", leaf.units * 2, "leaf_read")).toString("utf16le");
     }
-    /** Resolves once every queued storage job, including the ones they queued, has completed. */
-    async idle() {
-        while (this.queued > 0)
-            await this.chain;
-    }
-    /**
-     * Invalidates spilling, joins owned I/O, then removes the epoch directory only when this store
-     * created it and it still passes the ownership checks; otherwise rejects with `CompactSpoolRefusedError`.
-     */
-    async retire() {
-        this.retired = true;
-        await this.idle();
-        const token = this.spoolToken;
-        this.spoolToken = undefined;
-        if (token !== undefined)
-            await removeSpoolDir(this.dir, token);
-    }
     status() {
         return {
             residentPayloadBytes: this.residentPayloadBytes,
@@ -109,94 +80,6 @@ export class CompactContentStore {
             failures: [...this.failures],
         };
     }
-    /** Reads a committed file and rejects a missing, unreadable or short one. */
-    async readFile(path, bytes, operation) {
-        let data;
-        try {
-            data = await this.io.readFile(path);
-        }
-        catch (cause) {
-            throw this.readFailure(operation, path, cause);
-        }
-        if (data.byteLength !== bytes) {
-            throw this.readFailure(operation, path, new Error(`expected ${bytes} bytes, found ${data.byteLength}`));
-        }
-        return data;
-    }
-    /** Writes one new spool file; undefined means the write failed, was reported, and spilling halted. */
-    async writeFile(data, operation, retainedInMemoryBytes) {
-        const path = await this.ensureDir(retainedInMemoryBytes);
-        if (path === undefined)
-            return undefined;
-        const file = join(path, `leaf-${this.nextFile++}.bin`);
-        this.pendingIoCopyBytes += data.byteLength;
-        try {
-            await this.io.writeFile(file, data);
-            this.spillBytesWritten += data.byteLength;
-            return file;
-        }
-        catch (cause) {
-            this.fail(operation, file, cause, retainedInMemoryBytes);
-            this.discard(file, data.byteLength);
-            return undefined;
-        }
-        finally {
-            this.pendingIoCopyBytes -= data.byteLength;
-        }
-    }
-    /**
-     * An unreferenced (or partially written) spool file: reclamation debt until its unlink completes or
-     * finds it gone. Files dropped after retirement started belong to the directory retirement removes.
-     */
-    discard(path, bytes) {
-        if (this.retired)
-            return;
-        this.reclaimDebtBytes += bytes;
-        this.enqueue("reclaim", () => this.reclaim(path, bytes, 0));
-    }
-    /** A failed unlink keeps its debt and is retried with bounded backoff outside the job chain. */
-    async reclaim(path, bytes, attempt) {
-        try {
-            await this.io.unlink(path);
-        }
-        catch (cause) {
-            if (cause.code !== "ENOENT") {
-                this.fail("reclaim", path, cause, 0);
-                const delay = RECLAIM_RETRY_DELAYS_MS[attempt];
-                if (delay !== undefined) {
-                    setTimeout(() => {
-                        if (this.retired)
-                            this.reclaimDebtBytes -= bytes;
-                        else
-                            this.enqueue("reclaim", () => this.reclaim(path, bytes, attempt + 1));
-                    }, delay).unref?.();
-                }
-                return;
-            }
-        }
-        this.reclaimDebtBytes -= bytes;
-        this.scheduleSpill();
-    }
-    get spillAllowed() {
-        return !this.halted && !this.retired;
-    }
-    /** True while a storage failure or unreclaimed debt above the work allowance holds spilling back. */
-    get spillStopped() {
-        return this.halted || this.reclaimDebtBytes > RECLAIM_WORK_ALLOWANCE_BYTES;
-    }
-    enqueue(operation, job) {
-        this.queued++;
-        this.chain = this.chain
-            .then(job)
-            .catch((cause) => {
-            if (operation === "spill_write")
-                this.spillQueued = false;
-            this.fail(operation, this.dir, cause, 0);
-        })
-            .finally(() => {
-            this.queued--;
-        });
-    }
     scheduleSpill() {
         if (this.spillQueued || !this.spillAllowed || this.residentPayloadBytes <= this.spillAboveBytes)
             return;
@@ -216,22 +99,29 @@ export class CompactContentStore {
         const bytes = leaf.units * 2;
         leaf.state = "pending";
         this.ramLeaves.delete(id);
-        const path = await this.writeFile(Buffer.from(leaf.text, "utf16le"), "spill_write", bytes);
-        const owned = this.leaves.get(id) === leaf;
-        if (path === undefined) {
-            leaf.state = "ram";
-            if (owned)
-                this.ramLeaves.add(id);
+        let path;
+        try {
+            path = await this.writeFile(Buffer.from(leaf.text, "utf16le"), "spill_write", bytes);
         }
-        else if (!owned || this.retired) {
+        finally {
+            // A failed write, or a failure report that threw, keeps the leaf resident and spillable.
+            if (path === undefined) {
+                leaf.state = "ram";
+                if (this.leaves.get(id) === leaf)
+                    this.ramLeaves.add(id);
+            }
+        }
+        const owned = this.leaves.get(id) === leaf;
+        if (path !== undefined && (!owned || this.retired)) {
             this.discard(path, bytes);
         }
-        else {
+        else if (path !== undefined) {
             leaf.state = "committed";
             leaf.path = path;
             leaf.text = undefined;
             this.residentPayloadBytes -= bytes;
             this.spilledLiveBytes += bytes;
+            this.onCommitted?.(id);
         }
         this.spillQueued = false;
         if (this.residentPayloadBytes > this.spillTargetBytes) {
@@ -240,30 +130,5 @@ export class CompactContentStore {
                 this.enqueue("spill_write", () => this.spillNext());
         }
     }
-    /** Creates the private epoch directory once; a refusal or failure halts spilling and is reported. */
-    ensureDir(retained) {
-        this.dirReady ??= createSpoolDir(this.dir).then((token) => {
-            this.spoolToken = token;
-            return this.dir;
-        }, (cause) => {
-            this.fail("spool_create", this.dir, cause, retained);
-            return undefined;
-        });
-        return this.dirReady;
-    }
-    readFailure(operation, path, cause) {
-        this.fail(operation, path, cause, 0);
-        return new CompactStorageReadError(operation, path, cause);
-    }
-    fail(operation, path, cause, retained) {
-        if (operation === "spill_write" || operation === "spool_create")
-            this.halted = true;
-        this.record({ operation, path, cause: describeCause(cause), retainedInMemoryBytes: retained });
-    }
-    record(failure) {
-        this.failures.push(failure);
-        if (this.failures.length > FAILURE_HISTORY)
-            this.failures.shift();
-    }
 }
 //# sourceMappingURL=compact-content-store.js.map

package/dist/modes/rpc/compact-index-pages.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Page layout of the compact settled-row index (senpi#4272): how folded rows are packed into
+ * copy-on-write page files, and which base pages are small enough to merge on the next compaction.
+ */
+/** A page under half full in both rows and bytes is rewritten by the next compaction, so pages merge. */
+export declare function isSmallPage(page: {
+    readonly keys: readonly string[];
+    readonly bytes: number;
+}): boolean;
+/** Packs entries into pages of at most `PAGE_ROWS` rows and `PAGE_BYTES` UTF-8 bytes (one oversized row stands alone). */
+export declare function packPages<Row>(rows: readonly [string, Row][]): [string, Row][][];
+//# sourceMappingURL=compact-index-pages.d.ts.map

package/dist/modes/rpc/compact-index-pages.js

@@ -0,0 +1,31 @@
+/**
+ * Page layout of the compact settled-row index (senpi#4272): how folded rows are packed into
+ * copy-on-write page files, and which base pages are small enough to merge on the next compaction.
+ */
+const PAGE_ROWS = 128;
+const PAGE_BYTES = 64 * 1024;
+/** A page under half full in both rows and bytes is rewritten by the next compaction, so pages merge. */
+export function isSmallPage(page) {
+    return page.keys.length < PAGE_ROWS / 2 && page.bytes < PAGE_BYTES / 2;
+}
+/** Packs entries into pages of at most `PAGE_ROWS` rows and `PAGE_BYTES` UTF-8 bytes (one oversized row stands alone). */
+export function packPages(rows) {
+    const pages = [];
+    let page = [];
+    // UTF-8 bytes of the serialized page: the brackets, plus each entry and its separator.
+    let bytes = 1;
+    for (const entry of rows) {
+        const size = Buffer.byteLength(JSON.stringify(entry)) + 1;
+        if (page.length > 0 && (page.length === PAGE_ROWS || bytes + size > PAGE_BYTES)) {
+            pages.push(page);
+            page = [];
+            bytes = 1;
+        }
+        page.push(entry);
+        bytes += size;
+    }
+    if (page.length > 0)
+        pages.push(page);
+    return pages;
+}
+//# sourceMappingURL=compact-index-pages.js.map

package/dist/modes/rpc/compact-session-state.d.ts

@@ -1,45 +1,15 @@
+import { CompactContentIndex, type FrozenIndex } from "./compact-content-index.ts";
 import { type CompactContentStoreOptions, type CompactStorageStatus, type LeafId } from "./compact-content-store.ts";
+import { type CompactBlockKind, type CompactPersistence, type CompactTransition } from "./compact-transition.ts";
 /**
  * The in-memory current-state owner over compact storage (senpi#4272, R3.C6.4 first half).
  *
  * `accept` is synchronous: it validates a typed transition completely, then publishes the next
  * sequence, or throws and leaves the prior root untouched. Block text lives in owned bounded leaves
- * that spill asynchronously; settled message rows live in a resident map whose persistence status
- * changes only through `message_status`, never through storage success or failure. The map is
- * exact for every transition: a status change replaces the whole row, a removal deletes it, and a
- * transition addressing a removed or unknown message is refused rather than masked. `freeze` pins
+ * that spill asynchronously; settled messages live in a spillable index whose persistence status
+ * changes only through `message_status`, never through storage success or failure. `freeze` pins
  * an immutable cut synchronously, and `read` materializes it asynchronously from RAM or disk.
  */
-type CompactBlockKind = "text" | "thinking" | "tool_arguments";
-type CompactPersistence = "pending" | "appended" | "failed";
-interface BlockAddress {
-    readonly messageId: string;
-    readonly contentIndex: number;
-}
-export type CompactTransition = (BlockAddress & {
-    readonly type: "block_start";
-    readonly kind: CompactBlockKind;
-    readonly seed: string;
-    /**
-     * The whole seed when later deltas replay it from offset 0, or 0 when they continue after it. Partial
-     * coverage is refused: the uncovered seed tail would make every later delta overlap or leave a gap.
-     */
-    readonly coveredCodeUnits: number;
-}) | (BlockAddress & {
-    readonly type: "block_delta";
-    readonly offset: number;
-    readonly text: string;
-}) | (BlockAddress & {
-    readonly type: "block_replace";
-    readonly text: string;
-}) | {
-    readonly type: "message_status";
-    readonly messageId: string;
-    readonly persistence: CompactPersistence;
-} | {
-    readonly type: "message_remove";
-    readonly messageId: string;
-};
 interface FrozenBlock {
     readonly contentIndex: number;
     readonly kind: CompactBlockKind;
@@ -54,7 +24,7 @@ interface SettledRow {
 interface FrozenCompactState {
     readonly sequence: number;
     readonly active: ReadonlyMap<string, readonly FrozenBlock[]>;
-    readonly settled: ReadonlyMap<string, SettledRow>;
+    readonly settled: FrozenIndex<SettledRow>;
 }
 interface CompactMessageView {
     readonly messageId: string;
@@ -65,13 +35,17 @@ interface CompactMessageView {
         readonly text: string;
     }[];
 }
+export interface CompactSessionStateOptions extends CompactContentStoreOptions {
+    /** Index compaction is considered once this many override slots exist (one page by default). */
+    readonly compactAboveRows?: number;
+}
 export declare class CompactSessionState {
     private readonly store;
     private readonly settled;
     private readonly active;
     private sequence;
     private frozenTailBytes;
-    constructor(options: CompactContentStoreOptions);
+    constructor(options: CompactSessionStateOptions);
     get acceptedSequence(): number;
     accept(transition: CompactTransition): number;
     freeze(): FrozenCompactState;
@@ -81,13 +55,11 @@ export declare class CompactSessionState {
         sequence: number;
         messages: CompactMessageView[];
     }>;
-    storageStatus(): CompactStorageStatus & {
+    storageStatus(): CompactStorageStatus & ReturnType<CompactContentIndex<SettledRow>["status"]> & {
         readonly residentTailBytes: number;
         /** Active tails held by unreleased cuts; may share storage with `residentTailBytes`. */
         readonly frozenTailBytes: number;
         readonly hotWitnessBytes: number;
-        /** Settled rows kept resident: S03a-1 has no paged row index, so every row header stays in RAM. */
-        readonly residentSettledRows: number;
     };
     idle(): Promise<void>;
     retire(): Promise<void>;

package/dist/modes/rpc/compact-session-state.js

@@ -1,19 +1,15 @@
+import { CompactContentIndex } from "./compact-content-index.js";
 import { COMPACT_LEAF_CODE_UNITS, CompactContentStore, } from "./compact-content-store.js";
-class CompactTransitionError extends Error {
-    constructor(reason, detail) {
-        super(`compact transition rejected (${reason}): ${detail}`);
-        this.name = "CompactTransitionError";
-        this.reason = reason;
-    }
-}
+import { CompactTransitionError, } from "./compact-transition.js";
 const byContentIndex = ([a], [b]) => a - b;
 export class CompactSessionState {
     constructor(options) {
-        this.settled = new Map();
         this.active = new Map();
         this.sequence = 0;
         this.frozenTailBytes = 0;
         this.store = new CompactContentStore(options);
+        const leavesOf = (row) => row.blocks.flatMap((block) => block.leaves);
+        this.settled = new CompactContentIndex(this.store, leavesOf, options.compactAboveRows ?? 128);
     }
     get acceptedSequence() {
         return this.sequence;
@@ -42,23 +38,19 @@ export class CompactSessionState {
         const active = new Map();
         for (const [messageId, blocks] of this.active)
             active.set(messageId, this.seal(blocks, false));
-        const settled = new Map(this.settled);
         for (const blocks of active.values())
             this.pin(blocks, 1);
-        for (const row of settled.values())
-            this.pin(row.blocks, 1);
-        return { sequence: this.sequence, active, settled };
+        return { sequence: this.sequence, active, settled: this.settled.freeze() };
     }
     release(frozen) {
         for (const blocks of frozen.active.values())
             this.pin(blocks, -1);
-        for (const row of frozen.settled.values())
-            this.pin(row.blocks, -1);
+        this.settled.release(frozen.settled);
     }
     /** Rejects with the storage error when committed content is gone; never returns empty content for it. */
     async read(frozen) {
         const messages = [];
-        for (const [messageId, row] of frozen.settled) {
+        for (const [messageId, row] of await this.settled.entries(frozen.settled)) {
             messages.push({ messageId, persistence: row.persistence, blocks: await this.texts(row.blocks) });
         }
         for (const [messageId, blocks] of frozen.active) {
@@ -77,10 +69,10 @@ export class CompactSessionState {
         }
         return {
             ...this.store.status(),
+            ...this.settled.status(),
             residentTailBytes,
             frozenTailBytes: this.frozenTailBytes,
             hotWitnessBytes,
-            residentSettledRows: this.settled.size,
         };
     }
     idle() {
@@ -137,12 +129,13 @@ export class CompactSessionState {
         const blocks = this.active.get(messageId);
         if (blocks) {
             this.settled.set(messageId, { persistence, blocks: this.seal(blocks, true) });
+            for (const block of blocks.values())
+                for (const id of block.leaves)
+                    this.store.adjust(id, -1, 0);
             this.active.delete(messageId);
-            return;
         }
-        const row = this.settled.get(messageId);
-        if (row) {
-            this.settled.set(messageId, { ...row, persistence });
+        else if (this.settled.has(messageId)) {
+            this.settled.patch(messageId, { persistence });
         }
         else {
             throw new CompactTransitionError("unknown_message", messageId);
@@ -150,17 +143,15 @@ export class CompactSessionState {
     }
     remove(messageId) {
         const blocks = this.active.get(messageId);
-        const row = this.settled.get(messageId);
-        if (!blocks && !row)
+        const settled = this.settled.has(messageId);
+        if (!blocks && !settled)
             throw new CompactTransitionError("unknown_message", messageId);
         for (const block of blocks?.values() ?? [])
             for (const id of block.leaves)
                 this.store.adjust(id, -1, 0);
-        for (const block of row?.blocks ?? [])
-            for (const id of block.leaves)
-                this.store.adjust(id, -1, 0);
         this.active.delete(messageId);
-        this.settled.delete(messageId);
+        if (settled)
+            this.settled.delete(messageId);
     }
     block(address) {
         const block = this.active.get(address.messageId)?.get(address.contentIndex);

package/dist/modes/rpc/compact-spool-dir.d.ts

@@ -1,5 +1,8 @@
 /** Creates a fresh private epoch directory and returns the token its ownership marker holds. */
 export declare function createSpoolDir(dir: string): Promise<string>;
-/** Removes `dir` only while it is still the private, marked directory `createSpoolDir` made. */
+/**
+ * Removes `dir` only while it is still the private, marked directory `createSpoolDir` made. A
+ * directory that is already gone leaves nothing to remove, so retirement settles as a no-op.
+ */
 export declare function removeSpoolDir(dir: string, token: string): Promise<void>;
 //# sourceMappingURL=compact-spool-dir.d.ts.map

package/dist/modes/rpc/compact-spool-dir.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { describeCause } from "./compact-storage-io.js";
 /**
  * Ownership of the compact spool's epoch directory (senpi#4272). The store creates the directory
  * itself (0700, never adopting an existing one) and writes a private marker into it; removal
@@ -9,8 +10,10 @@ import { dirname, join } from "node:path";
  */
 const MARKER = ".compact-spool-owner";
 class CompactSpoolRefusedError extends Error {
-    constructor(reason, path) {
-        super(`compact spool directory refused (${reason}): ${path}`);
+    constructor(reason, path, cause, cleanupFailure) {
+        const detail = cause === undefined ? "" : `: ${describeCause(cause)}`;
+        const kept = cleanupFailure === undefined ? "" : `; removing the directory failed: ${describeCause(cleanupFailure)}`;
+        super(`compact spool directory refused (${reason}): ${path}${detail}${kept}`, { cause });
         this.name = "CompactSpoolRefusedError";
         this.reason = reason;
         this.path = path;
@@ -28,18 +31,48 @@ export async function createSpoolDir(dir) {
         throw cause;
     }
     const token = randomUUID();
-    await writeFile(join(dir, MARKER), token, { flag: "wx", mode: 0o600 });
+    try {
+        await writeFile(join(dir, MARKER), token, { flag: "wx", mode: 0o600 });
+    }
+    catch (cause) {
+        throw await abandonSpoolDir(dir, cause);
+    }
     return token;
 }
-/** Removes `dir` only while it is still the private, marked directory `createSpoolDir` made. */
+/**
+ * Removes a directory `createSpoolDir` just made but could not mark, so a later store creates it
+ * fresh instead of refusing it as pre-existing. Only a marker this call's exclusive create made (any
+ * failure but EEXIST) is unlinked, then the directory itself, which `rmdir` removes only while empty.
+ */
+async function abandonSpoolDir(dir, cause) {
+    try {
+        if (cause.code !== "EEXIST")
+            await rm(join(dir, MARKER), { force: true });
+        await rmdir(dir);
+        return new CompactSpoolRefusedError("marker_write_failed", dir, cause);
+    }
+    catch (cleanupFailure) {
+        return new CompactSpoolRefusedError("marker_write_failed", dir, cause, cleanupFailure);
+    }
+}
+/**
+ * Removes `dir` only while it is still the private, marked directory `createSpoolDir` made. A
+ * directory that is already gone leaves nothing to remove, so retirement settles as a no-op.
+ */
 export async function removeSpoolDir(dir, token) {
-    const refusal = await refusalFor(dir, token);
+    const owned = await lstat(dir).catch((cause) => {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    });
+    if (owned === undefined)
+        return;
+    const refusal = await refusalFor(dir, owned, token);
     if (refusal)
         throw new CompactSpoolRefusedError(refusal, dir);
     await rm(dir, { recursive: true, force: true });
 }
-async function refusalFor(dir, token) {
-    const owned = await lstat(dir);
+async function refusalFor(dir, owned, token) {
     if (owned.isSymbolicLink())
         return "symlink";
     if (!owned.isDirectory())

package/dist/modes/rpc/compact-spool-storage.d.ts

@@ -0,0 +1,53 @@
+import { type CompactStorageFailure, type CompactStorageIo, type CompactStorageOperation } from "./compact-storage-io.ts";
+/**
+ * The spool file path of compact current-state storage (senpi#4272, R3.C6.4): one serial
+ * asynchronous job chain, the private epoch directory, spool file writes, reads and reclamation,
+ * and the failure ledger. `CompactContentStore` adds leaf ownership and spilling on top.
+ */
+export declare const RECLAIM_WORK_ALLOWANCE_BYTES: number;
+export declare abstract class CompactSpoolStorage {
+    readonly dir: string;
+    private readonly io;
+    protected readonly failures: CompactStorageFailure[];
+    private nextFile;
+    private dirReady;
+    private spoolToken;
+    private chain;
+    private queued;
+    protected spillQueued: boolean;
+    private halted;
+    protected retired: boolean;
+    protected pendingIoCopyBytes: number;
+    protected spillBytesWritten: number;
+    protected reclaimDebtBytes: number;
+    constructor(dir: string, io: CompactStorageIo);
+    /** Resolves once every queued storage job, including the ones they queued, has completed. */
+    idle(): Promise<void>;
+    /**
+     * Invalidates spilling, joins owned I/O, then removes the epoch directory only when this store
+     * created it and it still passes the ownership checks; otherwise rejects with `CompactSpoolRefusedError`.
+     */
+    retire(): Promise<void>;
+    /** Reads a committed file and rejects a missing, unreadable or short one. */
+    readFile(path: string, bytes: number, operation: CompactStorageOperation): Promise<Buffer>;
+    /** Writes one new spool file; undefined means the write failed and was reported (a spill write also halts spilling). */
+    writeFile(data: Buffer, operation: CompactStorageOperation, retainedInMemoryBytes: number): Promise<string | undefined>;
+    /**
+     * An unreferenced (or partially written) spool file: reclamation debt until its unlink completes or
+     * finds it gone. Files dropped after retirement started belong to the directory retirement removes.
+     */
+    discard(path: string, bytes: number): void;
+    /** A failed unlink keeps its debt and is retried with bounded backoff outside the job chain. */
+    private reclaim;
+    get spillAllowed(): boolean;
+    /** True while a storage failure or unreclaimed debt above the work allowance holds spilling back. */
+    protected get spillStopped(): boolean;
+    enqueue(operation: CompactStorageOperation, job: () => Promise<void>): void;
+    protected abstract scheduleSpill(): void;
+    /** Creates the private epoch directory once; a refusal or failure halts spilling and is reported. */
+    private ensureDir;
+    private readFailure;
+    private fail;
+    private record;
+}
+//# sourceMappingURL=compact-spool-storage.d.ts.map