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

package/dist/modes/rpc/compact-read-lease.js

@@ -0,0 +1,40 @@
+export class CompactReadError extends Error {
+    constructor(reason) {
+        super(`compact read refused (${reason})`);
+        this.name = "CompactReadError";
+        this.reason = reason;
+    }
+}
+/** Invalidates immediately, but holds the owner's references until its last operation unwinds. */
+export class CompactReadLease {
+    constructor(dispose) {
+        this.released = false;
+        this.operations = 0;
+        this.dispose = dispose;
+    }
+    assert() {
+        if (this.released)
+            throw new CompactReadError("released");
+    }
+    async run(read) {
+        this.assert();
+        this.operations++;
+        try {
+            const result = await read();
+            this.assert();
+            return result;
+        }
+        finally {
+            if (--this.operations === 0 && this.released)
+                this.dispose();
+        }
+    }
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        if (this.operations === 0)
+            this.dispose();
+    }
+}
+//# sourceMappingURL=compact-read-lease.js.map

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

@@ -1,52 +1,7 @@
-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;
-}
+import { CompactContentIndex, type FrozenIndex } from "./compact-content-index.ts";
+import { type CompactMessageView, type FrozenBlock } from "./compact-text-view.ts";
+import { type CompactContentStoreOptions, type CompactStorageStatus } from "./compact-content-store.ts";
+import { type CompactPersistence, type CompactTransition } from "./compact-transition.ts";
 interface SettledRow {
     readonly persistence: CompactPersistence;
     readonly blocks: readonly FrozenBlock[];
@@ -54,16 +9,11 @@ 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;
-    readonly persistence: CompactPersistence | undefined;
-    readonly blocks: readonly {
-        readonly contentIndex: number;
-        readonly kind: CompactBlockKind;
-        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;
@@ -71,7 +21,8 @@ export declare class CompactSessionState {
     private readonly active;
     private sequence;
     private frozenTailBytes;
-    constructor(options: CompactContentStoreOptions);
+    private readonly cuts;
+    constructor(options: CompactSessionStateOptions);
     get acceptedSequence(): number;
     accept(transition: CompactTransition): number;
     freeze(): FrozenCompactState;
@@ -81,13 +32,14 @@ export declare class CompactSessionState {
         sequence: number;
         messages: CompactMessageView[];
     }>;
-    storageStatus(): CompactStorageStatus & {
+    private cutLease;
+    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;
+        readonly residentTextNodes: number;
+        readonly residentTextIndexBytes: number;
     };
     idle(): Promise<void>;
     retire(): Promise<void>;
@@ -105,7 +57,6 @@ export declare class CompactSessionState {
     /** 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

@@ -1,24 +1,25 @@
+import { CompactContentIndex } from "./compact-content-index.js";
+import { CompactReadError, CompactReadLease } from "./compact-read-lease.js";
+import { readCompactBlocks } from "./compact-text-view.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.cuts = new WeakMap();
         this.store = new CompactContentStore(options);
+        const leavesOf = (row) => row.blocks.map((block) => block.root);
+        this.settled = new CompactContentIndex(this.store, leavesOf, options.compactAboveRows ?? 128);
     }
     get acceptedSequence() {
         return this.sequence;
     }
     accept(transition) {
+        if (transition.type !== "message_remove")
+            this.store.assertReadable();
         switch (transition.type) {
             case "block_start":
                 this.start(transition);
@@ -39,32 +40,56 @@ export class CompactSessionState {
         return ++this.sequence;
     }
     freeze() {
+        this.store.assertReadable();
         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 };
+        const frozen = { sequence: this.sequence, active, settled: this.settled.freeze() };
+        this.cuts.set(frozen, new CompactReadLease(() => {
+            for (const blocks of frozen.active.values())
+                this.pin(blocks, -1);
+            this.settled.release(frozen.settled);
+        }));
+        return frozen;
     }
     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.cutLease(frozen).release();
     }
     /** 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 };
+        const lease = this.cutLease(frozen);
+        const valid = () => {
+            lease.assert();
+            this.store.assertReadable();
+        };
+        valid();
+        return lease.run(async () => {
+            const messages = [];
+            for (const [messageId, row] of await this.settled.entries(frozen.settled)) {
+                messages.push({
+                    messageId,
+                    persistence: row.persistence,
+                    blocks: await readCompactBlocks(this.store.text, row.blocks, valid),
+                });
+            }
+            for (const [messageId, blocks] of frozen.active) {
+                messages.push({
+                    messageId,
+                    persistence: undefined,
+                    blocks: await readCompactBlocks(this.store.text, blocks, valid),
+                });
+            }
+            valid();
+            return { sequence: frozen.sequence, messages };
+        });
+    }
+    cutLease(frozen) {
+        const lease = this.cuts.get(frozen);
+        if (!lease)
+            throw new CompactReadError("ownership");
+        return lease;
     }
     storageStatus() {
         let residentTailBytes = 0;
@@ -77,10 +102,13 @@ export class CompactSessionState {
         }
         return {
             ...this.store.status(),
+            ...this.settled.status(),
             residentTailBytes,
             frozenTailBytes: this.frozenTailBytes,
             hotWitnessBytes,
-            residentSettledRows: this.settled.size,
+            residentTextNodes: this.store.text.residentNodes,
+            // Fixed accounting charge for node headers, two edges and pending dependency bookkeeping.
+            residentTextIndexBytes: this.store.text.residentNodes * 192,
         };
     }
     idle() {
@@ -98,7 +126,7 @@ export class CompactSessionState {
             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: "" };
+        const block = { kind: t.kind, root: 0, 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();
@@ -124,8 +152,8 @@ export class CompactSessionState {
             block.witness = "";
     }
     replace(block, text) {
-        for (const id of block.leaves.splice(0))
-            this.store.adjust(id, -1, 0);
+        this.store.adjust(block.root, -1, 0);
+        block.root = 0;
         block.tail = "";
         block.units = 0;
         block.covered = 0;
@@ -137,12 +165,12 @@ 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())
+                this.store.adjust(block.root, -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 +178,14 @@ 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.store.adjust(block.root, -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);
@@ -173,7 +198,7 @@ export class CompactSessionState {
         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.root = this.store.text.append(block.root, block.tail + rest.slice(0, take));
             block.tail = "";
             rest = rest.slice(take);
         }
@@ -183,24 +208,17 @@ export class CompactSessionState {
     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.root = this.store.text.append(block.root, block.tail);
                 block.tail = "";
             }
-            return { contentIndex, kind: block.kind, leaves: [...block.leaves], tail: block.tail };
+            return { contentIndex, kind: block.kind, root: block.root, 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);
+            this.store.adjust(block.root, 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

@@ -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,58 @@
+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;
+    private reads;
+    private reading;
+    assertReadable(): void;
+    beginRead(): () => void;
+    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>;
+    private readCommittedFile;
+    /** 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