@noopolis/daimon 0.1.2 → 0.2.1

package/dist/runtime/wakeFuse.js

@@ -0,0 +1,466 @@
+import { constants } from "node:fs";
+import { open, readFile, readdir, rename, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { resolveTurnUsageLedgerPath, TURN_USAGE_LEDGER, TURN_USAGE_MAX_IDENTIFIER_CHARS, TURN_USAGE_ROTATE_BYTES } from "./turnUsageLedger.js";
+export const WAKE_FUSE_VERSION = "noopolis.daimon.wake-fuse.v1";
+export const WAKE_FUSE_DIRECTORY_ENV = "DAIMON_WAKE_FUSE_DIRECTORY";
+export const WAKE_FUSE_EPOCH_ZONE_ENV = "DAIMON_WAKE_FUSE_EPOCH_ZONE";
+export const DEFAULT_WAKE_FUSE_MAX_WAKES = 100;
+export const DEFAULT_WAKE_FUSE_MAX_TOKENS = 5_000_000;
+/**
+ * The counting window, when the operator has not named one.
+ *
+ * WHY THIS IS DERIVED AND NOT CONFIGURED
+ * --------------------------------------
+ * `DAIMON_WAKE_FUSE_EPOCH` is read from the container's env file, and an env
+ * file is applied at container CREATION only. So an operator who wants a daily
+ * budget has to rewrite that file and RECREATE THE CONTAINER every day, and
+ * the only thing that ever did that was a daily rebuild. The budget was
+ * therefore coupled to a deploy: stop deploying daily and the wake ceiling
+ * never resets, and the organization stops admitting wakes for good.
+ *
+ * A date-derived epoch removes the coupling instead of moving it. There is no
+ * file to rewrite, no deploy, no restart, and no clock for anybody to forget.
+ *
+ * An explicitly configured epoch still wins, unchanged: an operator pinning one
+ * window is doing it deliberately, and this must not roll it out from under
+ * them.
+ */
+export function derivedEpoch(organizationKey, at, zone) {
+    // `en-CA` renders ISO-8601 (YYYY-MM-DD), which is what makes this sortable
+    // and stable; the zone is what makes "a day" mean the operator's day.
+    const day = new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(at);
+    return `organization-${createHash("sha256").update(organizationKey).digest("hex")}-${day}`;
+}
+const TRIP_MARKER = "fuse.trip.json";
+let warnedDisarmed = false;
+/**
+ * Durable catastrophic-wake admission fuse for one organization/container.
+ *
+ * Operator trip: `docker exec <container> touch /var/lib/spawnfile/daimon/usage/fuse.stop`.
+ * Unlike `recordTurnUsage` ("advisory: never rejects"), every storage or
+ * evaluation failure here rejects admission: this safety boundary fails closed.
+ */
+export class WakeFuse {
+    armed;
+    directory;
+    epoch;
+    epochStartedAt;
+    maxWakes;
+    maxTokens;
+    admissions;
+    usageLedgerPath;
+    now;
+    nextEpoch;
+    serial = Promise.resolve();
+    reason;
+    tripMarkerMissing = false;
+    constructor(armed, directory, epoch, epochStartedAt, maxWakes, maxTokens, admissions, usageLedgerPath, now, nextEpoch) {
+        this.armed = armed;
+        this.directory = directory;
+        this.epoch = epoch;
+        this.epochStartedAt = epochStartedAt;
+        this.maxWakes = maxWakes;
+        this.maxTokens = maxTokens;
+        this.admissions = admissions;
+        this.usageLedgerPath = usageLedgerPath;
+        this.now = now;
+        this.nextEpoch = nextEpoch;
+    }
+    static async open(options) {
+        const environment = options.environment ?? process.env;
+        const setting = environment.DAIMON_WAKE_FUSE;
+        if (setting !== undefined && setting !== "off")
+            throw new Error("DAIMON_WAKE_FUSE must be exactly 'off' when set");
+        if (environment.DAIMON_WAKE_FUSE_EPOCH !== undefined && nonBlank(environment.DAIMON_WAKE_FUSE_EPOCH) === undefined)
+            throw new Error("DAIMON_WAKE_FUSE_EPOCH must be non-blank");
+        const pinned = nonBlank(environment.DAIMON_WAKE_FUSE_EPOCH);
+        const zone = nonBlank(environment[WAKE_FUSE_EPOCH_ZONE_ENV]) ?? "UTC";
+        // A pinned epoch never rolls; a derived one rolls with the operator's day.
+        // Agent ids are the stable organization identity available to Daimon.
+        const nextEpoch = (at) => pinned ?? derivedEpoch(options.organizationKey, at, zone);
+        const maxWakes = ceiling(environment.DAIMON_WAKE_FUSE_MAX_WAKES, DEFAULT_WAKE_FUSE_MAX_WAKES, "DAIMON_WAKE_FUSE_MAX_WAKES");
+        const maxTokens = ceiling(environment.DAIMON_WAKE_FUSE_MAX_TOKENS, DEFAULT_WAKE_FUSE_MAX_TOKENS, "DAIMON_WAKE_FUSE_MAX_TOKENS");
+        const directory = resolveWakeFuseDirectory(environment);
+        const now = options.now ?? (() => new Date());
+        const epoch = nextEpoch(now());
+        const usageLedgerPath = resolveTurnUsageLedgerPath(environment);
+        if (setting === "off") {
+            if (!warnedDisarmed) {
+                warnedDisarmed = true;
+                console.error("DAIMON WAKE FUSE IS OFF: wake admission is unbounded");
+            }
+            return new WakeFuse(false, directory, epoch, now().toISOString(), maxWakes, maxTokens, new Set(), usageLedgerPath, now, nextEpoch);
+        }
+        // Unbounded defaults would reproduce exactly the failure this module prevents.
+        await readdir(directory);
+        await ensureUsageLedgerUsable(usageLedgerPath);
+        const records = await readFuseRecords(directory);
+        const existingStart = records.filter((record) => record.kind === "epoch_start" && record.epoch === epoch).at(-1);
+        const epochStartedAt = existingStart?.at ?? now().toISOString();
+        if (existingStart === undefined)
+            await append(directory, { v: WAKE_FUSE_VERSION, kind: "epoch_start", epoch, at: epochStartedAt });
+        const admissions = new Set(records
+            .filter((record) => record.kind === "admission" && record.epoch === epoch)
+            .map((record) => key(record.agent, record.delivery)));
+        const fuse = new WakeFuse(true, directory, epoch, epochStartedAt, maxWakes, maxTokens, admissions, usageLedgerPath, now, nextEpoch);
+        if (await exists(path.join(directory, "fuse.stop")))
+            fuse.reason = "operator_stop";
+        else
+            fuse.reason = await readTripMarker(directory, epoch);
+        return fuse;
+    }
+    admit(agentId, deliveryId, limits = {}) {
+        if (!this.armed)
+            return Promise.resolve({ state: "admitted" });
+        // One organization is one container/control-host process. This promise
+        // chain is organization-wide in-process serialization, not cross-process locking.
+        const result = this.serial.catch(() => undefined).then(async () => await this.admitNow(agentId, deliveryId, limits));
+        this.serial = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * The budget as the caller should act on it NOW — which means after the day
+     * has been allowed to roll.
+     *
+     * This is the gate the scheduler actually consults: `AttentionDispatcher.drain()`
+     * returns at `snapshot().state !== "available"` before it ever reaches
+     * `admit()`. Rolling only inside `admitNow` therefore never fired for an
+     * organization that had hit its ceiling — it stayed paused across midnight
+     * and only a process restart could renew the budget. The roll is serialized
+     * with admissions so a snapshot and an admission never see two windows.
+     */
+    async snapshot(agentId, limits = {}) {
+        const result = this.serial.catch(() => undefined).then(async () => {
+            if (this.armed)
+                await this.rollEpochIfDue();
+            return await this.snapshotNow(agentId, limits);
+        });
+        this.serial = result.then(() => undefined, () => undefined);
+        return await result;
+    }
+    async snapshotNow(agentId, limits = {}) {
+        const used = this.admissions.size;
+        const agentUsed = [...this.admissions].filter((entry) => entry.startsWith(`${bounded(agentId)}\u0000`)).length;
+        const tokens = this.armed ? await sumTokens(this.usageLedgerPath, this.epochStartedAt) : 0;
+        const agentTokens = this.armed ? await sumTokens(this.usageLedgerPath, this.epochStartedAt, agentId) : 0;
+        const reason = this.reason ?? (this.armed ? used >= this.maxWakes ? "wake_ceiling" : tokens >= this.maxTokens ? "token_ceiling" : limits.maxExecutions !== undefined && agentUsed >= limits.maxExecutions ? "agent_execution_ceiling" : limits.maxTokens !== undefined && agentTokens >= limits.maxTokens ? "agent_token_ceiling" : undefined : undefined);
+        return { armed: this.armed, epoch: this.epoch, state: reason === undefined ? "available" : reason === "operator_stop" || reason === "ledger_unavailable" ? "stopped" : "paused", ...(reason === undefined ? {} : { reason }), executions_used: used, executions_remaining: Math.max(0, this.maxWakes - used), tokens_used: tokens, tokens_remaining: Math.max(0, this.maxTokens - tokens), agent_executions_used: agentUsed, agent_tokens_used: agentTokens, ...(limits.maxExecutions === undefined ? {} : { agent_executions_remaining: Math.max(0, limits.maxExecutions - agentUsed) }), ...(limits.maxTokens === undefined ? {} : { agent_tokens_remaining: Math.max(0, limits.maxTokens - agentTokens) }) };
+    }
+    async pollOperatorStop() {
+        if (!this.armed || this.reason === "operator_stop" || this.reason === "ledger_unavailable")
+            return this.reason;
+        try {
+            if (await exists(path.join(this.directory, "fuse.stop")))
+                await this.trip("operator_stop");
+        }
+        catch {
+            await this.trip("ledger_unavailable");
+        }
+        return this.reason;
+    }
+    tripped() { return this.reason; }
+    async close() { await this.serial; }
+    /**
+     * Moves the counting window when the derived day has changed.
+     *
+     * Called at admission, which is the only moment the answer can matter: the
+     * organization runtime is a long-lived process, so an epoch computed once at
+     * open() would be the same epoch a week later.
+     *
+     * WHAT ROLLS AND WHAT DOES NOT
+     * ----------------------------
+     * A new window clears a CEILING trip, exactly as selecting a new epoch by
+     * hand always did: `readTripMarker` only honours a marker belonging to the
+     * current epoch. It does NOT clear an operator stop. `fuse.stop` is checked
+     * by existence and is deliberately not epoch-scoped, so a parked newsroom
+     * stays parked across midnight. That asymmetry is the whole point: a budget
+     * is a thing that renews, an operator stop is a decision that does not.
+     *
+     * Admissions are rebuilt from the ledger rather than emptied, so a clock that
+     * steps BACKWARD into a window that already spent wakes does not hand the
+     * organization a fresh budget.
+     */
+    async rollEpochIfDue() {
+        const wanted = this.nextEpoch(this.now());
+        if (wanted === this.epoch)
+            return;
+        const records = await readFuseRecords(this.directory);
+        const existingStart = records.filter((record) => record.kind === "epoch_start" && record.epoch === wanted).at(-1);
+        const startedAt = existingStart?.at ?? this.now().toISOString();
+        if (existingStart === undefined)
+            await append(this.directory, { v: WAKE_FUSE_VERSION, kind: "epoch_start", epoch: wanted, at: startedAt });
+        this.epoch = wanted;
+        this.epochStartedAt = startedAt;
+        this.admissions = new Set(records
+            .filter((record) => record.kind === "admission" && record.epoch === wanted)
+            .map((record) => key(record.agent, record.delivery)));
+        // Re-evaluate the trip for the NEW window. Clearing a CEILING is the part
+        // that does work here, and it is what makes the budget renew.
+        //
+        // The operator-stop branch is deliberately BELT AND BRACES, not the guard:
+        // `admitNow` checks `fuse.stop` itself on every admission, unscoped by
+        // epoch, and `trip()` sets the reason — so a park is already enforced
+        // whatever this line does. I could not write a failing test for it, and
+        // said so rather than dressing it up as a guarantee. It stays because it
+        // keeps the object's own state coherent at the moment it rolls; the test
+        // above pins the BEHAVIOUR, which is what must not regress.
+        this.reason = await exists(path.join(this.directory, "fuse.stop")) ? "operator_stop" : await readTripMarker(this.directory, wanted);
+    }
+    async admitNow(agentId, deliveryId, limits) {
+        // Before the trip is consulted: a new day may have cleared a ceiling.
+        await this.rollEpochIfDue();
+        if (this.reason !== undefined)
+            return await this.trip(this.reason);
+        try {
+            if (await exists(path.join(this.directory, "fuse.stop")))
+                return await this.trip("operator_stop");
+            const admissionKey = key(bounded(agentId), bounded(deliveryId));
+            if (this.admissions.has(admissionKey))
+                return { state: "admitted" };
+            const budget = await this.snapshotNow(agentId, limits);
+            if (budget.agent_executions_remaining === 0)
+                return { state: "paused", reason: "agent_execution_ceiling" };
+            if (budget.agent_tokens_remaining === 0)
+                return { state: "paused", reason: "agent_token_ceiling" };
+            if (this.admissions.size >= this.maxWakes)
+                return await this.trip("wake_ceiling");
+            // Lagging indicator: usage is written after turn completion, so in-flight
+            // spend can overshoot by one concurrent round. The wake ceiling bounds it;
+            // design §5.2 owns the later pre-spawn reservation.
+            if (await sumTokens(this.usageLedgerPath, this.epochStartedAt) >= this.maxTokens)
+                return await this.trip("token_ceiling");
+            const record = { v: WAKE_FUSE_VERSION, kind: "admission", epoch: this.epoch, at: this.now().toISOString(), agent: bounded(agentId), delivery: bounded(deliveryId) };
+            await append(this.directory, record);
+            this.admissions.add(admissionKey);
+            return { state: "admitted" };
+        }
+        catch {
+            return await this.trip("ledger_unavailable");
+        }
+    }
+    async trip(reason) {
+        if (this.reason === undefined || (reason === "operator_stop" || reason === "ledger_unavailable") && this.reason !== "operator_stop" && this.reason !== "ledger_unavailable") {
+            this.reason = reason;
+            this.tripMarkerMissing = true;
+        }
+        if (this.tripMarkerMissing) {
+            try {
+                await writeTripMarker(this.directory, { v: WAKE_FUSE_VERSION, kind: "trip", epoch: this.epoch, at: this.now().toISOString(), reason: this.reason });
+                this.tripMarkerMissing = false;
+            }
+            catch {
+                // Keep the in-memory fuse closed and retry durability on every later
+                // admit/trip. Marker I/O must never turn a tripped verdict into an
+                // unhandled rejection at the HTTP boundary.
+            }
+        }
+        return { state: "tripped", reason: this.reason };
+    }
+}
+export function resolveWakeFuseDirectory(environment = process.env) {
+    const override = environment[WAKE_FUSE_DIRECTORY_ENV]?.trim();
+    return override !== undefined && override.startsWith("/") ? override : TURN_USAGE_LEDGER.directoryPath;
+}
+function ceiling(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return parsed;
+}
+function nonBlank(value) { const trimmed = value?.trim(); return trimmed ? trimmed : undefined; }
+function bounded(value) { return [...value].slice(0, TURN_USAGE_MAX_IDENTIFIER_CHARS).join(""); }
+function key(agent, delivery) { return `${agent}\u0000${delivery}`; }
+function admissionsPath(directory) { return path.join(directory, "admissions.jsonl"); }
+async function append(directory, record) {
+    const file = admissionsPath(directory);
+    try {
+        if ((await stat(file)).size >= TURN_USAGE_ROTATE_BYTES)
+            await rename(file, `${file}.1`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const bytes = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+    const handle = await open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+    try {
+        const result = await handle.write(bytes, 0, bytes.length);
+        if (result.bytesWritten !== bytes.length)
+            throw new Error("wake fuse admission append was torn");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectory(directory);
+}
+async function syncDirectory(directory) { const handle = await open(directory, constants.O_RDONLY); try {
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} }
+async function readFuseRecords(directory) {
+    const records = [];
+    for (const file of [`${admissionsPath(directory)}.1`, admissionsPath(directory)]) {
+        for (const line of await lines(file)) {
+            try {
+                const value = JSON.parse(line);
+                if (value.v !== WAKE_FUSE_VERSION || typeof value.epoch !== "string" || typeof value.at !== "string" || Number.isNaN(Date.parse(value.at)))
+                    continue;
+                if (value.kind === "epoch_start")
+                    records.push(value);
+                else if (value.kind === "admission" && typeof value.agent === "string" && typeof value.delivery === "string")
+                    records.push(value);
+            }
+            catch { /* malformed historical fuse lines do not count */ }
+        }
+    }
+    return records;
+}
+async function sumTokens(ledgerPath, since, agentId) {
+    let total = 0;
+    // Rows carrying a `turn` idempotency key count once per turn, whichever file holds them.
+    const turns = new Set();
+    for (const file of [`${ledgerPath}.1`, ledgerPath]) {
+        for (const line of await lines(file)) {
+            try {
+                const value = JSON.parse(line);
+                // Evaluator inference rows belong to their own ledger; one here (a misconfigured path) is never subject spend.
+                if (value.kind === "inference")
+                    continue;
+                if (typeof value.turn === "string") {
+                    if (turns.has(value.turn))
+                        continue;
+                    turns.add(value.turn);
+                }
+                if ((agentId === undefined || value.agent === agentId) && typeof value.at === "string" && !Number.isNaN(Date.parse(value.at)) && value.at >= since && typeof value.total === "number" && Number.isFinite(value.total) && value.total >= 0)
+                    total += value.total;
+            }
+            catch { /* usage accounting is advisory input; malformed lines are skipped */ }
+        }
+    }
+    return total;
+}
+async function writeTripMarker(directory, marker) {
+    const target = path.join(directory, TRIP_MARKER);
+    const temporary = path.join(directory, `.${TRIP_MARKER}.${process.pid}.${randomUUID()}`);
+    const bytes = Buffer.from(`${JSON.stringify(marker)}\n`, "utf8");
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+        try {
+            const result = await handle.write(bytes, 0, bytes.length);
+            if (result.bytesWritten !== bytes.length)
+                throw new Error("wake fuse trip marker write was torn");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, target);
+        await syncDirectory(directory);
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function readTripMarker(directory, epoch) {
+    try {
+        const value = JSON.parse(await readFile(path.join(directory, TRIP_MARKER), "utf8"));
+        if (value.v !== WAKE_FUSE_VERSION || value.kind !== "trip" || typeof value.epoch !== "string" || typeof value.at !== "string" || Number.isNaN(Date.parse(value.at)) || !isTripReason(value.reason))
+            return "ledger_unavailable";
+        // A valid marker belongs to one explicit counting window. Selecting a new
+        // epoch deliberately clears it; a corrupt marker cannot prove that and fails closed.
+        return value.epoch === epoch ? value.reason : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return "ledger_unavailable";
+    }
+}
+function isTripReason(value) { return value === "wake_ceiling" || value === "token_ceiling" || value === "operator_stop" || value === "ledger_unavailable"; }
+async function lines(file) { try {
+    return (await readFile(file, "utf8")).split("\n").filter(Boolean);
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return [];
+    throw error;
+} }
+/**
+ * An unenforceable usage ledger at arm time must never degrade to a silent
+ * zero. `sumTokens` (used on every later `admit`) deliberately treats a
+ * missing ledger as an empty one — if the ledger is deleted mid-epoch, the
+ * fuse still needs to keep functioning rather than wedge the organization —
+ * but that same tolerance is exactly how a 17.6M-token run passed a 5M
+ * ceiling untouched: the ledger was never created at all, so every sum read
+ * zero and the ceiling never had anything to compare against.
+ *
+ * Four states, distinguished by what actually makes the ceiling
+ * unenforceable versus merely unwritten yet:
+ *  - The ledger directory is missing, or present but not writable by this
+ *    uid: the ceiling is genuinely unenforceable. Fails loudly, the same
+ *    treatment `readdir(directory)` above already gives a missing
+ *    admissions directory.
+ *  - The directory is present and writable but the ledger file itself is
+ *    absent: Spawnfile's entrypoint provisions and chows the directory as a
+ *    persistent volume before the first turn ever writes usage
+ *    (`renderDaimonUsageLedgerProvisioning`), so a brand-new organization
+ *    legitimately has zero recorded spend. That is a true zero, not an
+ *    unknown one — but only once this durably creates the (empty) ledger
+ *    itself and verifies the result is readable, rather than assuming a
+ *    missing file means zero.
+ *  - The ledger file exists and is readable: arm normally; `sumTokens` sums
+ *    whatever is in it.
+ *  - The ledger file exists but is unreadable (EACCES, EISDIR, ...): fails
+ *    loudly, exactly as before.
+ */
+async function ensureUsageLedgerUsable(ledgerPath) {
+    try {
+        await readFile(ledgerPath, "utf8");
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing or unreadable (${code ?? String(error)}); refusing to admit wakes against an unenforceable token ceiling`);
+        }
+    }
+    // Ledger file absent. Create it empty, matching the mode the broker itself
+    // writes usage records with, so a fresh organization can start.
+    try {
+        const handle = await open(ledgerPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, TURN_USAGE_LEDGER.fileMode);
+        await handle.close();
+    }
+    catch (error) {
+        const code = error.code;
+        // EEXIST means a concurrent writer created it first (e.g. a racing turn
+        // append); that is not a creation failure, so fall through to verify.
+        if (code !== "EEXIST") {
+            throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing and could not be created (${code ?? String(error)}); refusing to admit wakes against an unenforceable token ceiling`);
+        }
+    }
+    // Never assume the create succeeded: read the file back before treating
+    // the ceiling as enforceable.
+    try {
+        await readFile(ledgerPath, "utf8");
+    }
+    catch (error) {
+        const code = error.code ?? String(error);
+        throw new Error(`DAIMON_WAKE_FUSE cannot start: usage ledger at ${ledgerPath} is missing or unreadable (${code}); refusing to admit wakes against an unenforceable token ceiling`);
+    }
+}
+async function exists(file) { try {
+    await stat(file);
+    return true;
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return false;
+    throw error;
+} }

package/dist/runtime/wakeMomentFs.d.ts

@@ -0,0 +1,27 @@
+import { type FileHandle } from "node:fs/promises";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+export { WakeMomentFault } from "./wakeMomentIo.js";
+/** Diagnostics never include source paths, file contents, or arbitrary exception text. */
+export declare function wakeMomentFailure(error: unknown): string;
+export type MomentStore = {
+    verify(io: WakeMomentIo, target?: string): Promise<void>;
+    close(): Promise<void>;
+};
+/** Pin the caller's root, then re-check the same dev/ino/uid/mode at every write boundary. */
+export declare function pinMomentStore(directory: string, io: WakeMomentIo, verifyPrepared?: () => Promise<void>): Promise<MomentStore>;
+export declare function openMomentDirectory(directory: string, io?: WakeMomentIo): Promise<FileHandle>;
+export declare function ensureMomentDirectory(directory: string, io?: WakeMomentIo): Promise<void>;
+export declare function syncMomentDirectory(directory: string, io?: WakeMomentIo): Promise<void>;
+/** Refuses symlinks, special files and hard-linked metadata, including a FIFO before it can block. */
+export declare function openMomentFile(file: string, flags?: number, io?: WakeMomentIo): Promise<FileHandle>;
+export declare function manifestBytes(value: unknown, max?: number): string;
+export declare function readMomentJson(file: string, io?: WakeMomentIo, max?: number): Promise<unknown>;
+/** Unlike FileHandle.writeFile, each syscall is admitted through the cancellation fence. */
+export declare function writeMomentBytes(fd: FileHandle, bytes: string | Buffer): Promise<void>;
+export declare function writeMomentJson(file: string, bytes: string, io: WakeMomentIo, cleanup: Set<string>, verifyReplacement?: () => Promise<void>): Promise<void>;
+export declare function momentPathExists(target: string, io?: WakeMomentIo): Promise<boolean>;
+/** Never recurse until root identity AND the target's parent components have just been verified. */
+export declare function cleanMomentPaths(paths: Set<string>, store: MomentStore, io: WakeMomentIo): Promise<void>;
+/** Explicit traversal keeps recursive cleanup cancellable between individual filesystem calls. */
+export declare function removeMomentPath(target: string, store: MomentStore, io: WakeMomentIo): Promise<void>;
+//# sourceMappingURL=wakeMomentFs.d.ts.map

package/dist/runtime/wakeMomentFs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentFs.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentFs.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKzD,OAAO,EAAmB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIxD;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAE/G,8FAA8F;AAC9F,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CA0BpI;AAMD,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAKzG;AAED,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrG;AAED,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnG;AAED,sGAAsG;AACtG,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAqB,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAO3H;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAoC,MAAM,GAAG,MAAM,CAInG;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,eAAqB,EAAE,GAAG,GAAoC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiB3I;AAED,4FAA4F;AAC5F,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5F;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjK;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhG;AAED,oGAAoG;AACpG,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9G;AAED,kGAAkG;AAClG,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAc1G"}