@saihm/shm 0.0.0-stage → 0.38.1

package/dist/store/index_snapshot.js

@@ -0,0 +1,126 @@
+export const INDEX_PART_NAME = "index.rows";
+const MAGIC = Buffer.from("SHMIDX1\n", "ascii");
+const MAX_HEADER_BYTES = 4096;
+const HASH_BYTES = 32;
+const HEX64 = /^[0-9a-f]{64}$/;
+export class IndexPartError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IndexPartError";
+    }
+}
+export function encodeIndexPart(rows, space) {
+    if (typeof space.modelId !== "string" || space.modelId === "")
+        throw new IndexPartError("the space has no model id");
+    if (!Number.isSafeInteger(space.dim) || space.dim < 1 || space.dim > 65_536)
+        throw new IndexPartError("the space's dimension is not a whole number from 1 to 65536");
+    const header = Buffer.from(JSON.stringify({ v: 1, modelId: space.modelId, dim: space.dim, count: rows.length }), "utf8");
+    if (header.length > MAX_HEADER_BYTES)
+        throw new IndexPartError(`the header is longer than ${MAX_HEADER_BYTES} bytes`);
+    const chunks = [MAGIC, u32(header.length), header];
+    for (const [i, r] of rows.entries()) {
+        const id = Buffer.from(r.cellId, "utf8");
+        const ns = Buffer.from(r.namespace, "utf8");
+        if (id.length === 0 || id.length > 0xffff)
+            throw new IndexPartError(`row ${i}: the cell id is empty or longer than 65535 bytes`);
+        if (ns.length > 0xffff)
+            throw new IndexPartError(`row ${i}: the namespace is longer than 65535 bytes`);
+        if (!HEX64.test(r.sourceHashHex))
+            throw new IndexPartError(`row ${i}: the source hash is not 64 lowercase hex`);
+        if (!Number.isFinite(r.epoch))
+            throw new IndexPartError(`row ${i}: the epoch is not a finite number`);
+        if (!Number.isInteger(r.flags) || r.flags < 0 || r.flags > 0xff)
+            throw new IndexPartError(`row ${i}: the flags are not one byte`);
+        if (r.vec.length !== space.dim)
+            throw new IndexPartError(`row ${i}: the vector has ${r.vec.length} components, the space ${space.dim}`);
+        const head = Buffer.alloc(2);
+        head.writeUInt16LE(id.length);
+        const mid = Buffer.alloc(HASH_BYTES + 8 + 2);
+        Buffer.from(r.sourceHashHex, "hex").copy(mid, 0);
+        mid.writeDoubleLE(r.epoch, HASH_BYTES);
+        mid.writeUInt16LE(ns.length, HASH_BYTES + 8);
+        const vec = Buffer.alloc(4 * space.dim);
+        for (let j = 0; j < space.dim; j++) {
+            const x = r.vec[j];
+            if (!Number.isFinite(x))
+                throw new IndexPartError(`row ${i}: the vector has a component that is not finite`);
+            vec.writeFloatLE(x, 4 * j);
+        }
+        chunks.push(head, id, mid, ns, Buffer.from([r.flags]), vec);
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+export function decodeIndexPart(bytes, expect) {
+    const no = (reason) => ({ ok: false, reason });
+    const b = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (b.length < MAGIC.length + 4 || !b.subarray(0, MAGIC.length).equals(MAGIC))
+        return no("not an index part (magic)");
+    const headerLen = b.readUInt32LE(MAGIC.length);
+    if (headerLen > MAX_HEADER_BYTES)
+        return no("the header is too long");
+    let at = MAGIC.length + 4;
+    if (at + headerLen > b.length)
+        return no("the header runs past the end");
+    let header;
+    try {
+        header = JSON.parse(b.subarray(at, at + headerLen).toString("utf8"));
+    }
+    catch {
+        return no("the header is not JSON");
+    }
+    at += headerLen;
+    if (typeof header !== "object" || header === null || Array.isArray(header))
+        return no("the header is not an object");
+    const h = header;
+    if (h["v"] !== 1)
+        return no("the header's version is not 1");
+    const modelId = h["modelId"], dim = h["dim"], count = h["count"];
+    if (typeof modelId !== "string" || !Number.isSafeInteger(dim) || !Number.isSafeInteger(count) || count < 0)
+        return no("the header's fields are malformed");
+    if (modelId !== expect.modelId || dim !== expect.dim)
+        return no(`made with another embedding space (${modelId}, ${String(dim)}) than this session's (${expect.modelId}, ${expect.dim})`);
+    const d = dim;
+    const rows = [];
+    for (let i = 0; i < count; i++) {
+        if (at + 2 > b.length)
+            return no(`row ${i} runs past the end`);
+        const idLen = b.readUInt16LE(at);
+        at += 2;
+        if (idLen === 0 || at + idLen + HASH_BYTES + 8 + 2 > b.length)
+            return no(`row ${i} runs past the end`);
+        const cellId = b.subarray(at, at + idLen).toString("utf8");
+        at += idLen;
+        const sourceHashHex = b.subarray(at, at + HASH_BYTES).toString("hex");
+        at += HASH_BYTES;
+        const epoch = b.readDoubleLE(at);
+        at += 8;
+        const nsLen = b.readUInt16LE(at);
+        at += 2;
+        if (at + nsLen + 1 + 4 * d > b.length)
+            return no(`row ${i} runs past the end`);
+        const namespace = b.subarray(at, at + nsLen).toString("utf8");
+        at += nsLen;
+        const flags = b.readUInt8(at);
+        at += 1;
+        const vec = new Float32Array(d);
+        for (let j = 0; j < d; j++) {
+            const x = b.readFloatLE(at + 4 * j);
+            if (!Number.isFinite(x))
+                return no(`row ${i}: a vector component is not finite`);
+            vec[j] = x;
+        }
+        at += 4 * d;
+        if (!Number.isFinite(epoch))
+            return no(`row ${i}: the epoch is not finite`);
+        rows.push({ cellId, sourceHashHex, epoch, namespace, flags, vec });
+    }
+    if (at !== b.length)
+        return no("bytes follow the last row");
+    return { ok: true, rows };
+}
+function u32(n) {
+    const out = Buffer.alloc(4);
+    out.writeUInt32LE(n);
+    return out;
+}
+//# sourceMappingURL=index_snapshot.js.map

package/dist/store/index_snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index_snapshot.js","sourceRoot":"","sources":["../../src/store/index_snapshot.ts"],"names":[],"mappings":"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"}

package/dist/store/mcp_warm_start.d.ts

@@ -0,0 +1,93 @@
+import type { McpToolCaller } from "../saihm_client/mcp_client.js";
+import type { WarmStart } from "./warm_start.js";
+export declare const WARM_START_DIRNAME = "warm-start";
+export declare const CALL_TOKEN: RegExp;
+export declare const putFileName: (token: string) => string;
+export declare const latestFileName: (token: string) => string;
+export declare function newCallToken(): string;
+export declare const DEFAULT_MAX_LATEST_BYTES: number;
+export type LocalCode = "shm_bad_argument" | "shm_dir_unsafe" | "shm_file_unsafe" | "shm_file_too_large" | "shm_file_missing" | "shm_answer_malformed" | "shm_residue" | "shm_io_error" | "shm_not_offered";
+export declare const LOCAL_CODES: readonly LocalCode[];
+export declare class McpWarmStartError extends Error {
+    readonly origin: "tool" | "local";
+    readonly code?: string;
+    constructor(message: string, origin: "tool" | "local", code: string | undefined, cause?: unknown);
+}
+export declare function codeFromToolText(text: string): string | undefined;
+export declare function codeFromErrorField(structured: unknown): string | undefined;
+export type ToolAnswer = {
+    readonly kind: "error";
+    readonly code: string | undefined;
+} | {
+    readonly kind: "object";
+    readonly value: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "null";
+} | {
+    readonly kind: "other";
+} | {
+    readonly kind: "malformed";
+};
+export declare function readToolAnswer(raw: unknown): ToolAnswer;
+export interface EntryStat {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+    readonly mode: number;
+    readonly uid: number;
+    readonly nlink: number;
+    readonly size: number;
+}
+export declare function warmDirProblem(st: Pick<EntryStat, "isDirectory" | "isSymbolicLink" | "mode" | "uid">, uid: number): string | null;
+export declare function latestFileProblem(st: EntryStat, uid: number, maxBytes: number): {
+    readonly code: "shm_file_unsafe" | "shm_file_too_large";
+    readonly what: string;
+} | null;
+export interface McpWarmStartConfig {
+    readonly callTool: McpToolCaller;
+    readonly agentIdHash: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly homeDir: string;
+    readonly status: unknown;
+    readonly maxLatestBytes?: number;
+    readonly newToken?: () => string;
+}
+export declare class McpWarmStart implements WarmStart {
+    readonly dir: string;
+    private readonly callTool;
+    private readonly uid;
+    private readonly maxLatestBytes;
+    private readonly newToken;
+    readonly notOffered: string | null;
+    constructor(cfg: McpWarmStartConfig);
+    private token;
+    put(payload: Uint8Array, opts: {
+        readonly coversThrough: string;
+    }): Promise<{
+        readonly snapshotId: string;
+        readonly createdAt: string;
+        readonly bytes: number;
+    }>;
+    latest(): Promise<{
+        readonly snapshotId: string;
+        readonly createdAt: string;
+        readonly coversThrough: string;
+        readonly payload: Uint8Array;
+    } | null>;
+    list(): Promise<ReadonlyArray<{
+        readonly snapshotId: string;
+        readonly createdAt: string;
+        readonly bytes: number;
+        readonly coversThrough: string;
+    }>>;
+    delete(snapshotId: string): Promise<void>;
+    private offered;
+    private call;
+    private thenRemove;
+    private prepareDir;
+    private writePut;
+    private removePutFiles;
+    private removeLatest;
+    private readLatest;
+}
+//# sourceMappingURL=mcp_warm_start.d.ts.map

package/dist/store/mcp_warm_start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_warm_start.d.ts","sourceRoot":"","sources":["../../src/store/mcp_warm_start.ts"],"names":[],"mappings":"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"}

package/dist/store/mcp_warm_start.js

@@ -0,0 +1,406 @@
+import { constants as bufferConstants } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, readdir, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { HEX64, resolveFeedPath } from "../erasure/feed_watcher.js";
+import { parseServerFeatures } from "../saihm_client/server_features.js";
+import { writeFileAtomic } from "./atomic_write.js";
+import { ensureStateDir } from "./state_dir.js";
+export const WARM_START_DIRNAME = "warm-start";
+export const CALL_TOKEN = /^[a-z0-9]{16,32}$/;
+export const putFileName = (token) => `put-${token}.bin`;
+export const latestFileName = (token) => `latest-${token}.bin`;
+const TOKEN_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+const TOKEN_LENGTH = 24;
+export function newCallToken() {
+    let out = "";
+    while (out.length < TOKEN_LENGTH) {
+        for (const b of randomBytes(TOKEN_LENGTH)) {
+            if (b < 252 && out.length < TOKEN_LENGTH)
+                out += TOKEN_ALPHABET[b % 36];
+        }
+    }
+    return out;
+}
+export const DEFAULT_MAX_LATEST_BYTES = 256 * 1024 * 1024;
+export const LOCAL_CODES = Object.freeze([
+    "shm_bad_argument",
+    "shm_dir_unsafe",
+    "shm_file_unsafe",
+    "shm_file_too_large",
+    "shm_file_missing",
+    "shm_answer_malformed",
+    "shm_residue",
+    "shm_io_error",
+    "shm_not_offered",
+]);
+export class McpWarmStartError extends Error {
+    origin;
+    code;
+    constructor(message, origin, code, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "McpWarmStartError";
+        this.origin = origin;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+const local = (code, message, cause) => new McpWarmStartError(message, "local", code, cause);
+const errno = (e) => {
+    const c = typeof e === "object" && e !== null ? e.code : undefined;
+    return typeof c === "string" ? c : undefined;
+};
+const SAIHM_ERROR_TEXT = /^SAIHM error \[([^\]]{0,64})\]/;
+const WIRE_CODE = /^[a-z][a-z_]{0,63}$/;
+export function codeFromToolText(text) {
+    const c = SAIHM_ERROR_TEXT.exec(text)?.[1];
+    return c !== undefined && WIRE_CODE.test(c) ? c : undefined;
+}
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function codeFromErrorField(structured) {
+    if (!isPlainObject(structured))
+        return undefined;
+    const err = structured["error"];
+    if (!isPlainObject(err))
+        return undefined;
+    const c = err["code"];
+    return typeof c === "string" && WIRE_CODE.test(c) ? c : undefined;
+}
+export function readToolAnswer(raw) {
+    if (raw === null)
+        return { kind: "null" };
+    if (!isPlainObject(raw))
+        return { kind: "other" };
+    const content = raw["content"];
+    if (!Array.isArray(content))
+        return { kind: "object", value: raw };
+    const isError = raw["isError"];
+    if (isError !== undefined && typeof isError !== "boolean")
+        return { kind: "malformed" };
+    const first = content.filter(isPlainObject).find((c) => c["type"] === "text" && typeof c["text"] === "string")?.["text"];
+    if (isError === true)
+        return { kind: "error", code: codeFromErrorField(raw["structuredContent"]) ?? (first === undefined ? undefined : codeFromToolText(first)) };
+    const structured = raw["structuredContent"];
+    if (structured !== undefined)
+        return isPlainObject(structured) ? { kind: "object", value: structured } : { kind: "malformed" };
+    if (first === undefined)
+        return { kind: "other" };
+    let parsed;
+    try {
+        parsed = JSON.parse(first);
+    }
+    catch {
+        return { kind: "other" };
+    }
+    if (parsed === null)
+        return { kind: "null" };
+    return isPlainObject(parsed) ? { kind: "object", value: parsed } : { kind: "other" };
+}
+export function warmDirProblem(st, uid) {
+    if (!st.isDirectory())
+        return st.isSymbolicLink() ? "is a symbolic link" : "is not a directory";
+    if (st.uid !== uid)
+        return "belongs to another account";
+    if ((st.mode & 0o077) !== 0)
+        return "is open to its group or to others";
+    return null;
+}
+export function latestFileProblem(st, uid, maxBytes) {
+    if (!st.isFile())
+        return { code: "shm_file_unsafe", what: st.isSymbolicLink() ? "is a symbolic link" : "is not a regular file" };
+    if (st.nlink > 1)
+        return { code: "shm_file_unsafe", what: "has another name (a hard link)" };
+    if (st.uid !== uid)
+        return { code: "shm_file_unsafe", what: "belongs to another account" };
+    if ((st.mode & 0o077) !== 0)
+        return { code: "shm_file_unsafe", what: "is open to its group or to others" };
+    if (st.size > maxBytes)
+        return { code: "shm_file_too_large", what: `is larger than ${maxBytes} bytes` };
+    return null;
+}
+const TOOL = { put: "saihm_remember", latest: "saihm_recall", list: "saihm_recall", delete: "saihm_forget" };
+const named = (op) => `${TOOL[op]} (warmStart ${op})`;
+const own = (o, k) => (Object.hasOwn(o, k) ? o[k] : undefined);
+const ISO_MS_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function isIsoMsUtc(v) {
+    if (typeof v !== "string" || !ISO_MS_UTC.test(v))
+        return false;
+    const t = Date.parse(v);
+    return Number.isFinite(t) && new Date(t).toISOString() === v;
+}
+const isSnapshotId = (v) => typeof v === "string" && HEX64.test(v);
+const isCursor = (v) => typeof v === "string" && v !== "";
+const isWhole = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+function field(o, op, at, key, ok, what) {
+    const v = own(o, key);
+    if (!ok(v))
+        throw local("shm_answer_malformed", `${named(op)}: ${at}${key} ${what}`);
+    return v;
+}
+const snapshotIdOf = (o, op, at = "") => field(o, op, at, "snapshotId", isSnapshotId, "is not 64 lowercase hex");
+const createdAtOf = (o, op, at = "") => field(o, op, at, "createdAt", isIsoMsUtc, "is not an ISO-8601 UTC time with milliseconds and Z");
+const bytesOf = (o, op, at = "") => field(o, op, at, "bytes", isWhole, "is not a whole number");
+const coversThroughOf = (o, op, at = "") => field(o, op, at, "coversThrough", isCursor, "is not a non-empty cursor");
+export class McpWarmStart {
+    dir;
+    callTool;
+    uid;
+    maxLatestBytes;
+    newToken;
+    notOffered;
+    constructor(cfg) {
+        if (typeof cfg.callTool !== "function")
+            throw new TypeError("McpWarmStart: callTool must be the host's MCP tool caller");
+        if (typeof cfg.agentIdHash !== "string" || !HEX64.test(cfg.agentIdHash))
+            throw new TypeError("McpWarmStart: agentIdHash must be 64 lowercase hex");
+        const tenant = dirname(resolveFeedPath({ identity: cfg.agentIdHash, env: cfg.env, homeDir: cfg.homeDir }));
+        if (!isAbsolute(tenant)) {
+            throw new TypeError("McpWarmStart: the tenant directory resolves to a relative path. The tool runs in another process, and a relative " +
+                "SAIHM_ERASURE_FEED_DIR, SAIHM_HOME or home directory names a different directory in each process's working directory.");
+        }
+        if (typeof process.getuid !== "function") {
+            throw new Error("McpWarmStart: this platform reports no POSIX owner, so the warm-start files' owner and mode cannot be judged");
+        }
+        const offer = parseServerFeatures(cfg.status).warmStart;
+        this.notOffered = offer.kind === "available" ? null : `features.warmStart is ${offer.kind}: ${offer.reason}`;
+        const offeredMax = offer.kind === "available" && offer.value.maxBytes >= 1 ? Math.min(offer.value.maxBytes, bufferConstants.MAX_LENGTH) : undefined;
+        const max = cfg.maxLatestBytes ?? offeredMax ?? DEFAULT_MAX_LATEST_BYTES;
+        if (!Number.isSafeInteger(max) || max < 1 || max > bufferConstants.MAX_LENGTH) {
+            throw new RangeError(`McpWarmStart: maxLatestBytes must be a whole number from 1 to ${bufferConstants.MAX_LENGTH}`);
+        }
+        this.callTool = cfg.callTool;
+        this.uid = process.getuid();
+        this.maxLatestBytes = max;
+        if (cfg.newToken !== undefined && typeof cfg.newToken !== "function")
+            throw new TypeError("McpWarmStart: newToken must be a function");
+        this.newToken = cfg.newToken ?? newCallToken;
+        this.dir = join(tenant, WARM_START_DIRNAME);
+    }
+    token() {
+        const t = this.newToken();
+        if (typeof t !== "string" || !CALL_TOKEN.test(t))
+            throw local("shm_bad_argument", "the call token is not 16 to 32 characters from a-z and 0-9");
+        return t;
+    }
+    async put(payload, opts) {
+        this.offered("put");
+        if (!(payload instanceof Uint8Array))
+            throw local("shm_bad_argument", "put: the payload must be bytes");
+        const coversThrough = opts?.coversThrough;
+        if (!isCursor(coversThrough))
+            throw local("shm_bad_argument", "put: coversThrough must be a non-empty cursor");
+        const token = this.token();
+        const putPath = join(this.dir, putFileName(token));
+        await this.prepareDir();
+        return this.thenRemove(async () => {
+            await this.writePut(putPath, payload);
+            const a = await this.call("put", { warmStart: "put", coversThrough, token });
+            if (a.kind !== "object")
+                throw local("shm_answer_malformed", `${named("put")}: the answer is not an object`);
+            return { snapshotId: snapshotIdOf(a.value, "put"), createdAt: createdAtOf(a.value, "put"), bytes: bytesOf(a.value, "put") };
+        }, () => this.removePutFiles(putFileName(token)));
+    }
+    async latest() {
+        this.offered("latest");
+        const token = this.token();
+        const latestPath = join(this.dir, latestFileName(token));
+        await this.prepareDir();
+        return this.thenRemove(async () => {
+            const a = await this.call("latest", { warmStart: "latest", token });
+            if (a.kind !== "object")
+                throw local("shm_answer_malformed", `${named("latest")}: the answer is not an object`);
+            const snap = own(a.value, "snapshot");
+            if (snap === null)
+                return null;
+            if (!isPlainObject(snap))
+                throw local("shm_answer_malformed", `${named("latest")}: snapshot is neither null nor an object`);
+            const meta = { snapshotId: snapshotIdOf(snap, "latest", "snapshot."), createdAt: createdAtOf(snap, "latest", "snapshot."), coversThrough: coversThroughOf(snap, "latest", "snapshot.") };
+            return { ...meta, payload: await this.readLatest(latestPath) };
+        }, () => this.removeLatest(latestPath));
+    }
+    async list() {
+        this.offered("list");
+        const a = await this.call("list", { warmStart: "list", token: this.token() });
+        if (a.kind !== "object")
+            throw local("shm_answer_malformed", `${named("list")}: the answer is not an object`);
+        const snapshots = own(a.value, "snapshots");
+        if (!Array.isArray(snapshots))
+            throw local("shm_answer_malformed", `${named("list")}: snapshots is not a list`);
+        const seen = new Set();
+        return snapshots.map((s, i) => {
+            const at = `snapshots[${i}].`;
+            if (!isPlainObject(s))
+                throw local("shm_answer_malformed", `${named("list")}: snapshots[${i}] is not an object`);
+            const entry = { snapshotId: snapshotIdOf(s, "list", at), createdAt: createdAtOf(s, "list", at), bytes: bytesOf(s, "list", at), coversThrough: coversThroughOf(s, "list", at) };
+            if (seen.has(entry.snapshotId))
+                throw local("shm_answer_malformed", `${named("list")}: ${at}snapshotId repeats`);
+            seen.add(entry.snapshotId);
+            return entry;
+        });
+    }
+    async delete(snapshotId) {
+        this.offered("delete");
+        if (!isSnapshotId(snapshotId))
+            throw local("shm_bad_argument", "delete: snapshotId must be 64 lowercase hex");
+        await this.call("delete", { warmStart: "delete", snapshotId, token: this.token() });
+    }
+    offered(op) {
+        if (this.notOffered !== null)
+            throw local("shm_not_offered", `${named(op)}: refused — ${this.notOffered}; warm start runs only where the server offers it`);
+    }
+    async call(op, args) {
+        let raw;
+        try {
+            raw = await this.callTool(TOOL[op], args);
+        }
+        catch (e) {
+            const text = typeof e === "string" ? e : typeof e === "object" && e !== null && typeof e.message === "string" ? e.message : undefined;
+            const code = text === undefined ? undefined : codeFromToolText(text);
+            throw new McpWarmStartError(`${named(op)}: the call threw${code === undefined ? "" : ` [${code}]`}`, "tool", code, e);
+        }
+        const a = readToolAnswer(raw);
+        if (a.kind === "error")
+            throw new McpWarmStartError(`${named(op)}: the tool answered with an error${a.code === undefined ? "" : ` [${a.code}]`}`, "tool", a.code);
+        if (a.kind === "malformed")
+            throw local("shm_answer_malformed", `${named(op)}: not a tool result (isError or structuredContent has the wrong type)`);
+        return a;
+    }
+    async thenRemove(body, remove) {
+        let outcome;
+        try {
+            outcome = { ok: true, value: await body() };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+        await remove();
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.value;
+    }
+    async prepareDir() {
+        let failure;
+        try {
+            await ensureStateDir("McpWarmStart", this.dir);
+        }
+        catch (e) {
+            failure = e;
+        }
+        let st;
+        try {
+            st = await lstat(this.dir);
+        }
+        catch (e) {
+            throw local("shm_io_error", `${this.dir} could not be created or examined`, failure ?? e);
+        }
+        const problem = warmDirProblem(st, this.uid);
+        if (problem !== null)
+            throw local("shm_dir_unsafe", `${this.dir} ${problem}: refused, and left as it is`);
+        if (failure !== undefined)
+            throw local("shm_io_error", `${this.dir} could not be prepared`, failure);
+    }
+    async writePut(putPath, payload) {
+        try {
+            await writeFileAtomic(putPath, payload);
+            const fh = await open(putPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+            try {
+                await fh.sync();
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch (e) {
+            throw local("shm_io_error", `${putPath} could not be written`, e);
+        }
+    }
+    async removePutFiles(putName) {
+        const tempPrefix = putName + ".tmp.";
+        let names;
+        try {
+            names = await readdir(this.dir);
+        }
+        catch (e) {
+            if (errno(e) === "ENOENT")
+                return;
+            throw local("shm_residue", `${this.dir} could not be listed, so ${putName} may remain there in plaintext`, e);
+        }
+        let failed = 0;
+        let first;
+        for (const name of names) {
+            if (name !== putName && !name.startsWith(tempPrefix))
+                continue;
+            try {
+                await unlink(join(this.dir, name));
+            }
+            catch (e) {
+                if (errno(e) === "ENOENT")
+                    continue;
+                failed++;
+                first ??= e;
+            }
+        }
+        if (failed > 0)
+            throw local("shm_residue", `${failed} put file(s) in ${this.dir} could not be removed and may hold SHM's state in plaintext`, first);
+    }
+    async removeLatest(latestPath) {
+        try {
+            await unlink(latestPath);
+        }
+        catch (e) {
+            if (errno(e) !== "ENOENT")
+                throw local("shm_residue", `${latestPath} could not be removed and may hold a snapshot in plaintext`, e);
+        }
+    }
+    async readLatest(latestPath) {
+        let st;
+        try {
+            st = await lstat(latestPath);
+        }
+        catch (e) {
+            if (errno(e) === "ENOENT")
+                throw local("shm_file_missing", `${named("latest")} named a snapshot, and ${latestPath} is not there`);
+            throw local("shm_io_error", `${latestPath} could not be examined`, e);
+        }
+        const problem = latestFileProblem(st, this.uid, this.maxLatestBytes);
+        if (problem !== null)
+            throw local(problem.code, `${latestPath} ${problem.what}: refused`);
+        let fh;
+        try {
+            fh = await open(latestPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+        }
+        catch (e) {
+            if (errno(e) === "ENOENT")
+                throw local("shm_file_missing", `${latestPath} went away before it was read`, e);
+            if (errno(e) === "ELOOP")
+                throw local("shm_file_unsafe", `${latestPath} became a symbolic link before it was read`, e);
+            throw local("shm_io_error", `${latestPath} could not be opened`, e);
+        }
+        try {
+            const opened = await fh.stat();
+            if (!opened.isFile() || opened.dev !== st.dev || opened.ino !== st.ino || opened.size !== st.size) {
+                throw local("shm_file_unsafe", `${latestPath} changed between the check and the read`);
+            }
+            const buf = Buffer.alloc(st.size);
+            let at = 0;
+            while (at < buf.byteLength) {
+                const { bytesRead } = await fh.read(buf, at, buf.byteLength - at, at);
+                if (bytesRead === 0)
+                    break;
+                at += bytesRead;
+            }
+            if (at !== buf.byteLength || (await fh.read(Buffer.alloc(1), 0, 1, at)).bytesRead !== 0) {
+                throw local("shm_file_unsafe", `${latestPath} changed size while it was read`);
+            }
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        catch (e) {
+            throw e instanceof McpWarmStartError ? e : local("shm_io_error", `${latestPath} could not be read`, e);
+        }
+        finally {
+            await fh.close();
+        }
+    }
+}
+//# sourceMappingURL=mcp_warm_start.js.map