@zq-silk/yui 2.8.1 → 2.9.0

package/dist/job/builtinJob.js

@@ -0,0 +1,58 @@
+import { fileURLToPath } from "node:url";
+import { requireKnownFields } from "../domain/validation.js";
+/**
+ * Controlled action compilation, not a shell/Agent plugin surface.
+ * Unknown actions fail closed; executable paths/argv are never caller supplied.
+ */
+export function prepareBuiltinJob(configuration, workspace, execution) {
+    if (configuration.action === "project.refresh") {
+        projectRefreshDigest(configuration);
+        // Runtime-owned Git discovery/authentication context, never caller input
+        // or arbitrary inherited credentials. Background Git cannot prompt.
+        const env = { GIT_TERMINAL_PROMPT: "0" };
+        for (const key of ["PATH", "HOME", "SSH_AUTH_SOCK", "XDG_CONFIG_HOME", "GIT_CONFIG_NOSYSTEM", "GIT_CONFIG_GLOBAL"]) {
+            if (process.env[key] !== undefined)
+                env[key] = process.env[key];
+        }
+        return {
+            workspace, env, head: "0".repeat(40),
+            steps: [{
+                    name: "project.refresh", command: `project.refresh ${configuration.projectId}`,
+                    argv: [process.execPath, fileURLToPath(new URL("./projectRefreshRunner.js", import.meta.url)),
+                        execution?.home ?? "", execution?.runId ?? ""],
+                    timeoutMs: 10 * 60_000
+                }]
+        };
+    }
+    if (configuration.action !== "system.noop")
+        throw new Error(`Unsupported builtin Job action: ${configuration.action}.`);
+    if (configuration.projectId !== undefined || JSON.stringify(configuration.input) !== "{}") {
+        throw new Error("system.noop accepts an empty input and no Project target.");
+    }
+    return {
+        workspace,
+        env: {},
+        // No source repository applies to this action. This explicit sentinel is
+        // never an Integration candidate or evidence of a Project revision.
+        head: "0".repeat(40),
+        steps: [{
+                name: "system.noop",
+                command: "system.noop",
+                argv: [process.execPath, "-e", "process.stdout.write('system.noop completed\\n')"],
+                timeoutMs: 5000
+            }]
+    };
+}
+export function projectRefreshDigest(configuration) {
+    if (!/^project-\d+$/u.test(configuration.projectId ?? ""))
+        throw new Error("project.refresh requires an exact Project ID.");
+    const input = configuration.input;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Invalid project.refresh input.");
+    requireKnownFields(input, ["targetDigest"], "project.refresh input");
+    const digest = input.targetDigest;
+    if (typeof digest !== "string" || !/^[a-f0-9]{64}$/u.test(digest)) {
+        throw new Error("project.refresh requires its current catalog targetDigest.");
+    }
+    return digest;
+}

package/dist/job/durableJob.js

@@ -11,6 +11,9 @@ export const DURABLE_JOB_TERMINAL_STATUSES = [
     "cancelled",
     "unknown-needs-attention"
 ];
+export function executionNamespace(run) {
+    return "taskId" in run ? run.taskId : "global";
+}
 export function isDurableJobTerminal(status) {
     return DURABLE_JOB_TERMINAL_STATUSES.includes(status);
 }
@@ -22,6 +25,9 @@ export function createDurableJob(input, now) {
     return validateDurableJob({
         schemaVersion: CURRENT_DURABLE_JOB_SCHEMA_VERSION,
         id: input.id,
+        definitionId: input.definitionId ?? input.id,
+        definitionRevision: input.definitionRevision ?? 1,
+        trigger: input.trigger ?? { source: "manual", key: input.operation.requestId },
         taskId: input.taskId,
         owner: input.owner,
         projectId: input.projectId,
@@ -233,50 +239,26 @@ export function validateDurableJob(job) {
         throw new Error(`DurableJob must use schemaVersion ${CURRENT_DURABLE_JOB_SCHEMA_VERSION}.`);
     }
     validateOperationFacts(job.operation);
-    validateTaskRecordReference({
-        taskId: job.taskId,
-        localId: job.id
-    }, "durableJob");
-    validateDurableJobOwner(job.owner, job.taskId);
-    requireIdentity(job.projectId, "DurableJob project id");
-    requireCommit(job.head, "DurableJob head");
-    requireText(job.workspace, "DurableJob workspace");
-    if (!job.workspace.startsWith("/")) {
-        throw new Error("DurableJob workspace must be an absolute path.");
-    }
-    validateEnvMap(job.env);
-    if (!Array.isArray(job.steps) || job.steps.length === 0) {
-        throw new Error("DurableJob requires at least one step.");
-    }
-    const stepNames = new Set();
-    for (const step of job.steps) {
-        const name = requireText(step.name, "DurableJob step name");
-        if (stepNames.has(name)) {
-            throw new Error(`DurableJob step names must be unique: ${name}.`);
-        }
-        stepNames.add(name);
-        requireText(step.command, `DurableJob step command (${name})`);
-        if (step.argv !== undefined) {
-            if (!Array.isArray(step.argv) || step.argv.length === 0) {
-                throw new Error(`DurableJob step argv must be a non-empty array (${name}).`);
-            }
-            for (const value of step.argv) {
-                requireText(value, `DurableJob step argv (${name})`);
-            }
-        }
-        if (step.cwd !== undefined) {
-            requireText(step.cwd, `DurableJob step cwd (${name})`);
-            if (!step.cwd.startsWith("/")) {
-                throw new Error(`DurableJob step cwd must be absolute (${name}).`);
-            }
-        }
-        if (step.env !== undefined) {
-            validateEnvMap(step.env);
-        }
-        if (step.timeoutMs !== undefined) {
-            requirePositiveInteger(step.timeoutMs, `DurableJob step timeout (${name})`);
-        }
-    }
+    requireIdentity(job.definitionId, "Job definition id");
+    requirePositiveInteger(job.definitionRevision, "Job definition revision");
+    requireText(job.trigger?.key, "Job trigger key");
+    if (!["manual", "retry", "schedule", "integration", "migration"].includes(job.trigger.source)) {
+        throw new Error("Invalid JobRun trigger source.");
+    }
+    if ("taskId" in job) {
+        validateTaskRecordReference({ taskId: job.taskId, localId: job.id }, "durableJob");
+        validateDurableJobOwner(job.owner, job.taskId);
+        requireIdentity(job.projectId, "DurableJob project id");
+    }
+    else {
+        if (job.scope !== "global")
+            throw new Error("Invalid global JobRun scope.");
+        requireIdentity(job.id, "JobRun id");
+        requireText(job.action, "JobRun builtin action");
+        if (job.projectId !== undefined)
+            requireIdentity(job.projectId, "JobRun Project id");
+    }
+    validateJobExecutionConfiguration(job);
     requireText(job.idempotencyKey, "DurableJob idempotency key");
     if (!/^[a-f0-9]{64}$/u.test(job.idempotencyKey)) {
         throw new Error("DurableJob idempotency key is invalid.");
@@ -321,7 +303,10 @@ export function validateDurableJob(job) {
         normalizeDurableJobResult(job.result);
     }
     if (job.retryOf !== undefined) {
-        validateTaskRecordReference({ taskId: job.taskId, localId: job.retryOf }, "durableJob");
+        if ("taskId" in job)
+            validateTaskRecordReference({ taskId: job.taskId, localId: job.retryOf }, "durableJob");
+        else
+            requireIdentity(job.retryOf, "JobRun retryOf");
     }
     if (job.cancelRequestedAt !== undefined) {
         requireTimestamp(job.cancelRequestedAt, "DurableJob cancelRequestedAt");
@@ -345,14 +330,18 @@ export function validateDurableJob(job) {
 }
 export function validDurableJobTransition(before, after) {
     if (before.id !== after.id
-        || before.taskId !== after.taskId
+        || before.definitionId !== after.definitionId
+        || before.definitionRevision !== after.definitionRevision
+        || !isDeepStrictEqual(before.trigger, after.trigger)
+        || before.retryOf !== after.retryOf
+        || executionNamespace(before) !== executionNamespace(after)
         || before.projectId !== after.projectId
         || before.head !== after.head
         || before.workspace !== after.workspace
         || before.idempotencyKey !== after.idempotencyKey
         || before.artifactsLocator !== after.artifactsLocator
         || before.createdAt !== after.createdAt
-        || !isDeepStrictEqual(before.owner, after.owner)
+        || !isDeepStrictEqual("owner" in before ? before.owner : [before.action, before.actionInput], "owner" in after ? after.owner : [after.action, after.actionInput])
         || !isDeepStrictEqual(before.env, after.env)
         || !isDeepStrictEqual(before.steps, after.steps)
         || before.operation.requestId !== after.operation.requestId
@@ -374,7 +363,10 @@ export function validDurableJobTransition(before, after) {
         const wakeupFlip = before.wakeupNotified !== true && after.wakeupNotified === true;
         const acknowledgeFlip = before.acknowledgedAt === undefined
             && after.acknowledgedAt !== undefined;
-        return before.status === after.status
+        const { wakeupNotified: _beforeWake, acknowledgedAt: _beforeAck, updatedAt: _beforeTime, ...beforeFacts } = before;
+        const { wakeupNotified: _afterWake, acknowledgedAt: _afterAck, updatedAt: _afterTime, ...afterFacts } = after;
+        return isDeepStrictEqual(beforeFacts, afterFacts)
+            && before.status === after.status
             && isDeepStrictEqual(before.result, after.result)
             && isDeepStrictEqual(before.operation, after.operation)
             && before.terminalAt === after.terminalAt
@@ -398,7 +390,7 @@ export function validDurableJobTransition(before, after) {
     };
     return (allowed[before.status] ?? []).includes(after.status);
 }
-function validateDurableJobOwner(owner, taskId) {
+export function validateDurableJobOwner(owner, taskId) {
     if (owner.kind === "integration-attempt") {
         validateTaskRecordReference({ taskId, localId: owner.integrationAttemptId }, "integrationAttempt");
     }
@@ -409,6 +401,37 @@ function validateDurableJobOwner(owner, taskId) {
         throw new Error(`DurableJob owner kind is invalid: ${String(owner.kind)}.`);
     }
 }
+export function validateJobExecutionConfiguration(job) {
+    requireCommit(job.head, "DurableJob head");
+    requireText(job.workspace, "DurableJob workspace");
+    if (!job.workspace.startsWith("/"))
+        throw new Error("DurableJob workspace must be an absolute path.");
+    validateEnvMap(job.env);
+    if (!Array.isArray(job.steps) || job.steps.length === 0) {
+        throw new Error("DurableJob requires at least one step.");
+    }
+    const names = new Set();
+    for (const step of job.steps) {
+        const name = requireText(step.name, "DurableJob step name");
+        if (names.has(name))
+            throw new Error(`DurableJob step names must be unique: ${name}.`);
+        names.add(name);
+        requireText(step.command, `DurableJob step command (${name})`);
+        if (step.argv !== undefined) {
+            if (!Array.isArray(step.argv) || step.argv.length === 0)
+                throw new Error("Step argv must be nonempty.");
+            for (const value of step.argv)
+                requireText(value, `DurableJob step argv (${name})`);
+        }
+        if (step.cwd !== undefined && !requireText(step.cwd, "Step cwd").startsWith("/")) {
+            throw new Error("DurableJob step cwd must be absolute.");
+        }
+        if (step.env !== undefined)
+            validateEnvMap(step.env);
+        if (step.timeoutMs !== undefined)
+            requirePositiveInteger(step.timeoutMs, "Step timeout");
+    }
+}
 function validateEnvMap(env) {
     if (typeof env !== "object" || env === null || Array.isArray(env)) {
         throw new Error("DurableJob env must be a map.");

package/dist/job/jobDefinition.js

@@ -0,0 +1,68 @@
+import { requireIdentity, requireKnownFields, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateJobExecutionConfiguration, validateDurableJobOwner } from "./durableJob.js";
+export function jobScopeKey(scope) {
+    if (scope.kind === "global")
+        return "global";
+    requireIdentity(scope.taskId, "Job Task id");
+    if (!/^task-\d+$/u.test(scope.taskId))
+        throw new Error("Invalid Job Task id.");
+    return scope.taskId;
+}
+export function validateJobDefinition(job) {
+    requireKnownFields(job, ["schemaVersion", "id", "scope", "title", "revision", "configuration", "createdAt", "updatedAt"], "Job");
+    if (job.schemaVersion !== 1)
+        throw new Error("Job schemaVersion must be 1.");
+    requireIdentity(job.id, "Job id");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(job.id))
+        throw new Error("Invalid Job definition id.");
+    requireText(job.title, "Job title");
+    requirePositiveInteger(job.revision, "Job revision");
+    requireTimestamp(job.createdAt, "Job createdAt");
+    requireTimestamp(job.updatedAt, "Job updatedAt");
+    if (job.scope.kind !== "task" && job.scope.kind !== "global")
+        throw new Error("Invalid Job scope.");
+    requireKnownFields(job.scope, job.scope.kind === "task" ? ["kind", "taskId"] : ["kind"], "Job scope");
+    jobScopeKey(job.scope);
+    const config = job.configuration;
+    if (job.scope.kind === "global") {
+        if (config.kind !== "builtin")
+            throw new Error("Global Jobs require a controlled builtin action.");
+        requireKnownFields(config, ["kind", "action", "projectId", "input"], "Builtin Job");
+        requireText(config.action, "Builtin action");
+        if (config.projectId !== undefined)
+            requireIdentity(config.projectId, "Job Project id");
+        if (config.input === undefined)
+            throw new Error("Builtin Job input is required.");
+    }
+    else {
+        if (config.kind !== "shell")
+            throw new Error("Task Jobs require a managed shell configuration.");
+        requireKnownFields(config, ["kind", "owner", "projectId", "head", "workspace", "env", "steps"], "Task Job");
+        requireIdentity(config.projectId, "Job Project id");
+        validateDurableJobOwner(config.owner, job.scope.taskId);
+        validateJobExecutionConfiguration(config);
+    }
+    return job;
+}
+export function createJobDefinition(input, now) {
+    return validateJobDefinition({
+        schemaVersion: 1, ...structuredClone(input), revision: 1,
+        createdAt: now.toISOString(), updatedAt: now.toISOString()
+    });
+}
+export function reviseJobDefinition(job, input, now) {
+    return validateJobDefinition({
+        ...job, title: input.title, configuration: structuredClone(input.configuration),
+        revision: job.revision + 1, updatedAt: now.toISOString()
+    });
+}
+/** Old execution IDs are preserved one-to-one; command equality never merges history. */
+export function definitionFromTaskRun(run) {
+    return createJobDefinition({
+        id: run.definitionId, scope: { kind: "task", taskId: run.taskId }, title: run.steps[0].name,
+        configuration: {
+            kind: "shell", owner: run.owner, projectId: run.projectId, head: run.head,
+            workspace: run.workspace, env: run.env, steps: run.steps
+        }
+    }, new Date(run.createdAt));
+}

package/dist/job/jobRunner.js

@@ -267,7 +267,8 @@ function readSpec(specPath) {
     if (typeof spec.jobId !== "string" || spec.jobId.length === 0) {
         throw new Error("DurableJob spec is missing jobId.");
     }
-    if (typeof spec.taskId !== "string" || spec.taskId.length === 0) {
+    if (spec.scope === "global" ? spec.taskId !== undefined
+        : typeof spec.taskId !== "string" || spec.taskId.length === 0) {
         throw new Error("DurableJob spec is missing taskId.");
     }
     if (typeof spec.workspace !== "string" || !spec.workspace.startsWith("/")) {

package/dist/job/projectRefreshRunner.js

@@ -0,0 +1,48 @@
+/**
+ * Controlled Project domain action invoked by the artifact-only Job runner.
+ * Its catalog connection is read-only; only the shared domain service writes Git.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SqliteTaskStore } from "../storage/sqliteStore.js";
+import { authorizeGlobalJobStart } from "../controller/jobDefinitionControl.js";
+import { refreshRegisteredProject } from "../repository/projectRefresh.js";
+import { projectRefreshDigest } from "./builtinJob.js";
+import { CliError } from "../errors/cliError.js";
+export async function runProjectRefresh(home, runId) {
+    const store = new SqliteTaskStore(home, { readonly: true });
+    try {
+        const run = store.getGlobalJobRun(runId);
+        if (!run || run.action !== "project.refresh" || !["queued", "running"].includes(run.status)
+            || run.operation.effect !== "possible" || run.cancelRequestedAt) {
+            throw new Error("No active admitted project.refresh Run.");
+        }
+        authorizeGlobalJobStart(store, run);
+        const result = await refreshRegisteredProject(store, run.projectId, {
+            automatic: true,
+            expectedDigest: projectRefreshDigest({
+                kind: "builtin", action: run.action, projectId: run.projectId, input: run.actionInput
+            }),
+            beforeRefresh: () => {
+                const current = store.getGlobalJobRun(runId);
+                if (!current || !["queued", "running"].includes(current.status) || current.cancelRequestedAt) {
+                    throw new Error("Project refresh Run stopped while waiting for maintenance.");
+                }
+                authorizeGlobalJobStart(store, current);
+            }
+        });
+        process.stdout.write(JSON.stringify({ action: run.action, projectId: run.projectId,
+            trigger: run.trigger, outcome: "succeeded", observedAt: new Date().toISOString(),
+            remoteCheck: { status: "verified", commit: result.toCommit }, refresh: result }) + "\n");
+    }
+    finally {
+        store.close();
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    runProjectRefresh(process.argv[2], process.argv[3]).catch(error => {
+        process.stderr.write(JSON.stringify({ outcome: "failed", reason: error instanceof Error ? error.message : String(error),
+            ...(error instanceof CliError ? { details: error.details } : {}) }) + "\n");
+        process.exitCode = 1;
+    });
+}

package/dist/repository/projectRefresh.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { CliError, usageError } from "../errors/cliError.js";
+import { assertProjectActive } from "./project.js";
+import { GitWorkspaceRefreshError, NodeGitWorkspace } from "./gitWorkspace.js";
+import { acquireProjectMaintenanceLock } from "./projectMaintenanceLock.js";
+/** Bind maintenance intent to catalog identity, not a caller-supplied path. */
+export function projectRefreshTargetDigest(project) {
+    return createHash("sha256").update(JSON.stringify([
+        project.id, project.path, project.remoteUrl, project.stableBranch,
+        project.developmentBranch, project.ownership, project.status
+    ])).digest("hex");
+}
+export function requireRefreshProject(store, id, automatic = false) {
+    const project = store.listProjects().find(project => project.id === id);
+    if (!project)
+        throw usageError(`Project not found: ${id}.`);
+    assertProjectActive(project, "refresh");
+    if (automatic && project.ownership !== "managed") {
+        throw usageError(`Automatic Project refresh requires a managed Project: ${id}.`);
+    }
+    if (project.remoteUrl === undefined)
+        throw usageError(`Project refresh requires a remote URL: ${id}.`);
+    if (project.stableBranch !== project.developmentBranch) {
+        throw usageError(`Project refresh requires matching stable and development branches: ${id}.`);
+    }
+    return project;
+}
+/** Shared manual/background operation. Waiting never authorizes a changed target. */
+export async function refreshRegisteredProject(store, id, options = {}) {
+    const project = requireRefreshProject(store, id, options.automatic);
+    const expected = options.expectedDigest ?? projectRefreshTargetDigest(project);
+    const check = () => {
+        const current = requireRefreshProject(store, id, options.automatic);
+        if (projectRefreshTargetDigest(current) !== expected) {
+            throw new Error(`Project changed while waiting to refresh: ${id}; read current state before retrying.`);
+        }
+        return current;
+    };
+    check();
+    const release = await acquireProjectMaintenanceLock(store.rootDirectory(), id, { signal: options.signal });
+    try {
+        const current = check();
+        options.beforeRefresh?.();
+        const refreshed = await (options.git ?? new NodeGitWorkspace()).refresh({
+            repositoryPath: current.path, remoteUrl: current.remoteUrl, stableRef: current.stableBranch
+        });
+        return { project: current, ...refreshed };
+    }
+    catch (error) {
+        if (error instanceof GitWorkspaceRefreshError) {
+            throw new CliError("RUNTIME_ERROR", error.message, undefined, { projectId: id, refresh: error.result });
+        }
+        throw error;
+    }
+    finally {
+        release();
+    }
+}

package/dist/repository/taskWorkspacePreparer.js

@@ -2,6 +2,7 @@ import { lstat, mkdir, readdir, readlink, rmdir, symlink, unlink } from "node:fs
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { recordArchiveCleanup } from "../task/archiveDiagnostics.js";
+import { activationWakeRefs } from "../context/taskPhase.js";
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { createTaskEvent } from "../event/taskEvent.js";
 import { retireTaskRoleSessionsForWorkspace, updateRoleAgentSessionStatus } from "../executor/agentExecutor.js";
@@ -2282,7 +2283,7 @@ export class FileTaskWorkspacePreparer {
 function recordTaskActivation(store, previous, active, now, actor) {
     // Activation is the explicit request to enter delivery, not an ordinary
     // Leader-local edit. Preserve that transition for the replacement Session.
-    enqueueWork(store, { kind: "role", taskId: active.id, roleName: LEADER_ROLE }, "execution-started", now, [{ type: "task", id: active.id }]);
+    enqueueWork(store, { kind: "role", taskId: active.id, roleName: LEADER_ROLE }, "execution-started", now, [{ type: "task", id: active.id }, ...activationWakeRefs(store, active)]);
     enqueueWork(store, { kind: "task", taskId: active.id }, "task-activated", now, [{ type: "task", id: active.id }]);
     store.saveEvent(active.id, createTaskEvent(store.nextEventId(active.id), active.id, "task.activated", { fromStatus: previous.status, status: active.status, by: actor }, now));
 }

package/dist/schedule/schedule.js

@@ -0,0 +1,108 @@
+import { CronExpressionParser } from "cron-parser";
+import { requireKnownFields, requirePositiveInteger, requireTimestamp, requireText } from "../domain/validation.js";
+import { jobScopeKey } from "../job/jobDefinition.js";
+export function scheduleId(id) {
+    if (typeof id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(id)) {
+        throw new Error("An explicit safe Schedule/Job id is required.");
+    }
+}
+function instant(value) {
+    requireTimestamp(value, "Schedule instant");
+    if (!/(?:Z|[+-]\d{2}:\d{2})$/u.test(value))
+        throw new Error("Schedule instants require an explicit UTC offset.");
+}
+export function validateScheduleRule(rule) {
+    if (rule?.kind === "once") {
+        requireKnownFields(rule, ["kind", "at"], "Once rule");
+        instant(rule.at);
+    }
+    else if (rule?.kind === "interval") {
+        requireKnownFields(rule, ["kind", "anchor", "everyMs"], "Interval rule");
+        instant(rule.anchor);
+        if (!Number.isSafeInteger(rule.everyMs) || rule.everyMs < 1000)
+            throw new Error("Interval everyMs must be an integer of at least 1000.");
+    }
+    else if (rule?.kind === "cron") {
+        requireKnownFields(rule, ["kind", "expression", "timezone"], "Cron rule");
+        if (typeof rule.timezone !== "string" || !rule.timezone.trim())
+            throw new Error("An explicit IANA timezone is required.");
+        new Intl.DateTimeFormat("en", { timeZone: rule.timezone });
+        if (typeof rule.expression !== "string" || rule.expression.trim().split(/\s+/u).length !== 5
+            || /\bH\b/iu.test(rule.expression))
+            throw new Error("Cron requires five fields and does not support random H.");
+        CronExpressionParser.parse(rule.expression, { tz: rule.timezone, currentDate: "2026-01-01T00:00:00Z" });
+    }
+    else
+        throw new Error("Unknown Schedule rule.");
+    return rule;
+}
+/** Strictly after the fence; once returns null after its single occurrence. */
+export function nextScheduleDue(rule, after) {
+    validateScheduleRule(rule);
+    const at = after.getTime();
+    if (rule.kind === "once")
+        return Date.parse(rule.at) > at ? new Date(rule.at).toISOString() : null;
+    if (rule.kind === "interval") {
+        const anchor = Date.parse(rule.anchor);
+        return new Date(anchor + Math.max(0, Math.floor((at - anchor) / rule.everyMs) + 1) * rule.everyMs).toISOString();
+    }
+    return CronExpressionParser.parse(rule.expression, { currentDate: after, tz: rule.timezone }).next().toISOString();
+}
+export function validateSchedule(value) {
+    requireKnownFields(value, ["schemaVersion", "id", "scope", "jobId", "rule", "revision", "generation",
+        "state", "nextDue", "processedThrough", "authorization", "lastAttempt", "reason", "createdAt", "updatedAt"], "Schedule");
+    if (value.schemaVersion !== 1)
+        throw new Error("Invalid Schedule schema.");
+    scheduleId(value.id);
+    scheduleId(value.jobId);
+    if (!["task", "global"].includes(value.scope.kind))
+        throw new Error("Invalid Schedule scope.");
+    requireKnownFields(value.scope, value.scope.kind === "task" ? ["kind", "taskId"] : ["kind"], "Schedule scope");
+    jobScopeKey(value.scope);
+    validateScheduleRule(value.rule);
+    requirePositiveInteger(value.revision, "Schedule revision");
+    requirePositiveInteger(value.generation, "Schedule generation");
+    if (!["enabled", "disabled", "completed", "needs-attention", "retired"].includes(value.state))
+        throw new Error("Invalid Schedule state.");
+    if (value.state === "enabled" && value.nextDue === null)
+        throw new Error("Enabled Schedule requires nextDue.");
+    if (value.state === "completed" && (value.rule.kind !== "once" || value.nextDue !== null))
+        throw new Error("Only an admitted once Schedule is completed.");
+    if (value.nextDue !== null)
+        instant(value.nextDue);
+    if (value.processedThrough !== undefined)
+        instant(value.processedThrough);
+    instant(value.createdAt);
+    instant(value.updatedAt);
+    requireKnownFields(value.authorization, ["caller", "binding", "jobRevision"], "Schedule authorization");
+    requirePositiveInteger(value.authorization.jobRevision, "Schedule Job revision");
+    if (typeof value.authorization.binding !== "string" || !/^[a-f0-9]{64}$/u.test(value.authorization.binding))
+        throw new Error("Invalid Schedule authority binding.");
+    const caller = value.authorization.caller;
+    requireKnownFields(caller, ["scope", "taskId", "role", "agentId", "adapterId", "nativeSessionId", "runId"], "Schedule caller");
+    if (typeof caller.role !== "string" || typeof caller.nativeSessionId !== "string")
+        throw new Error("Schedule authority requires a Role and Session.");
+    requireText(caller.role, "Schedule caller role");
+    requireText(caller.nativeSessionId, "Schedule caller Session");
+    if (caller.scope === "global") {
+        if (caller.role !== "operator")
+            throw new Error("Global Schedule authority requires Operator.");
+    }
+    else if (caller.scope !== "task" || value.scope.kind !== "task" || caller.taskId !== value.scope.taskId) {
+        throw new Error("Schedule caller must belong to its scope.");
+    }
+    if (value.reason !== undefined)
+        requireText(value.reason, "Schedule reason");
+    if (value.lastAttempt !== undefined) {
+        requireKnownFields(value.lastAttempt, ["at", "dueAt", "outcome", "runId", "reason"], "Schedule attempt");
+        instant(value.lastAttempt.at);
+        instant(value.lastAttempt.dueAt);
+        if (!["admitted", "overlap", "blocked"].includes(value.lastAttempt.outcome))
+            throw new Error("Invalid Schedule attempt.");
+        if (value.lastAttempt.runId !== undefined)
+            requireText(value.lastAttempt.runId, "Schedule Run id");
+        if (value.lastAttempt.reason !== undefined)
+            requireText(value.lastAttempt.reason, "Schedule attempt reason");
+    }
+    return value;
+}

package/dist/scheduler/operatorEvent.js

@@ -16,6 +16,8 @@ export function claimOperatorAttention(mailbox, options) {
         || pending.toSequence - pending.fromSequence + 1 !== pending.requestCount
         || pending.dedupeKeys.some((key, index) => {
             const ref = pending.refs[index];
+            if (ref.type === "global-job-run")
+                return key !== `operator-global-job-run:${ref.id}`;
             return (ref.type !== "event" && ref.type !== "input")
                 || key !== `operator-${ref.type}:${ref.taskId}:${ref.id}`
                     && key !== `sequence:${pending.fromSequence + index}`;

package/dist/scheduler/operatorInputNotificationProcessor.js

@@ -20,6 +20,10 @@ export async function processOperatorInputNotifications(store, selection, now =
         return [];
     const processing = claim.processing;
     const attentions = deduplicateAttention(processing.batch.refs.flatMap((ref) => {
+        if (ref.type === "global-job-run") {
+            const run = store.getGlobalJobRun?.(ref.id);
+            return run == null ? [] : [{ kind: "global-job-run", run }];
+        }
         if (ref.type === "input") {
             const request = store.getInputRequest(ref.taskId, ref.id);
             return request !== null && request.status === "open"
@@ -70,6 +74,8 @@ function skipped(attention, reason) {
     };
 }
 function attentionIdentity(attention) {
+    if (attention.kind === "global-job-run")
+        return { sourceKind: "global-job-run", sourceId: attention.run.id };
     return attention.kind === "input"
         ? {
             sourceKind: "input",
@@ -83,6 +89,8 @@ function attentionIdentity(attention) {
         };
 }
 function toPresentationItem(attention) {
+    if (attention.kind === "global-job-run")
+        return attention;
     return attention.kind === "input"
         ? { kind: "input-request", request: attention.request }
         : { kind: "task-event", event: attention.event };

package/dist/storage/contextRecords.js

@@ -98,6 +98,14 @@ export function queryContextRecords(db, taskId, query) {
     const sequence = `CAST(substr(r.${key}, length(r.${key}) - length(ltrim(r.${key}, 'abcdefghijklmnopqrstuvwxyz-')) + 1) AS INTEGER)`;
     // Task-local numeric IDs are the stable historical order, not lexical 1,10,2.
     if (query.family === "task-event") {
+        if (query.eventRequestId !== undefined) {
+            where.push("json_extract(r.payload, '$.payload.requestId') = @requestId");
+            params.requestId = query.eventRequestId;
+        }
+        if (query.eventMessageId !== undefined) {
+            where.push("json_extract(r.payload, '$.payload.messageId') = @messageId");
+            params.messageId = query.eventMessageId;
+        }
         if (query.eventTypes !== undefined) {
             where.push("r.type IN (SELECT value FROM json_each(@types))");
             params.types = JSON.stringify(query.eventTypes);

package/dist/storage/jobSchema.js

@@ -0,0 +1,15 @@
+/** Additive DDL for storage 1.9; the published baseline is unchanged. */
+export const JOB_SCHEMA_SQL = `
+CREATE TABLE job_definitions (
+  scope_key TEXT NOT NULL,
+  definition_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (scope_key, definition_id)
+);
+CREATE TABLE global_job_runs (
+  run_id TEXT PRIMARY KEY,
+  payload TEXT NOT NULL,
+  status TEXT NOT NULL
+);
+CREATE INDEX idx_global_job_runs_status ON global_job_runs(status);
+`;

package/dist/storage/maintenanceCaller.js

@@ -22,7 +22,7 @@ export function maintenanceCallerEnvironment(home, env, operatorOnly = true) {
             if (storageMinorUpgradePlan(schema.currentVersion) === null) {
                 throw new ManagedRuntimeDriftError("Maintenance cannot authenticate an unsupported Home storage version.");
             }
-            validateSqliteSchemaObjects(db);
+            validateSqliteSchemaObjects(db, schema.currentVersion);
             const read = (table, where, params) => {
                 const row = db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).get(...params);
                 if (!row)