@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/runtimeHomeLayout.js

@@ -0,0 +1,84 @@
+import { constants } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Mode for every directory Daimon creates inside an agent's runtime home.
+ *
+ * A brokered Grok agent's runtime home is `0710`
+ * (`GROK_ENGINE_BROKER.worker.home.organizationRuntimeHome`) so its sandboxed
+ * worker can traverse into the setgid `tool-output/` spill directory. Traverse
+ * is all it may have: anything Daimon creates in that home — telemetry traces
+ * (prompts, replies, world trajectories), tool state, receipts, the engine's
+ * XDG directories and the private `.tmp` — stays `0700`, so a default
+ * `mkdir` (0755 under the usual umask) never turns a traversable home into a
+ * readable one.
+ */
+export const RUNTIME_HOME_SUBDIRECTORY_MODE = 0o700;
+/**
+ * The home itself, created if it is absent and otherwise left exactly as it is.
+ *
+ * Create-only is the whole contract here. A brokered Grok agent's home is
+ * deliberately `0710` and an organization's may be `0700`; which of the two is
+ * correct is `physicalReadiness.ts`'s judgement, made against the agent's
+ * declared engine, and a layout helper that "corrected" a traversable home to
+ * `0700` would break the worker's only route to its own spills.
+ */
+export const ensureRuntimeHome = async (runtimeHomePath) => {
+    await mkdir(runtimeHomePath, { recursive: true, mode: RUNTIME_HOME_SUBDIRECTORY_MODE });
+    return runtimeHomePath;
+};
+/**
+ * One directory Daimon owns *below* a runtime home, private on every install.
+ *
+ * `mkdir(..., { mode })` decides nothing for a directory that already exists,
+ * and that is the common case rather than the exotic one: a `telemetry/` left
+ * at `0755` by a pre-branch Daimon, or pre-created by a deployment, stayed
+ * `0755` forever. Under a Grok agent's traversable `0710` home that is the
+ * worker reading its own agent's prompts, replies and causal history — the
+ * home is traverse-only precisely so that nothing but `tool-output/` is
+ * readable. `assertRuntimeDirectory` checks the home, and nothing checked what
+ * Daimon created inside it.
+ *
+ * So every level below the home is asserted and corrected on the way down,
+ * through a handle rather than a path: `O_DIRECTORY|O_NOFOLLOW` refuses a
+ * symlink planted where a directory belongs, and the `fchmod` that follows
+ * lands on the directory that was stat'd. A directory owned by anyone but the
+ * runtime user is **refused**, never widened and never silently accepted — the
+ * runtime cannot make someone else's directory private, and proceeding would
+ * write an agent's telemetry into it anyway.
+ *
+ * `owner` is a seam so both refusals are testable unprivileged, exactly as
+ * `physicalReadiness.ts`'s `RuntimeIdentity` is.
+ */
+export async function ensureRuntimeHomeDirectory(runtimeHomePath, relative, owner = process.getuid?.() ?? -1) {
+    const segments = relative.split("/").filter((segment) => segment.length > 0);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`runtime home subdirectory must name a path below the home: ${relative}`);
+    }
+    let current = await ensureRuntimeHome(runtimeHomePath);
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        await mkdir(current, { mode: RUNTIME_HOME_SUBDIRECTORY_MODE }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        await assertPrivateDirectory(current, owner);
+    }
+    return current;
+}
+const flag = (name) => constants[name] ?? 0;
+async function assertPrivateDirectory(directory, owner) {
+    const handle = await open(directory, constants.O_RDONLY | flag("O_DIRECTORY") | flag("O_NOFOLLOW"));
+    try {
+        const entry = await handle.stat();
+        if (!entry.isDirectory())
+            throw new Error(`runtime home path is not a directory: ${directory}`);
+        if (entry.uid !== owner)
+            throw new Error(`runtime home subdirectory must be owned by the runtime user: ${directory}`);
+        if ((entry.mode & 0o7777) !== RUNTIME_HOME_SUBDIRECTORY_MODE)
+            await handle.chmod(RUNTIME_HOME_SUBDIRECTORY_MODE);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/runtime/schedule.d.ts

@@ -0,0 +1,40 @@
+import type { OrganizationRuntimeAgentConfig, OrganizationRuntimeSchedule } from "./organizationRuntime.js";
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+export type ScheduledOccurrence = Readonly<{
+    agentId: string;
+    deliveryId: string;
+    occurredAt: string;
+    prompt: string;
+}>;
+type ActiveSchedule = Exclude<OrganizationRuntimeSchedule, {
+    kind: "disabled";
+}>;
+type Timer = ReturnType<typeof setTimeout>;
+export type ScheduleController = Readonly<{
+    start(): Promise<void>;
+    drain(agentId?: string): Promise<void>;
+    stop(): Promise<void>;
+}>;
+export type ScheduleControllerOptions = Readonly<{
+    acceptanceStorePath: string;
+    agents: readonly OrganizationRuntimeAgentConfig[];
+    /** False means the agent is busy; the durable latest-pending slot remains. */
+    accept(occurrence: ScheduledOccurrence): Promise<boolean | void>;
+    now?: () => number;
+    /** Draws the fractional jitter offset; defaults to `Math.random`. Injectable so tests can assert bounds/independence without real randomness. */
+    random?: () => number;
+    setTimer?: (callback: () => void, delayMs: number) => Timer;
+    clearTimer?: (timer: Timer) => void;
+    /** @internal Observable durability stages for focused crash-order tests. */
+    onPersistStageForTest?: (stage: "write" | "file-sync" | "rename" | "directory-sync") => void;
+}>;
+/** Schedules create durable pending occurrences; engine execution remains elsewhere. */
+export declare function createScheduleController(options: ScheduleControllerOptions): ScheduleController;
+export declare function occurrenceFor(agentId: string, schedule: ActiveSchedule, at: number): ScheduledOccurrence;
+export declare function isCanonicalScheduleDeliveryId(value: string): boolean;
+export declare function nextOccurrence(agentId: string, schedule: ActiveSchedule, anchor: number | undefined, from: number): number;
+export declare function cronIsPossible(cron: string): boolean;
+/** Independent per-arming offset in `[0, jitter_seconds * 1000]`; absent/zero jitter always yields exactly 0. */
+export declare function jitterOffsetMs(schedule: ActiveSchedule | undefined, random: () => number): number;
+export {};
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/runtime/schedule.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAK5G,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAKhD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AACxH,KAAK,cAAc,GAAG,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAGjF,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAAC;AACrI,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAClD,8EAA8E;IAC9E,MAAM,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iJAAiJ;IACjJ,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,gBAAgB,KAAK,IAAI,CAAC;CAC9F,CAAC,CAAC;AAEH,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CA8F/F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB,CAGxG;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAU1H;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAA8E;AAEnI,iHAAiH;AACjH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,GAAG,MAAM,CAKjG"}

package/dist/runtime/schedule.js

@@ -0,0 +1,371 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readFile, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+const STATE_VERSION = "noopolis.daimon.schedule-state.v1";
+const STATE_FILE = "schedule-state.v1.json";
+const MAX_STATE_BYTES = 256 * 1024;
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const SEARCH_HORIZON_MS = 64 * 366 * 86_400_000;
+const MAX_SEARCH_CHECKS = 1_000_000;
+const CRON_FIELD_BOUNDS = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+/** Schedules create durable pending occurrences; engine execution remains elsewhere. */
+export function createScheduleController(options) {
+    const now = options.now ?? Date.now;
+    const random = options.random ?? Math.random;
+    const setTimer = options.setTimer ?? ((callback, delay) => setTimeout(callback, delay));
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    const statePath = path.join(options.acceptanceStorePath, STATE_FILE);
+    const active = options.agents.filter((agent) => agent.schedule && agent.schedule.kind !== "disabled");
+    const byKey = new Map(active.map((agent) => [identity(agent.id, agent.schedule), agent]));
+    const timers = new Map();
+    let directory;
+    let state = { version: STATE_VERSION, schedules: {} };
+    let mutations = Promise.resolve();
+    let stopped = false;
+    const enqueue = (operation) => {
+        const result = mutations.catch(() => undefined).then(operation);
+        mutations = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const save = async () => {
+        if (directory === undefined)
+            throw new Error("schedule state directory is unavailable");
+        await persist(statePath, state, directory, options.onPersistStageForTest);
+    };
+    const nextEntry = (agent, anchor, observedNow, latest_pending) => {
+        const next_due_ms = nextOccurrence(agent.id, agent.schedule, anchor, observedNow);
+        return withFireTarget({ next_due_ms, ...(latest_pending === undefined ? {} : { latest_pending }) }, agent.schedule, random);
+    };
+    const arm = (key) => {
+        const prior = timers.get(key);
+        if (prior !== undefined)
+            clearTimer(prior);
+        if (stopped)
+            return;
+        const entry = state.schedules[key];
+        if (entry === undefined)
+            return;
+        const target = entry.fire_at_ms ?? entry.next_due_ms;
+        const delay = Math.min(MAX_TIMER_DELAY_MS, Math.max(0, target - now()));
+        const timer = setTimer(() => { void enqueue(async () => await onTimer(key)); }, delay);
+        timer.unref?.();
+        timers.set(key, timer);
+    };
+    const drainKey = async (key) => {
+        if (stopped)
+            return;
+        const pending = state.schedules[key]?.latest_pending;
+        if (pending === undefined)
+            return;
+        const accepted = await options.accept(pending);
+        if (accepted === false || stopped)
+            return;
+        const current = state.schedules[key];
+        if (current?.latest_pending?.deliveryId !== pending.deliveryId)
+            return;
+        state = { ...state, schedules: { ...state.schedules, [key]: withoutPending(current) } };
+        await save();
+    };
+    const onTimer = async (key) => {
+        if (stopped)
+            return;
+        const agent = byKey.get(key);
+        const entry = state.schedules[key];
+        if (agent === undefined || entry === undefined)
+            return;
+        const observedNow = now();
+        const fireAt = entry.fire_at_ms ?? entry.next_due_ms;
+        if (fireAt > observedNow) {
+            arm(key);
+            return;
+        }
+        const elapsed = latestEligibleOccurrence(agent.schedule, entry.next_due_ms, observedNow);
+        state = { ...state, schedules: { ...state.schedules, [key]: nextEntry(agent, elapsed, observedNow, occurrenceFor(agent.id, agent.schedule, elapsed)) } };
+        await save();
+        arm(key);
+        await drainKey(key);
+    };
+    return {
+        async start() {
+            await enqueue(async () => {
+                if (directory !== undefined)
+                    return;
+                directory = await open(options.acceptanceStorePath, constants.O_RDONLY | directoryFlag() | noFollow());
+                state = await restore(statePath, byKey);
+                const next = { ...state.schedules };
+                const observedNow = now();
+                for (const [key, agent] of byKey) {
+                    const prior = next[key];
+                    if (prior === undefined)
+                        next[key] = nextEntry(agent, undefined, observedNow);
+                    else if ((prior.fire_at_ms ?? prior.next_due_ms) <= observedNow) {
+                        const elapsed = latestEligibleOccurrence(agent.schedule, prior.next_due_ms, observedNow);
+                        const pending = occurrenceFor(agent.id, agent.schedule, elapsed);
+                        next[key] = nextEntry(agent, elapsed, observedNow, newer(prior.latest_pending, pending));
+                    }
+                    else if (prior.fire_at_ms === undefined) {
+                        next[key] = withFireTarget(prior, agent.schedule, random);
+                    }
+                }
+                state = { version: STATE_VERSION, schedules: next };
+                await save();
+                for (const key of byKey.keys())
+                    arm(key);
+                for (const key of byKey.keys())
+                    await drainKey(key);
+            });
+        },
+        async drain(agentId) { await enqueue(async () => { for (const [key, agent] of byKey)
+            if (agentId === undefined || agent.id === agentId)
+                await drainKey(key); }); },
+        async stop() {
+            stopped = true;
+            for (const timer of timers.values())
+                clearTimer(timer);
+            timers.clear();
+            await mutations;
+            await directory?.close();
+            directory = undefined;
+        }
+    };
+}
+export function occurrenceFor(agentId, schedule, at) {
+    const local = schedule.kind === "cron" ? occurrenceForOffset(at, schedule.timezone) : new Date(at).toISOString();
+    return { agentId, occurredAt: new Date(at).toISOString(), prompt: schedule.prompt, deliveryId: `schedule:${identity(agentId, schedule)}:${local}` };
+}
+export function isCanonicalScheduleDeliveryId(value) {
+    if (value.length > 256 || !/^schedule:[a-f0-9]{64}:/u.test(value))
+        return false;
+    const occurrence = value.slice("schedule:".length + 64 + 1);
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(occurrence)
+        || /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}@(?:GMT(?:[+-]\d{2}:\d{2})?|UTC)$/u.test(occurrence);
+}
+export function nextOccurrence(agentId, schedule, anchor, from) {
+    if (schedule.kind === "every") {
+        const base = anchor ?? from;
+        return base > from ? base : base + (Math.floor((from - base) / schedule.interval_ms) + 1) * schedule.interval_ms;
+    }
+    const fields = parseCron(schedule.cron);
+    if (!calendarPossible(fields))
+        throw new Error(`schedule ${agentId} is impossible`);
+    const found = searchCron(fields, schedule.timezone, from, from + SEARCH_HORIZON_MS, 1);
+    if (found !== undefined)
+        return found;
+    throw new Error(`schedule ${agentId} has no occurrence within the deterministic search bound`);
+}
+export function cronIsPossible(cron) { try {
+    return calendarPossible(parseCron(cron));
+}
+catch {
+    return false;
+} }
+/** Independent per-arming offset in `[0, jitter_seconds * 1000]`; absent/zero jitter always yields exactly 0. */
+export function jitterOffsetMs(schedule, random) {
+    const jitterSeconds = schedule?.jitter_seconds ?? 0;
+    if (jitterSeconds <= 0)
+        return 0;
+    const bound = jitterSeconds * 1_000;
+    return Math.min(bound, Math.max(0, Math.floor(random() * (bound + 1))));
+}
+function withFireTarget(entry, schedule, random) {
+    const offset = jitterOffsetMs(schedule, random);
+    return offset === 0 ? entry : { ...entry, fire_at_ms: entry.next_due_ms + offset };
+}
+function withoutPending(entry) {
+    return { next_due_ms: entry.next_due_ms, ...(entry.fire_at_ms === undefined ? {} : { fire_at_ms: entry.fire_at_ms }) };
+}
+function latestEligibleOccurrence(schedule, due, at) {
+    if (schedule.kind === "every")
+        return due + Math.floor((at - due) / schedule.interval_ms) * schedule.interval_ms;
+    const result = searchCron(parseCron(schedule.cron), schedule.timezone, Math.max(due, at - SEARCH_HORIZON_MS), at, -1);
+    if (result === undefined)
+        throw new Error("schedule state has no eligible occurrence within the deterministic search bound");
+    return result;
+}
+function parseCron(cron) {
+    const raw = cron.trim().split(/\s+/u);
+    if (raw.length !== 5)
+        throw new Error("cron is invalid");
+    return Object.assign(raw.map((field, index) => parseField(field, CRON_FIELD_BOUNDS[index])), {
+        dayOfMonthWildcard: raw[2] === "*", dayOfWeekWildcard: raw[4] === "*"
+    });
+}
+function parseField(value, [minimum, maximum]) {
+    const result = new Set();
+    for (const part of value.split(",")) {
+        const [range, rawStep] = part.split("/");
+        const step = Number(rawStep ?? 1);
+        const bounds = range === "*" ? [minimum, maximum] : range.split("-").map(Number);
+        const first = bounds[0];
+        const last = bounds[1] ?? first;
+        if (!Number.isSafeInteger(step) || step < 1 || !Number.isInteger(first) || !Number.isInteger(last) || first < minimum || last > maximum || first > last)
+            throw new Error("cron is invalid");
+        for (let current = first; current <= last; current += step)
+            result.add(current === 7 && maximum === 7 ? 0 : current);
+    }
+    return [...result].sort((left, right) => left - right);
+}
+function calendarPossible(fields) {
+    for (let year = 2000; year < 2400; year += 1)
+        for (const month of fields[3]) {
+            const days = new Date(Date.UTC(year, month, 0)).getUTCDate();
+            for (let day = 1; day <= days; day += 1)
+                if (dateMatches(fields, { year, month, day, hour: 0, minute: 0, weekday: new Date(Date.UTC(year, month - 1, day)).getUTCDay() }))
+                    return true;
+        }
+    return false;
+}
+function searchCron(fields, zone, start, end, direction) {
+    let checks = 0;
+    const firstDay = Math.floor((direction === 1 ? start : end) / 86_400_000) * 86_400_000;
+    const lastDay = Math.floor((direction === 1 ? end : start) / 86_400_000) * 86_400_000;
+    for (let day = firstDay; direction === 1 ? day <= lastDay : day >= lastDay; day += direction * 86_400_000) {
+        const boundary = [parts(day, zone), parts(day + 86_340_000, zone)];
+        checks += 2;
+        if (!boundary.some((value) => dateMatches(fields, value)))
+            continue;
+        const nextMinute = Math.floor(start / 60_000) * 60_000 + 60_000;
+        const low = Math.max(direction === 1 ? nextMinute : start, day);
+        const high = Math.min(end, day + 86_340_000);
+        let candidate = direction === 1 ? Math.ceil(low / 60_000) * 60_000 : Math.floor(high / 60_000) * 60_000;
+        for (; direction === 1 ? candidate <= high : candidate >= low; candidate += direction * 60_000) {
+            if (++checks > MAX_SEARCH_CHECKS)
+                throw new Error("cron search exceeded its deterministic work bound");
+            if (matches(fields, parts(candidate, zone)))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function dateMatches(fields, value) {
+    if (!fields[3].includes(value.month))
+        return false;
+    const dom = fields[2].includes(value.day);
+    const dow = fields[4].includes(value.weekday);
+    return fields.dayOfMonthWildcard ? dow : fields.dayOfWeekWildcard ? dom : dom || dow;
+}
+function matches(fields, value) { return fields[0].includes(value.minute) && fields[1].includes(value.hour) && dateMatches(fields, value); }
+const formatters = new Map();
+function formatter(zone) {
+    let value = formatters.get(zone);
+    if (value === undefined) {
+        value = new Intl.DateTimeFormat("en-US", { timeZone: zone, hourCycle: "h23", weekday: "short", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric" });
+        formatters.set(zone, value);
+    }
+    return value;
+}
+function parts(at, zone) {
+    const values = formatter(zone).formatToParts(at);
+    const get = (name) => values.find((part) => part.type === name)?.value ?? "0";
+    return { year: Number(get("year")), month: Number(get("month")), day: Number(get("day")), hour: Number(get("hour")), minute: Number(get("minute")), weekday: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"].indexOf(get("weekday")) };
+}
+function occurrenceForOffset(at, zone) {
+    const value = parts(at, zone);
+    const local = `${value.year}-${String(value.month).padStart(2, "0")}-${String(value.day).padStart(2, "0")}T${String(value.hour).padStart(2, "0")}:${String(value.minute).padStart(2, "0")}`;
+    const key = `${zone}\u0000offset`;
+    let offset = formatters.get(key);
+    if (offset === undefined) {
+        offset = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" });
+        formatters.set(key, offset);
+    }
+    return `${local}@${offset.formatToParts(at).find((part) => part.type === "timeZoneName")?.value ?? "UTC"}`;
+}
+function identity(agentId, schedule) { return createHash("sha256").update(JSON.stringify({ agentId, schedule })).digest("hex"); }
+function newer(left, right) { return left !== undefined && Date.parse(left.occurredAt) > Date.parse(right.occurredAt) ? left : right; }
+async function restore(file, allowed) {
+    let bytes;
+    try {
+        const entry = await lstat(file);
+        if (!entry.isFile() || entry.isSymbolicLink() || (entry.mode & 0o777) !== 0o600 || entry.size > MAX_STATE_BYTES)
+            throw new Error("schedule state is unsafe");
+        bytes = await readFile(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: STATE_VERSION, schedules: {} };
+        throw error;
+    }
+    if (bytes.length > MAX_STATE_BYTES)
+        throw new Error("schedule state exceeds its bound");
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("schedule state is invalid");
+    const root = value;
+    if (Object.keys(root).sort().join() !== "schedules,version" || root.version !== STATE_VERSION || !root.schedules || typeof root.schedules !== "object" || Array.isArray(root.schedules))
+        throw new Error("schedule state is invalid");
+    const schedules = {};
+    for (const [key, raw] of Object.entries(root.schedules)) {
+        if (!/^[a-f0-9]{64}$/u.test(key))
+            throw new Error("schedule state is invalid");
+        if (!allowed.has(key))
+            continue;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error("schedule state is invalid");
+        const entry = raw;
+        const keys = Object.keys(entry).sort().join();
+        if (!["fire_at_ms,next_due_ms", "fire_at_ms,latest_pending,next_due_ms", "latest_pending,next_due_ms", "next_due_ms"].includes(keys))
+            throw new Error("schedule state is invalid");
+        if (!Number.isSafeInteger(entry.next_due_ms) || entry.next_due_ms < 0)
+            throw new Error("schedule state is invalid");
+        const nextDue = entry.next_due_ms;
+        const fireAt = entry.fire_at_ms;
+        if (fireAt !== undefined) {
+            const maximumFireAt = nextDue + jitterOffsetMs(allowed.get(key).schedule, () => 0.999_999_999);
+            if (!Number.isSafeInteger(fireAt) || fireAt < nextDue || fireAt > maximumFireAt)
+                throw new Error("schedule state is invalid");
+        }
+        const pending = entry.latest_pending === undefined ? undefined : parseOccurrence(entry.latest_pending);
+        if (pending !== undefined)
+            assertRestoredOccurrence(key, allowed.get(key), pending, nextDue);
+        schedules[key] = { next_due_ms: nextDue, ...(fireAt === undefined ? {} : { fire_at_ms: fireAt }), ...(pending === undefined ? {} : { latest_pending: pending }) };
+    }
+    return { version: STATE_VERSION, schedules };
+}
+function assertRestoredOccurrence(key, agent, pending, nextDue) {
+    const occurred = Date.parse(pending.occurredAt);
+    const expected = occurrenceFor(agent.id, agent.schedule, occurred);
+    if (pending.agentId !== agent.id || pending.prompt !== agent.schedule.prompt ||
+        pending.deliveryId !== expected.deliveryId || !pending.deliveryId.startsWith(`schedule:${key}:`) ||
+        nextDue !== nextOccurrence(agent.id, agent.schedule, occurred, occurred)) {
+        throw new Error("schedule state is invalid");
+    }
+}
+function parseOccurrence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("schedule state is invalid");
+    const item = value;
+    if (Object.keys(item).sort().join() !== "agentId,deliveryId,occurredAt,prompt" || Object.values(item).some((entry) => typeof entry !== "string" || Buffer.byteLength(entry, "utf8") > 16_384))
+        throw new Error("schedule state is invalid");
+    const occurredAt = item.occurredAt;
+    if (Number.isNaN(Date.parse(occurredAt)) || new Date(occurredAt).toISOString() !== occurredAt || !/^schedule:[a-f0-9]{64}:/u.test(item.deliveryId))
+        throw new Error("schedule state is invalid");
+    return item;
+}
+async function persist(file, value, directory, observe) {
+    const bytes = Buffer.from(JSON.stringify(value), "utf8");
+    if (bytes.length > MAX_STATE_BYTES)
+        throw new Error("schedule state exceeds its bound");
+    const temporary = path.join(path.dirname(file), `.schedule-state-${randomUUID()}`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow(), 0o600);
+    try {
+        await handle.writeFile(bytes);
+        observe?.("write");
+        await handle.sync();
+        observe?.("file-sync");
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+        observe?.("rename");
+        await directory.sync();
+        observe?.("directory-sync");
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+function noFollow() { return constants.O_NOFOLLOW ?? 0; }
+function directoryFlag() { return constants.O_DIRECTORY ?? 0; }

package/dist/runtime/storeCoordination.d.ts

@@ -0,0 +1,23 @@
+import { open } from "node:fs/promises";
+export type StoreProcessIdentity = Readonly<{
+    pid: number;
+    process_start: string;
+    boot_id: string;
+    pid_namespace_dev: number;
+    pid_namespace_ino: number;
+}>;
+export type StoreHostRegistration = StoreProcessIdentity & Readonly<{
+    owner_id: string;
+}>;
+export type StoreHostRegistrationIdentity = StoreHostRegistration & Readonly<{
+    dev: number;
+    ino: number;
+}>;
+export declare function acquireHostRegistration(root: string, directory: Awaited<ReturnType<typeof open>>, identity: StoreProcessIdentity): Promise<StoreHostRegistration>;
+export declare function releaseHostRegistration(root: string, directory: Awaited<ReturnType<typeof open>>, registration: StoreHostRegistration): Promise<void>;
+/** Admin callers hold their durable offline lease before calling this. */
+export declare function listHostRegistrations(root: string): Promise<readonly StoreHostRegistrationIdentity[]>;
+/** Returns undefined when any registration is live, unknown, or changed. */
+export declare function clearDeadHostRegistrations(root: string, directory: Awaited<ReturnType<typeof open>>, identity: StoreProcessIdentity, liveness: (owner: StoreHostRegistration) => Promise<boolean>, authorizedCrossNamespace: ReadonlySet<string>): Promise<readonly string[] | undefined>;
+export declare function hostRegistrationDigest(value: StoreHostRegistrationIdentity): string;
+//# sourceMappingURL=storeCoordination.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storeCoordination.d.ts","sourceRoot":"","sources":["../../src/runtime/storeCoordination.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,IAAI,EAA6B,MAAM,kBAAkB,CAAC;AAG1E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC3J,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC1F,MAAM,MAAM,6BAA6B,GAAG,qBAAqB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE3G,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAWvK;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3J;AAED,0EAA0E;AAC1E,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,6BAA6B,EAAE,CAAC,CAA0O;AACtV,4EAA4E;AAC5E,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAgB/R;AAkBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,6BAA6B,GAAG,MAAM,CAA6E"}

package/dist/runtime/storeCoordination.js

@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readFile, readdir, unlink } from "node:fs/promises";
+import path from "node:path";
+export async function acquireHostRegistration(root, directory, identity) {
+    const registration = { owner_id: randomUUID(), ...identity };
+    const target = path.join(root, `.host-online-${registration.owner_id}.json`);
+    await writeNew(target, registration);
+    await directory.sync();
+    if (await exists(path.join(root, ".offline-reconciliation.lock"))) {
+        await unlink(target);
+        await directory.sync();
+        throw new Error("wake acceptance store is reserved for offline reconciliation");
+    }
+    return registration;
+}
+export async function releaseHostRegistration(root, directory, registration) {
+    const target = path.join(root, `.host-online-${registration.owner_id}.json`);
+    const current = await readRegistration(target);
+    if (!sameOwner(current, registration))
+        throw new Error("wake acceptance host registration changed");
+    await unlink(target);
+    await directory.sync();
+}
+/** Admin callers hold their durable offline lease before calling this. */
+export async function listHostRegistrations(root) { const result = []; for (const entry of await readdir(root)) {
+    if (/^\.host-online-[0-9a-f-]{36}\.json$/iu.test(entry))
+        result.push(await readRegistration(path.join(root, entry)));
+} return result; }
+/** Returns undefined when any registration is live, unknown, or changed. */
+export async function clearDeadHostRegistrations(root, directory, identity, liveness, authorizedCrossNamespace) {
+    const cleared = [];
+    for (const entry of await readdir(root)) {
+        if (!/^\.host-online-[0-9a-f-]{36}\.json$/iu.test(entry))
+            continue;
+        const target = path.join(root, entry);
+        const owner = await readRegistration(target);
+        const digest = hostRegistrationDigest(owner);
+        if (!sameNamespace(owner, identity) && !authorizedCrossNamespace.has(digest))
+            return undefined;
+        if (sameNamespace(owner, identity) && await liveness(owner))
+            return undefined;
+        const checked = await readRegistration(target);
+        if (!sameIdentity(checked, owner))
+            return undefined;
+        await unlink(target);
+        await directory.sync();
+        cleared.push(digest);
+    }
+    return cleared;
+}
+async function readRegistration(target) {
+    const entry = await lstat(target);
+    if (!entry.isFile() || entry.isSymbolicLink() || Number(entry.uid) !== process.getuid?.() || (Number(entry.mode) & 0o777) !== 0o600 || Number(entry.size) > 1024)
+        throw new Error("wake acceptance host registration is unsafe");
+    const value = JSON.parse((await readFile(target)).toString("utf8"));
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("wake acceptance host registration is invalid");
+    const record = value;
+    const keys = ["owner_id", "pid", "process_start", "boot_id", "pid_namespace_dev", "pid_namespace_ino"];
+    if (Object.keys(record).length !== keys.length || keys.some((key) => !Object.hasOwn(record, key)))
+        throw new Error("wake acceptance host registration is invalid");
+    const result = { dev: Number(entry.dev), ino: Number(entry.ino), owner_id: uuid(record.owner_id), pid: positive(record.pid), process_start: text(record.process_start), boot_id: text(record.boot_id), pid_namespace_dev: positive(record.pid_namespace_dev), pid_namespace_ino: positive(record.pid_namespace_ino) };
+    if (!result.process_start || !result.boot_id)
+        throw new Error("wake acceptance host registration is invalid");
+    return result;
+}
+async function writeNew(target, value) { const handle = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow(), 0o600); try {
+    await handle.writeFile(JSON.stringify(value));
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} }
+async function exists(target) { try {
+    await lstat(target);
+    return true;
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return false;
+    throw error;
+} }
+function sameOwner(left, right) { return left.owner_id === right.owner_id && left.pid === right.pid && left.process_start === right.process_start && left.boot_id === right.boot_id && sameNamespace(left, right); }
+function sameIdentity(left, right) { return left.dev === right.dev && left.ino === right.ino && sameOwner(left, right); }
+export function hostRegistrationDigest(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function sameNamespace(left, right) { return left.pid_namespace_dev === right.pid_namespace_dev && left.pid_namespace_ino === right.pid_namespace_ino; }
+function text(value) { if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > 1024)
+    throw new Error("wake acceptance host registration is invalid"); return value; }
+function uuid(value) { const result = text(value); if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(result))
+    throw new Error("wake acceptance host registration is invalid"); return result; }
+function positive(value) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+    throw new Error("wake acceptance host registration is invalid"); return value; }
+function noFollow() { return constants.O_NOFOLLOW ?? 0; }