@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/jobs/schedule.js

@@ -0,0 +1,77 @@
+/**
+ * §8.2 schedule math (jobs Task 1) — when a job fires next.
+ *
+ * Cron semantics belong to croner (spec §8.2: "Cron parsing uses
+ * croner … DST is exactly the class of bug not to hand-roll"); this
+ * module only dispatches the three schedule shapes and never
+ * re-derives a time. `nextFireAt` is the scheduler's single walk step:
+ * given a schedule and an instant, the next fire STRICTLY AFTER that
+ * instant, or `undefined` when the schedule can never fire again (a
+ * one-shot `at` already past).
+ *
+ * `every` intervals anchor at `after` itself — after downtime the next
+ * fire is computed from now, never from a missed slot (the plan's
+ * Review Focus 5: `catchUp` decides whether a missed fire is recorded,
+ * and the schedule never fires once per missed interval).
+ *
+ * `cronFor` is the ONE croner parse in the tree: validation
+ * (src/jobs/spec.ts rejects a bad pattern via croner's constructor
+ * throwing) and evaluation (below) must agree, so they share both the
+ * options and the pattern. `mode: "5-part"` enforces the Global
+ * Constraints' 5-field grammar — croner's auto mode would silently
+ * reinterpret a 6-field pattern as second-level precision instead of
+ * rejecting it.
+ */
+import { Cron } from "croner";
+/** The `every` grammar (Global Constraints): `^\d+(s|m|h|d)$`, ≥ 60 s. */
+const EVERY_PATTERN = /^\d+(s|m|h|d)$/;
+const EVERY_UNIT_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+/** The floor the Global Constraints put on `every` intervals. */
+const EVERY_MIN_MS = 60_000;
+/**
+ * The single croner parse (see the module header): a `Cron` whose
+ * constructor throws on an invalid 5-field pattern. No callback is
+ * passed, so croner never arms a timer — this is pure pattern math.
+ */
+export function cronFor(cron, timezone) {
+    return new Cron(cron, { timezone, mode: "5-part" });
+}
+/**
+ * Parse an `every` interval into milliseconds. Throws on anything
+ * outside `^\\d+(s|m|h|d)$` and on intervals below the 60 s floor.
+ */
+export function parseEvery(text) {
+    const match = EVERY_PATTERN.exec(text);
+    if (match === null) {
+        throw new Error(`every must match ${EVERY_PATTERN.source} (got ${JSON.stringify(text)})`);
+    }
+    const ms = Number.parseInt(match[0], 10) * EVERY_UNIT_MS[match[1]];
+    if (ms < EVERY_MIN_MS) {
+        throw new Error(`every must be at least 60 s (got ${JSON.stringify(text)})`);
+    }
+    return ms;
+}
+/**
+ * The next fire strictly after `after`, in epoch ms — or `undefined`
+ * when the schedule will never fire again (a one-shot `at` at or
+ * before `after`). A cron's timezone is the schedule's, else
+ * `defaultTz` (the resolved `server.timezone`).
+ */
+export function nextFireAt(schedule, after, defaultTz) {
+    if ("cron" in schedule) {
+        const next = cronFor(schedule.cron, schedule.timezone ?? defaultTz).nextRun(new Date(after));
+        return next === null ? undefined : next.getTime();
+    }
+    if ("every" in schedule) {
+        // Anchored at `after` (see the module header): the next fire is
+        // one interval from the instant asked about.
+        return after + parseEvery(schedule.every);
+    }
+    const fireAt = Date.parse(schedule.at);
+    return Number.isNaN(fireAt) || fireAt <= after ? undefined : fireAt;
+}

package/dist/jobs/spec.js

@@ -0,0 +1,248 @@
+/**
+ * §8.2 job-spec validation and hashing (jobs Task 1).
+ *
+ * Every job source — api (`POST /v1/jobs`), file (settings.json
+ * `jobs[]`), extension (factory-result `jobs[]`) — funnels through
+ * `validateJobSpec` before a job record exists; boot reconciliation
+ * then compares `specHash` to decide whether a declared job's schedule
+ * task may keep running (same hash) or must be recreated (changed).
+ *
+ * Validation maps every rejection to a `field` path so callers can
+ * attribute the 400 to the offending input. Cron validation IS
+ * croner's parse (`cronFor` in ./schedule.js — the constructor throws
+ * on a bad 5-field pattern), so what the validator accepts is exactly
+ * what the scheduler can evaluate; nothing is validated by a second
+ * grammar that could drift.
+ *
+ * `specHash` canonicalizes (recursively sorted object keys) before
+ * hashing, so key order — where the spec came from, which JSON parser
+ * read it — never changes a job's identity.
+ */
+import { createHash } from "node:crypto";
+import { isSharing } from "@sigrun/shared/access";
+import { cronFor, parseEvery } from "./schedule.js";
+/** Job names double as the file/extension id suffix (Global Constraints). */
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Refine `unknown` (a request body, a settings block, an extension
+ * declaration) into a `JobSpec`, or reject with the first offending
+ * field. The accepted spec is rebuilt field-by-field: only the
+ * declared, validated fields survive, so extra keys in the input never
+ * ride into the record (or into `specHash`).
+ */
+export function validateJobSpec(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid("spec", "a job spec must be an object");
+    }
+    const record = value;
+    if (typeof record.name !== "string" || !NAME_PATTERN.test(record.name)) {
+        return invalid("name", `name must be a string matching ${NAME_PATTERN.source}`);
+    }
+    const schedule = validateSchedule(record.schedule);
+    if (!schedule.ok)
+        return schedule;
+    const action = validateAction(record.action);
+    if (!action.ok)
+        return action;
+    if (record.overlap !== undefined && record.overlap !== "skip" && record.overlap !== "queue") {
+        return invalid("overlap", 'overlap must be "skip" or "queue"');
+    }
+    if (record.catchUp !== undefined && record.catchUp !== "once" && record.catchUp !== "none") {
+        return invalid("catchUp", 'catchUp must be "once" or "none"');
+    }
+    if (record.enabled !== undefined && typeof record.enabled !== "boolean") {
+        return invalid("enabled", "enabled must be a boolean");
+    }
+    if (record.owner !== undefined && typeof record.owner !== "string") {
+        return invalid("owner", "owner must be a string");
+    }
+    if (record.sharing !== undefined && !isSharing(record.sharing)) {
+        return invalid("sharing", "sharing must be a Sharing value");
+    }
+    const spec = {
+        name: record.name,
+        schedule: schedule.schedule,
+        action: action.action,
+    };
+    if (record.overlap !== undefined)
+        spec.overlap = record.overlap;
+    if (record.catchUp !== undefined)
+        spec.catchUp = record.catchUp;
+    if (record.enabled !== undefined)
+        spec.enabled = record.enabled;
+    if (record.owner !== undefined)
+        spec.owner = record.owner;
+    if (record.sharing !== undefined)
+        spec.sharing = record.sharing;
+    return { ok: true, spec };
+}
+/**
+ * sha256 of the canonical JSON (recursively key-sorted) of
+ * `{ id, spec }` — one job version's identity, as boot reconciliation
+ * compares it.
+ */
+export function specHash(id, spec) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize({ id, spec })))
+        .digest("hex");
+}
+function invalid(field, message) {
+    return { ok: false, field, message };
+}
+/**
+ * A schedule is exactly ONE of the three shapes (the wire type is a
+ * union): a schedule carrying two discriminants matches no member, so
+ * it is rejected rather than silently dispatched on the first present.
+ */
+function validateSchedule(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid("schedule", "schedule must be an object");
+    }
+    const record = value;
+    const discriminants = ["cron", "every", "at"].filter((key) => record[key] !== undefined);
+    if (discriminants.length !== 1) {
+        return invalid("schedule", 'schedule must carry exactly one of "cron", "every", or "at"');
+    }
+    if (record.cron !== undefined) {
+        if (typeof record.cron !== "string") {
+            return invalid("schedule.cron", "cron must be a string");
+        }
+        if (record.timezone !== undefined) {
+            if (typeof record.timezone !== "string") {
+                return invalid("schedule.timezone", "timezone must be a string");
+            }
+            // croner validates the name lazily (at evaluation, not parse), so
+            // the gate checks it here — a bad name would otherwise crash the
+            // scheduler instead of rejecting the spec.
+            if (!isIanaTimeZone(record.timezone)) {
+                return invalid("schedule.timezone", `timezone must be an IANA name (got ${JSON.stringify(record.timezone)})`);
+            }
+        }
+        try {
+            cronFor(record.cron, record.timezone);
+        }
+        catch (error) {
+            return invalid("schedule.cron", error instanceof Error ? error.message : String(error));
+        }
+        const schedule = { cron: record.cron };
+        if (record.timezone !== undefined)
+            schedule.timezone = record.timezone;
+        return { ok: true, schedule };
+    }
+    if (record.every !== undefined) {
+        if (typeof record.every !== "string") {
+            return invalid("schedule.every", "every must be a string");
+        }
+        try {
+            parseEvery(record.every);
+        }
+        catch (error) {
+            return invalid("schedule.every", error instanceof Error ? error.message : String(error));
+        }
+        return { ok: true, schedule: { every: record.every } };
+    }
+    // The one remaining discriminant is "at".
+    if (typeof record.at !== "string" || Number.isNaN(Date.parse(record.at))) {
+        return invalid("schedule.at", "at must be an ISO 8601 timestamp");
+    }
+    return { ok: true, schedule: { at: record.at } };
+}
+function validateAction(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid("action", "action must be an object");
+    }
+    const record = value;
+    if (record.kind === "prompt") {
+        if (typeof record.prompt !== "string") {
+            return invalid("action.prompt", "prompt must be a string");
+        }
+        if (record.conversation !== "new" &&
+            !(typeof record.conversation === "number" &&
+                Number.isInteger(record.conversation))) {
+            return invalid("action.conversation", 'conversation must be "new" or a conversation id');
+        }
+        if (record.model !== undefined && typeof record.model !== "string") {
+            return invalid("action.model", "model must be a string");
+        }
+        if (record.thinking !== undefined && typeof record.thinking !== "string") {
+            return invalid("action.thinking", "thinking must be a string");
+        }
+        if (record.runSharing !== undefined && !isSharing(record.runSharing)) {
+            return invalid("action.runSharing", "runSharing must be a Sharing value");
+        }
+        const action = {
+            kind: "prompt",
+            prompt: record.prompt,
+            // Guarded above: "new" or an integer conversation id.
+            conversation: record.conversation,
+        };
+        if (record.model !== undefined)
+            action.model = record.model;
+        if (record.thinking !== undefined)
+            action.thinking = record.thinking;
+        if (record.runSharing !== undefined)
+            action.runSharing = record.runSharing;
+        return { ok: true, action };
+    }
+    if (record.kind === "task") {
+        if (typeof record.task !== "string") {
+            return invalid("action.task", "task must be a string");
+        }
+        if (record.input !== undefined && !isJsonValue(record.input)) {
+            return invalid("action.input", "input must be a JSON value");
+        }
+        const action = {
+            kind: "task",
+            task: record.task,
+        };
+        if (record.input !== undefined)
+            action.input = record.input;
+        return { ok: true, action };
+    }
+    return invalid("action.kind", `action.kind must be "prompt" or "task" (got ${JSON.stringify(record.kind)})`);
+}
+/**
+ * `Intl` accepts exactly the IANA names `DateTimeFormat` resolves —
+ * the same resolver croner's evaluation path uses — and throws on
+ * everything else.
+ */
+export function isIanaTimeZone(name) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Structural JSON check for the `task` action's optional `input`. */
+function isJsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (typeof value === "object") {
+        return Object.values(value).every(isJsonValue);
+    }
+    return false;
+}
+/** Canonical form for hashing: key order never affects the digest. */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            if (record[key] === undefined)
+                continue;
+            sorted[key] = canonicalize(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}

package/dist/jobs/task.js

@@ -0,0 +1,190 @@
+/**
+ * Jobs Task 2 (spec §8.1 "The executor"): the `sigrun.schedule` task —
+ * one long-lived background pi-durable task per ENABLED job, looping
+ * `waiting` → `firing` → `waiting` over a durable `runtime.sleep`.
+ *
+ * The input is only `{jobId, hash, firstAt?}` (the plan's Global
+ * Constraints): the task NEVER trusts its input's spec — EVERY phase
+ * re-reads the job record, and a record that is absent, disabled, or
+ * hash-mismatched makes the task commit TERMINAL (it is a stale executor;
+ * reconciliation owns the replacement). `firstAt` exists because
+ * `initial(input)` sees only the input: the creator computes the first
+ * fire (`nextFireAt(schedule, now, tz)`).
+ *
+ * The phases:
+ * - `waiting`: durable `runtime.sleep(nextAt)`. On wake: under
+ *   `catchUp: "none"` and `now - nextAt > 60_000`, the missed slot is
+ *   recorded `skipped` and the task re-commits `waiting` at the NEXT
+ *   slot from NOW. Otherwise it commits `{phase: "firing", fireAt:
+ *   nextAt}`.
+ * - `firing`: `fireJob(…, fireKey = <jobId>:<fireAt>)` — the run record
+ *   doubles as the idempotency record, so a crash mid-fire re-enters
+ *   here and reuses it. Then `nextAt = nextFireAt(schedule, max(now,
+ *   fireAt), tz)` — FROM NOW, never from the missed slot (Review Focus
+ *   5: catchUp decides whether a missed fire is recorded; the schedule
+ *   never fires once per missed interval). No next slot → terminal
+ *   completed (a past one-shot `at`).
+ *
+ * `abort` commits terminal (aborted) — the disable/delete path's signal.
+ *
+ * The record's status fields (`state`, `nextRun`, `lastRun`) ride
+ * `patchJob` — small status edits, never version bumps.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { defineTask } from "@earendil-works/pi-durable";
+import { JobRunDoc, patchJob, readJob } from "./docs.js";
+import { fireJob } from "./fire.js";
+import { nextFireAt } from "./schedule.js";
+/** The persisted task kind (TaskRecord.kind). */
+export const SCHEDULE_TASK_KIND = "sigrun.schedule";
+/** The definition version persisted with the task. */
+export const SCHEDULE_TASK_VERSION = 1;
+/** Under `catchUp: "none"`, a fire missed by more than this is skipped. */
+const CATCHUP_GRACE_MS = 60_000;
+/**
+ * The per-job executor. `deps` threads the harness + the injectable
+ * clock (`deps.now` — the tests' lever; `runtime.sleep` reads the same
+ * clock through the harness, which is why the phases re-check it).
+ */
+export function createScheduleTask(deps) {
+    return defineTask({
+        name: SCHEDULE_TASK_KIND,
+        version: SCHEDULE_TASK_VERSION,
+        // `initial` sees only the input: the creator computed `firstAt`
+        // (nextFireAt at creation); absent, the first phase re-derives it
+        // from the record at its first run.
+        initial: (input) => ({
+            phase: "waiting",
+            nextAt: input.firstAt ?? 0,
+        }),
+        phases: {
+            waiting: async (task, runtime, context) => {
+                const record = await readJob(deps.harness, task.input.jobId, context);
+                if (stale(record, task.input.hash)) {
+                    await runtime.commit(() => ({
+                        status: "terminal",
+                        outcome: { status: "completed", result: undefined },
+                    }), context);
+                    return;
+                }
+                let nextAt = task.state.checkpoint.nextAt;
+                if (nextAt === 0) {
+                    // No creator-computed firstAt (a re-derived first fire).
+                    const first = nextFireAt(record.spec.schedule, deps.now(), deps.defaultTz);
+                    if (first === undefined) {
+                        await runtime.commit(() => ({
+                            status: "terminal",
+                            outcome: { status: "completed", result: undefined },
+                        }), context);
+                        return;
+                    }
+                    nextAt = first;
+                }
+                // The durable wait — the crash point the battery kills inside.
+                await runtime.sleep(nextAt, context);
+                // Re-check the record after the sleep (it may have changed).
+                const after = await readJob(deps.harness, task.input.jobId, context);
+                if (stale(after, task.input.hash)) {
+                    await runtime.commit(() => ({
+                        status: "terminal",
+                        outcome: { status: "completed", result: undefined },
+                    }), context);
+                    return;
+                }
+                const now = deps.now();
+                const catchUp = after.spec.catchUp ?? "once";
+                if (catchUp === "none" && now - nextAt > CATCHUP_GRACE_MS) {
+                    // Missed beyond the grace: record `skipped` (settled
+                    // immediately), then schedule the NEXT slot from now.
+                    const skipped = {
+                        jobId: task.input.jobId,
+                        version: after.version,
+                        fireAt: new Date(nextAt).toISOString(),
+                        manual: false,
+                        outcome: "skipped",
+                        startedAt: new Date(now).toISOString(),
+                        settledAt: new Date(now).toISOString(),
+                    };
+                    const fireKey = `${task.input.jobId}:${nextAt}`;
+                    await deps.harness.commit(async (tx) => {
+                        await tx.doc(JobRunDoc, fireKey, skipped);
+                    }, context);
+                    await patchJob(deps.harness, task.input.jobId, (draft) => {
+                        draft.lastRun = skipped;
+                    }, context);
+                    const next = nextFireAt(after.spec.schedule, now, deps.defaultTz);
+                    if (next === undefined) {
+                        await runtime.commit(() => ({
+                            status: "terminal",
+                            outcome: { status: "completed", result: undefined },
+                        }), context);
+                        return;
+                    }
+                    await runtime.commit(() => ({
+                        status: "running",
+                        checkpoint: { phase: "waiting", nextAt: next },
+                    }), context);
+                    await patchJob(deps.harness, task.input.jobId, (draft) => {
+                        draft.state = "waiting";
+                        draft.nextRun = new Date(next).toISOString();
+                    }, context);
+                    return;
+                }
+                await runtime.commit(() => ({
+                    status: "running",
+                    checkpoint: { phase: "firing", fireAt: nextAt },
+                }), context);
+                await patchJob(deps.harness, task.input.jobId, (draft) => {
+                    draft.state = "firing";
+                }, context);
+            },
+            firing: async (task, runtime, context) => {
+                const record = await readJob(deps.harness, task.input.jobId, context);
+                if (stale(record, task.input.hash)) {
+                    await runtime.commit(() => ({
+                        status: "terminal",
+                        outcome: { status: "completed", result: undefined },
+                    }), context);
+                    return;
+                }
+                const fireAt = task.state.checkpoint.fireAt;
+                const fireKey = `${task.input.jobId}:${fireAt}`;
+                await fireJob(deps, task.input.jobId, fireKey, fireAt, context, runtime);
+                // From NOW, never from the missed slot (Review Focus 5).
+                const now = deps.now();
+                const next = nextFireAt(record.spec.schedule, Math.max(now, fireAt), deps.defaultTz);
+                if (next === undefined) {
+                    await patchJob(deps.harness, task.input.jobId, (draft) => {
+                        draft.state = "waiting";
+                        delete draft.nextRun;
+                    }, context);
+                    await runtime.commit(() => ({
+                        status: "terminal",
+                        outcome: { status: "completed", result: undefined },
+                    }), context);
+                    return;
+                }
+                await runtime.commit(() => ({
+                    status: "running",
+                    checkpoint: { phase: "waiting", nextAt: next },
+                }), context);
+                await patchJob(deps.harness, task.input.jobId, (draft) => {
+                    draft.state = "waiting";
+                    draft.nextRun = new Date(next).toISOString();
+                }, context);
+            },
+        },
+        abort: async (_task, runtime, context) => {
+            await runtime.commit(() => ({
+                status: "terminal",
+                outcome: { status: "aborted", reason: "job disabled or deleted" },
+            }), context);
+        },
+    });
+}
+/** The stale-executor rule: absent/disabled/hash-mismatched record. */
+function stale(record, hash) {
+    return (record === undefined || record.hash !== hash || record.enabled === false);
+}
+/** Awaiting `runtime.sleep` on the harness's background context. */
+export const SCHEDULE_CONTEXT = BACKGROUND_CONTEXT;

package/dist/jobs/transfer.js

@@ -0,0 +1,53 @@
+/**
+ * Jobs Task 3 (spec §5.8 + §8.3): the ownership-transfer participant.
+ *
+ * Registered by `createServer` behind the core conversation participant
+ * (`registerCoreOwnershipParticipant` first — conversations transfer
+ * before the jobs records do). For a `from → to` transfer it rewrites
+ * every `api` job record whose `owner === from` to `owner: to` through
+ * `writeJobChange` — which recomputes NOTHING itself (the caller does)
+ * but bumps `version` and writes a `changedBy: "transfer"` revision —
+ * then calls `jobs.reconcile()`: the owner rides the spec hash, so the
+ * changed hash makes reconciliation abort the old executor and create a
+ * new one (the plan's "new hash → task recreated").
+ *
+ * Declared (`file`/`extension`) records are NOT rewritten here — their
+ * source owns the owner field; the next boot's reconciliation warns when
+ * a declared owner no longer exists in the directory (the job runs
+ * ownerless until the source is edited — spec §8.3's posture).
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { registerOwnershipParticipant } from "../server/ownership.js";
+import { scanJobs, writeJobChange } from "./docs.js";
+import { specHash } from "./spec.js";
+/**
+ * Register the jobs transfer participant on `ctx` (createServer calls
+ * this right after the core conversation participant).
+ */
+export function registerJobsOwnershipParticipant(ctx) {
+    const participant = async (from, to) => {
+        const { opened } = ctx;
+        const jobs = opened.jobs;
+        const storage = opened.storage;
+        const nowIso = new Date().toISOString();
+        const records = await scanJobs(storage, BACKGROUND_CONTEXT);
+        for (const { id, record } of records) {
+            if (record.source !== "api")
+                continue;
+            if (record.owner !== from)
+                continue;
+            const spec = { ...record.spec, owner: to };
+            const next = {
+                ...record,
+                spec,
+                owner: to,
+                hash: specHash(id, spec),
+            };
+            await opened.harness.commit(async (tx) => {
+                await writeJobChange(tx, id, next, "transfer", nowIso);
+            }, BACKGROUND_CONTEXT);
+        }
+        await jobs.reconcile();
+    };
+    registerOwnershipParticipant(ctx, participant);
+}