@code-yeongyu/senpi 2026.10.25-3 → 2026.10.26-1

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

@@ -0,0 +1,269 @@
+import { join } from "node:path";
+import { createSpoolDir, removeSpoolDir } from "./compact-spool-dir.js";
+import { CompactStorageReadError, describeCause, nodeCompactStorageIo, } from "./compact-storage-io.js";
+/**
+ * Owned bounded leaves for compact current state (senpi#4272, R3.C6.4 / R3.C2.4).
+ *
+ * Acceptance never waits here: a leaf is created synchronously in RAM, and a spill only relocates
+ * that immutable value. Its RAM copy is released only after the whole file was written and closed;
+ * a failed write keeps the bytes resident, halts further spilling and is reported through
+ * `status()`, never dropped. All storage work runs as one serial asynchronous job chain.
+ */
+/** 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 {
+    constructor(options) {
+        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;
+    }
+    /** Takes ownership of an immutable value with one live reference. */
+    createLeaf(text) {
+        const id = this.nextLeafId++;
+        this.leaves.set(id, { text, units: text.length, live: 1, pins: 0, state: "ram" });
+        this.ramLeaves.add(id);
+        this.residentPayloadBytes += text.length * 2;
+        this.scheduleSpill();
+        return id;
+    }
+    /** Moves live and cut-pin references; the last reference drops RAM or reclaims the file. */
+    adjust(id, live, pins) {
+        const leaf = this.leaves.get(id);
+        if (!leaf)
+            throw new Error(`compact leaf ${id} is not owned`);
+        const pinnedOnly = leaf.live === 0 && leaf.pins > 0;
+        leaf.live += live;
+        leaf.pins += pins;
+        if (pinnedOnly !== (leaf.live === 0 && leaf.pins > 0))
+            this.pinnedOnlyBytes += (pinnedOnly ? -2 : 2) * leaf.units;
+        if (leaf.live > 0 || leaf.pins > 0)
+            return;
+        this.leaves.delete(id);
+        this.ramLeaves.delete(id);
+        if (leaf.state === "committed" && leaf.path) {
+            this.spilledLiveBytes -= leaf.units * 2;
+            this.discard(leaf.path, leaf.units * 2);
+            return;
+        }
+        this.residentPayloadBytes -= leaf.units * 2;
+    }
+    /** Reads a leaf the caller still references, from RAM or its committed file. */
+    async readLeaf(id) {
+        const leaf = this.leaves.get(id);
+        if (!leaf)
+            throw new Error(`compact leaf ${id} is not owned`);
+        if (leaf.text !== undefined)
+            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,
+            pendingIoCopyBytes: this.pendingIoCopyBytes,
+            pinnedOnlyBytes: this.pinnedOnlyBytes,
+            spilledLiveBytes: this.spilledLiveBytes,
+            spillBytesWritten: this.spillBytesWritten,
+            reclaimDebtBytes: this.reclaimDebtBytes,
+            spillFailureRetainedBytes: this.spillStopped
+                ? Math.max(0, this.residentPayloadBytes - this.spillTargetBytes)
+                : 0,
+            spillHalted: this.spillStopped,
+            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;
+        if (this.reclaimDebtBytes > RECLAIM_WORK_ALLOWANCE_BYTES)
+            return;
+        this.spillQueued = true;
+        this.enqueue("spill_write", () => this.spillNext());
+    }
+    /** Spills one oldest resident leaf per job, so other storage work interleaves fairly. */
+    async spillNext() {
+        const [id] = this.ramLeaves;
+        const leaf = id === undefined ? undefined : this.leaves.get(id);
+        if (id === undefined || !leaf || leaf.text === undefined || !this.spillAllowed) {
+            this.spillQueued = false;
+            return;
+        }
+        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);
+        }
+        else if (!owned || this.retired) {
+            this.discard(path, bytes);
+        }
+        else {
+            leaf.state = "committed";
+            leaf.path = path;
+            leaf.text = undefined;
+            this.residentPayloadBytes -= bytes;
+            this.spilledLiveBytes += bytes;
+        }
+        this.spillQueued = false;
+        if (this.residentPayloadBytes > this.spillTargetBytes) {
+            this.spillQueued = this.spillAllowed;
+            if (this.spillQueued)
+                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-session-state.d.ts

@@ -0,0 +1,111 @@
+import { type CompactContentStoreOptions, type CompactStorageStatus, type LeafId } from "./compact-content-store.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
+ * 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;
+    readonly leaves: readonly LeafId[];
+    /** A cut shares the immutable active tail string (under one leaf) instead of minting a leaf per freeze. */
+    readonly tail: string;
+}
+interface SettledRow {
+    readonly persistence: CompactPersistence;
+    readonly blocks: readonly FrozenBlock[];
+}
+interface FrozenCompactState {
+    readonly sequence: number;
+    readonly active: ReadonlyMap<string, readonly FrozenBlock[]>;
+    readonly settled: ReadonlyMap<string, SettledRow>;
+}
+interface CompactMessageView {
+    readonly messageId: string;
+    readonly persistence: CompactPersistence | undefined;
+    readonly blocks: readonly {
+        readonly contentIndex: number;
+        readonly kind: CompactBlockKind;
+        readonly text: string;
+    }[];
+}
+export declare class CompactSessionState {
+    private readonly store;
+    private readonly settled;
+    private readonly active;
+    private sequence;
+    private frozenTailBytes;
+    constructor(options: CompactContentStoreOptions);
+    get acceptedSequence(): number;
+    accept(transition: CompactTransition): number;
+    freeze(): FrozenCompactState;
+    release(frozen: FrozenCompactState): void;
+    /** Rejects with the storage error when committed content is gone; never returns empty content for it. */
+    read(frozen: FrozenCompactState): Promise<{
+        sequence: number;
+        messages: CompactMessageView[];
+    }>;
+    storageStatus(): CompactStorageStatus & {
+        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>;
+    private start;
+    /**
+     * Appends only the new suffix. Overlap exists only while a fully covered seed is being replayed
+     * (`emitted < covered == units`), so it always lies inside the producer-declared coverage.
+     */
+    private delta;
+    private replace;
+    private setPersistence;
+    private remove;
+    private block;
+    private append;
+    /** Settling mints the final tail into a spillable leaf; a freeze of an active block shares the tail. */
+    private seal;
+    private pin;
+    private texts;
+}
+export {};
+//# sourceMappingURL=compact-session-state.d.ts.map

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

@@ -0,0 +1,206 @@
+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;
+    }
+}
+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);
+    }
+    get acceptedSequence() {
+        return this.sequence;
+    }
+    accept(transition) {
+        switch (transition.type) {
+            case "block_start":
+                this.start(transition);
+                break;
+            case "block_delta":
+                this.delta(this.block(transition), transition.offset, transition.text);
+                break;
+            case "block_replace":
+                this.replace(this.block(transition), transition.text);
+                break;
+            case "message_status":
+                this.setPersistence(transition.messageId, transition.persistence);
+                break;
+            case "message_remove":
+                this.remove(transition.messageId);
+                break;
+        }
+        return ++this.sequence;
+    }
+    freeze() {
+        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 };
+    }
+    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);
+    }
+    /** 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) {
+            messages.push({ messageId, persistence: row.persistence, blocks: await this.texts(row.blocks) });
+        }
+        for (const [messageId, blocks] of frozen.active) {
+            messages.push({ messageId, persistence: undefined, blocks: await this.texts(blocks) });
+        }
+        return { sequence: frozen.sequence, messages };
+    }
+    storageStatus() {
+        let residentTailBytes = 0;
+        let hotWitnessBytes = 0;
+        for (const blocks of this.active.values()) {
+            for (const block of blocks.values()) {
+                residentTailBytes += block.tail.length * 2;
+                hotWitnessBytes += block.witness.length * 2;
+            }
+        }
+        return {
+            ...this.store.status(),
+            residentTailBytes,
+            frozenTailBytes: this.frozenTailBytes,
+            hotWitnessBytes,
+            residentSettledRows: this.settled.size,
+        };
+    }
+    idle() {
+        return this.store.idle();
+    }
+    retire() {
+        return this.store.retire();
+    }
+    start(t) {
+        if (this.active.get(t.messageId)?.has(t.contentIndex) || this.settled.has(t.messageId)) {
+            throw new CompactTransitionError("duplicate_block", `${t.messageId}#${t.contentIndex}`);
+        }
+        const covered = t.coveredCodeUnits;
+        if (!Number.isInteger(covered) || (covered !== 0 && covered !== t.seed.length)) {
+            throw new CompactTransitionError("invalid_coverage", `${covered} of ${t.seed.length} seed code units`);
+        }
+        const emitted = covered > 0 ? 0 : t.seed.length;
+        const block = { kind: t.kind, leaves: [], tail: "", units: 0, emitted, covered, witness: "" };
+        block.witness = t.seed.slice(0, covered);
+        this.append(block, t.seed);
+        const blocks = this.active.get(t.messageId) ?? new Map();
+        blocks.set(t.contentIndex, block);
+        this.active.set(t.messageId, blocks);
+    }
+    /**
+     * Appends only the new suffix. Overlap exists only while a fully covered seed is being replayed
+     * (`emitted < covered == units`), so it always lies inside the producer-declared coverage.
+     */
+    delta(block, offset, text) {
+        if (offset !== block.emitted) {
+            throw new CompactTransitionError("non_contiguous", `offset ${offset}, expected ${block.emitted}`);
+        }
+        const overlapEnd = Math.min(offset + text.length, block.units);
+        const overlap = Math.max(0, overlapEnd - offset);
+        if (overlap > 0 && text.slice(0, overlap) !== block.witness.slice(offset, overlapEnd)) {
+            throw new CompactTransitionError("conflicting_overlap", `[${offset}, ${overlapEnd})`);
+        }
+        this.append(block, text.slice(overlap));
+        block.emitted = offset + text.length;
+        if (block.emitted >= block.covered)
+            block.witness = "";
+    }
+    replace(block, text) {
+        for (const id of block.leaves.splice(0))
+            this.store.adjust(id, -1, 0);
+        block.tail = "";
+        block.units = 0;
+        block.covered = 0;
+        block.witness = "";
+        this.append(block, text);
+        block.emitted = block.units;
+    }
+    setPersistence(messageId, persistence) {
+        const blocks = this.active.get(messageId);
+        if (blocks) {
+            this.settled.set(messageId, { persistence, blocks: this.seal(blocks, true) });
+            this.active.delete(messageId);
+            return;
+        }
+        const row = this.settled.get(messageId);
+        if (row) {
+            this.settled.set(messageId, { ...row, persistence });
+        }
+        else {
+            throw new CompactTransitionError("unknown_message", messageId);
+        }
+    }
+    remove(messageId) {
+        const blocks = this.active.get(messageId);
+        const row = this.settled.get(messageId);
+        if (!blocks && !row)
+            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);
+    }
+    block(address) {
+        const block = this.active.get(address.messageId)?.get(address.contentIndex);
+        if (!block)
+            throw new CompactTransitionError("unknown_block", `${address.messageId}#${address.contentIndex}`);
+        return block;
+    }
+    append(block, text) {
+        block.units += text.length;
+        let rest = text;
+        while (block.tail.length + rest.length >= COMPACT_LEAF_CODE_UNITS) {
+            const take = COMPACT_LEAF_CODE_UNITS - block.tail.length;
+            block.leaves.push(this.store.createLeaf(block.tail + rest.slice(0, take)));
+            block.tail = "";
+            rest = rest.slice(take);
+        }
+        block.tail += rest;
+    }
+    /** Settling mints the final tail into a spillable leaf; a freeze of an active block shares the tail. */
+    seal(blocks, settle) {
+        return [...blocks].sort(byContentIndex).map(([contentIndex, block]) => {
+            if (settle && block.tail.length > 0) {
+                block.leaves.push(this.store.createLeaf(block.tail));
+                block.tail = "";
+            }
+            return { contentIndex, kind: block.kind, leaves: [...block.leaves], tail: block.tail };
+        });
+    }
+    pin(blocks, delta) {
+        for (const block of blocks) {
+            this.frozenTailBytes += delta * block.tail.length * 2;
+            for (const id of block.leaves)
+                this.store.adjust(id, 0, delta);
+        }
+    }
+    async texts(blocks) {
+        return Promise.all(blocks.map(async ({ contentIndex, kind, leaves, tail }) => {
+            const parts = await Promise.all(leaves.map((id) => this.store.readLeaf(id)));
+            return { contentIndex, kind, text: parts.join("") + tail };
+        }));
+    }
+}
+//# sourceMappingURL=compact-session-state.js.map

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

@@ -0,0 +1,5 @@
+/** 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. */
+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

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * 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
+ * re-checks the directory and that marker without following symlinks, so retirement never deletes
+ * a directory this store did not create and still own.
+ */
+const MARKER = ".compact-spool-owner";
+class CompactSpoolRefusedError extends Error {
+    constructor(reason, path) {
+        super(`compact spool directory refused (${reason}): ${path}`);
+        this.name = "CompactSpoolRefusedError";
+        this.reason = reason;
+        this.path = path;
+    }
+}
+/** Creates a fresh private epoch directory and returns the token its ownership marker holds. */
+export async function createSpoolDir(dir) {
+    await mkdir(dirname(dir), { recursive: true, mode: 0o700 });
+    try {
+        await mkdir(dir, { mode: 0o700 });
+    }
+    catch (cause) {
+        if (cause.code === "EEXIST")
+            throw new CompactSpoolRefusedError("pre_existing", dir);
+        throw cause;
+    }
+    const token = randomUUID();
+    await writeFile(join(dir, MARKER), token, { flag: "wx", mode: 0o600 });
+    return token;
+}
+/** Removes `dir` only while it is still the private, marked directory `createSpoolDir` made. */
+export async function removeSpoolDir(dir, token) {
+    const refusal = await refusalFor(dir, 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);
+    if (owned.isSymbolicLink())
+        return "symlink";
+    if (!owned.isDirectory())
+        return "not_directory";
+    const markerPath = join(dir, MARKER);
+    const marker = await lstat(markerPath).catch(() => undefined);
+    if (!marker?.isFile() || (await readFile(markerPath, "utf8")) !== token)
+        return "marker_missing";
+    // Windows has no POSIX owner or mode bits; the marker token and the no-follow checks still apply.
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return undefined;
+    if (owned.uid !== uid || marker.uid !== uid)
+        return "foreign_owner";
+    if (((owned.mode | marker.mode) & 0o077) !== 0)
+        return "wide_mode";
+    return undefined;
+}
+//# sourceMappingURL=compact-spool-dir.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * The asynchronous file seam of compact current-state storage (senpi#4272) and the failures it
+ * reports. Every spool access goes through `CompactStorageIo`; nothing here blocks the host loop.
+ */
+export type CompactStorageOperation = "spool_create" | "spill_write" | "leaf_read" | "reclaim";
+export interface CompactStorageFailure {
+    readonly operation: CompactStorageOperation;
+    readonly path: string;
+    readonly cause: string;
+    /** Accepted bytes this failure leaves resident in memory instead of on disk. */
+    readonly retainedInMemoryBytes: number;
+}
+/** Asynchronous file access the host supplies; the default is node's promise filesystem. */
+export interface CompactStorageIo {
+    writeFile(path: string, data: Buffer): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    unlink(path: string): Promise<void>;
+}
+export declare const nodeCompactStorageIo: CompactStorageIo;
+export declare function describeCause(cause: unknown): string;
+/** Committed storage that can no longer be read: a real error, never empty content. */
+export declare class CompactStorageReadError extends Error {
+    readonly operation: CompactStorageOperation;
+    readonly path: string;
+    constructor(operation: CompactStorageOperation, path: string, cause: unknown);
+}
+//# sourceMappingURL=compact-storage-io.d.ts.map