@zq-silk/yui 2.8.0 → 2.9.0

package/dist/storage/maintenanceCaller.js

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import Database from "../sqlite/driver.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
+import { ManagedRuntimeDriftError, requireManagedGlobalCaller } from "../runtime/managedCaller.js";
+import { sessionCallerEnvironment } from "../runtime/sessionCaller.js";
+import { validateStoredRecord } from "./recordValidation.js";
+import { inspectSqliteSchema, storageMinorUpgradePlan, validateSqliteSchemaObjects } from "./sqliteSchema.js";
+import { CURRENT_DATABASE_FILENAME } from "./storageSchema.js";
+/**
+ * Maintenance must authenticate before migration, without opening a current-only
+ * business Store. The declared 1.x migrations preserve these Role/Session
+ * envelopes and physical tables. Read only those records in one SQLite snapshot;
+ * this grants no old-format business reads, writes or implicit migration.
+ */
+export function maintenanceCallerEnvironment(home, env, operatorOnly = true) {
+    if (!hasManagedIdentity(env))
+        return env;
+    const db = new Database(join(home, CURRENT_DATABASE_FILENAME), { readonly: true, fileMustExist: true });
+    try {
+        return db.transaction(() => {
+            const schema = inspectSqliteSchema(db);
+            if (storageMinorUpgradePlan(schema.currentVersion) === null) {
+                throw new ManagedRuntimeDriftError("Maintenance cannot authenticate an unsupported Home storage version.");
+            }
+            validateSqliteSchemaObjects(db, schema.currentVersion);
+            const read = (table, where, params) => {
+                const row = db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).get(...params);
+                if (!row)
+                    return null;
+                const value = JSON.parse(row.payload);
+                validateStoredRecord(table, value);
+                return value;
+            };
+            const registry = {
+                getGlobalRole: (name) => read("global_roles", "name=?", [name]),
+                getGlobalRoleSessionSet: (name) => read("global_role_session_sets", "name=?", [name]),
+                getTaskRoleSessionSet: (task, role) => read("role_session_sets", "task_id=? AND role_name=?", [task, role]),
+                listRuntimeSessionCandidates: () => {
+                    // Read canonical sets, not a derived index that could be stale. Only
+                    // active bindings participate, exactly as in normal caller discovery.
+                    const rows = db.prepare(`
+            SELECT 'global_role_session_sets' AS source, payload FROM global_role_session_sets
+            UNION ALL SELECT 'role_session_sets' AS source, payload FROM role_session_sets
+          `).all();
+                    return rows.flatMap(row => {
+                        const set = JSON.parse(row.payload);
+                        validateStoredRecord(row.source, set);
+                        const session = set.sessions[set.activeAgentId];
+                        if (!session || session.status !== "active")
+                            return [];
+                        return [{ owner: set.owner, agentId: session.agentId, adapterId: session.adapterId,
+                                nativeSessionId: session.nativeSessionId, sessionUpdatedAt: set.updatedAt }];
+                    });
+                }
+            };
+            const current = sessionCallerEnvironment(registry, env);
+            if (current.YUI_SESSION_SCOPE !== "global" || current.YUI_ROLE !== "operator") {
+                if (!operatorOnly)
+                    return current; // Doctor keeps normal scoped authorization below.
+                throw new ManagedRuntimeDriftError("Home maintenance requires the user or current Operator, not a Task or custom Role.");
+            }
+            requireManagedGlobalCaller(registry, current);
+            return current;
+        })();
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/storage/recordValidation.js

@@ -8,6 +8,8 @@ import { validateInputRequest } from "../input/inputRequest.js";
 import { validateChangeSet } from "../integration/changeSet.js";
 import { validateIntegrationAttempt } from "../integration/integrationAttempt.js";
 import { validateDurableJob } from "../job/durableJob.js";
+import { validateJobDefinition } from "../job/jobDefinition.js";
+import { validateSchedule } from "../schedule/schedule.js";
 import { validateGlobalRoleMessage, validateTaskMessage } from "../message/message.js";
 import { validateMilestone } from "../milestone/milestone.js";
 import { validatePluginIntent } from "../plugins/pluginIntent.js";
@@ -54,6 +56,9 @@ const validators = {
     change_sets: check(validateChangeSet),
     integration_attempts: check(validateIntegrationAttempt),
     durable_jobs: check(validateDurableJob),
+    job_definitions: check(validateJobDefinition),
+    schedules: check(validateSchedule),
+    global_job_runs: check(validateDurableJob),
     context_snapshots: check(validateContextSnapshot),
     managed_workspaces: check(validateManagedWorkspace),
     input_requests: check(validateInputRequest),

package/dist/storage/scheduleSchema.js

@@ -0,0 +1,12 @@
+/** Additive storage 1.9 -> 1.10. No old records are rewritten. */
+export const SCHEDULE_SCHEMA_SQL = `
+CREATE TABLE schedules (
+  scope_key TEXT NOT NULL,
+  schedule_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  state TEXT NOT NULL,
+  next_due TEXT,
+  PRIMARY KEY(scope_key, schedule_id)
+);
+CREATE INDEX idx_schedules_due ON schedules(state, next_due);
+`;

package/dist/storage/sqliteSchema.js

@@ -1,13 +1,20 @@
 import { createHash } from "node:crypto";
 import Database from "../sqlite/driver.js";
-import { BASELINE_SCHEMA_SQL, SQLITE_SCHEMA_TABLES } from "./baselineSchema.js";
+import { BASELINE_SCHEMA_SQL, SQLITE_SCHEMA_TABLES as BASELINE_SCHEMA_TABLES } from "./baselineSchema.js";
 import { migrateTaskMainWorkspaces } from "./upgrade/taskMainWorkspaceMigration.js";
 import { migrateProjectKnowledge } from "./upgrade/projectKnowledgeMigration.js";
+import { JOB_SCHEMA_SQL } from "./jobSchema.js";
+import { SCHEDULE_SCHEMA_SQL } from "./scheduleSchema.js";
+import { migrateJobDefinitions } from "./upgrade/jobDefinitionMigration.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION, STORAGE_FORMAT, isMinorStorageUpgrade, isStorageVersion, storageVersionParts } from "./storageVersions.js";
-export { BASELINE_SCHEMA_SQL, SQLITE_SCHEMA_TABLES };
+export { BASELINE_SCHEMA_SQL };
+export const SQLITE_SCHEMA_TABLES = [...BASELINE_SCHEMA_TABLES, "job_definitions", "global_job_runs", "schedules"];
 export const TELEMETRY_KEEP_PER_RUN = 200;
 export const TELEMETRY_RUN_CAP = 50_000;
-export const CURRENT_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_SQL).digest("hex");
+export const BASELINE_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_SQL).digest("hex");
+export const JOB_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL).digest("hex");
+export const CURRENT_SCHEMA_SQL = BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL + SCHEDULE_SCHEMA_SQL;
+export const CURRENT_SCHEMA_CHECKSUM = createHash("sha256").update(CURRENT_SCHEMA_SQL).digest("hex");
 export class SqliteSchemaError extends Error {
     code;
     constructor(detail, code = "STORAGE_SCHEMA_INVALID") {
@@ -21,8 +28,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.1",
         name: "task-main-workspace",
         introducedIn: "1.1.0",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         sql: "",
         dataMigration: "task-main-workspace"
     }, {
@@ -30,8 +37,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.2",
         name: "task-authorization-source",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // New grants can carry source evidence. Valid historical Operator grants
         // remain unchanged; migration must not invent authorization provenance.
         sql: ""
@@ -40,8 +47,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.3",
         name: "selected-session-input",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // Optional explicit Session fences apply only to new inputs. Preserve old
         // Role-addressed messages; never infer a historical user's Session choice.
         sql: ""
@@ -50,8 +57,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.4",
         name: "project-knowledge-applicability",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         sql: "",
         dataMigration: "project-knowledge"
     }, {
@@ -59,8 +66,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.5",
         name: "frozen-skill-packages",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // Additive effective-launch/manifest package evidence. Historical envelopes
         // and their digests remain unchanged: absence explicitly means entrypoint-only
         // provenance, not an invitation to invent packages from today's source files.
@@ -72,8 +79,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.6",
         name: "runtime-cost-evidence",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // Optional sourced monetary observations; historical missing costs stay unknown.
         sql: ""
     }, {
@@ -81,8 +88,8 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.7",
         name: "agent-inbox-consumption",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // Additive handling receipts on canonical Messages and wakes. Never invent
         // historical processing or Provider acceptance; existing records stay intact.
         sql: ""
@@ -91,11 +98,41 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.8",
         name: "model-management-connection",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: BASELINE_SCHEMA_CHECKSUM,
         // Optional non-secret connection references. Existing Homes remain unconfigured;
         // never infer local credentials or adopt an existing external service.
         sql: ""
+    }, {
+        fromVersion: "1.8",
+        toVersion: "1.9",
+        name: "job-definitions-and-runs",
+        introducedIn: "next",
+        sourceChecksum: BASELINE_SCHEMA_CHECKSUM,
+        targetChecksum: JOB_SCHEMA_CHECKSUM,
+        sql: JOB_SCHEMA_SQL,
+        dataMigration: "job-definitions"
+    }, {
+        fromVersion: "1.9",
+        toVersion: "1.10",
+        name: "persistent-schedules",
+        introducedIn: "next",
+        sourceChecksum: JOB_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sql: SCHEDULE_SCHEMA_SQL
+    }, {
+        fromVersion: "1.10",
+        toVersion: "1.11",
+        name: "activation-input-provenance",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Activation event payloads may now name an exact input or contain attributed
+        // native input text. Existing events remain immutable; missing old provenance
+        // stays explicitly missing. No historical source is guessed from timestamps.
+        // New Task Job semantic writes also append job.state-changed events; no old
+        // Job history is backfilled and the SQL layout remains unchanged.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)
@@ -118,13 +155,24 @@ function objects(db) {
     return db.prepare(`SELECT type,name,sql FROM sqlite_master
     WHERE name NOT GLOB 'sqlite_*' ORDER BY type,name`).all();
 }
-let expectedObjects;
-function validateSchemaObjects(db) {
+const schemaObjectsByChecksum = new Map();
+export function validateSqliteSchemaObjects(db, version = CURRENT_STORAGE_VERSION) {
+    // Maintenance authenticates before migration. Validate the declared source
+    // layout, not current-only tables that the migration has yet to create.
+    const checksum = version === CURRENT_STORAGE_VERSION
+        ? CURRENT_SCHEMA_CHECKSUM : storageMinorUpgradePlan(version)?.[0]?.sourceChecksum;
+    const sql = checksum === CURRENT_SCHEMA_CHECKSUM ? CURRENT_SCHEMA_SQL
+        : checksum === JOB_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL
+            : checksum === BASELINE_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL : undefined;
+    if (sql === undefined || checksum === undefined)
+        throw new SqliteSchemaError(`unsupported schema definition for storage ${version}.`);
+    let expectedObjects = schemaObjectsByChecksum.get(checksum);
     if (expectedObjects === undefined) {
         const reference = new Database(":memory:");
         try {
-            reference.exec(BASELINE_SCHEMA_SQL);
+            reference.exec(sql);
             expectedObjects = objects(reference);
+            schemaObjectsByChecksum.set(checksum, expectedObjects);
         }
         finally {
             reference.close();
@@ -134,7 +182,7 @@ function validateSchemaObjects(db) {
     for (const expected of expectedObjects) {
         const found = actual.find(object => object.type === expected.type && object.name === expected.name);
         if (found?.sql !== expected.sql)
-            throw new SqliteSchemaError(`required ${expected.type} '${expected.name}' differs from the current definition.`);
+            throw new SqliteSchemaError(`required ${expected.type} '${expected.name}' differs from the storage ${version} definition.`);
     }
     if (actual.length !== expectedObjects.length)
         throw new SqliteSchemaError("unexpected schema objects; preserve the database for diagnosis.");
@@ -161,7 +209,7 @@ export function inspectSqliteSchema(db) {
         throw new SqliteSchemaError("baseline checksum does not match its version.");
     }
     if (version === CURRENT_STORAGE_VERSION)
-        validateSchemaObjects(db);
+        validateSqliteSchemaObjects(db);
     return {
         currentVersion: version, currentChecksum: row.checksum,
         targetVersion: CURRENT_STORAGE_VERSION, targetChecksum: CURRENT_SCHEMA_CHECKSUM,
@@ -183,7 +231,7 @@ export function initializeSqliteSchema(db) {
     }
     const { major, minor } = storageVersionParts(CURRENT_STORAGE_VERSION);
     return db.transaction(() => {
-        db.exec(BASELINE_SCHEMA_SQL);
+        db.exec(CURRENT_SCHEMA_SQL);
         db.prepare("INSERT INTO storage_schema VALUES (1,?,?,?,?,?)")
             .run(STORAGE_FORMAT, major, minor, CURRENT_SCHEMA_CHECKSUM, new Date().toISOString());
         return validateSqliteSchema(db);
@@ -207,6 +255,8 @@ export function applySqliteMinorUpgrades(db, home, createdRoots = []) {
             }
             if (step.dataMigration === "project-knowledge")
                 migrateProjectKnowledge(db);
+            if (step.dataMigration === "job-definitions")
+                migrateJobDefinitions(db);
             const { major, minor } = storageVersionParts(step.toVersion);
             db.prepare("UPDATE storage_schema SET major=?,minor=?,checksum=? WHERE id=1")
                 .run(major, minor, step.targetChecksum);

package/dist/storage/sqliteStore.js

@@ -40,6 +40,7 @@ import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { validateTaskBrief } from "../brief/taskBrief.js";
 import { validateContextSnapshot } from "../context/contextSnapshot.js";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
+import { createTaskEvent } from "../event/taskEvent.js";
 import { enqueueDurableOperatorFact } from "../scheduler/operatorEvent.js";
 import { validateDurableJob, validDurableJobTransition } from "../job/durableJob.js";
 import { validateGlobalRoleMessage } from "../message/message.js";
@@ -60,6 +61,8 @@ import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
 import { operationalTaskRecords, TASK_RECORD_RETIRED_EVENT } from "../task/taskRecordRetirement.js";
 import { writeTelemetryBatch } from "../telemetry/sqliteTelemetryBatch.js";
 import { STORED_RECORD_TABLES, validateStoredRecord } from "./recordValidation.js";
+import { jobScopeKey, validateJobDefinition } from "../job/jobDefinition.js";
+import { validateSchedule } from "../schedule/schedule.js";
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
 import { validateWorkItem } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
@@ -1056,6 +1059,25 @@ export class SqliteTaskStore {
             throw new StorageRecordError("Task id is required.");
         }
         this.#mutate(() => {
+            const schedules = this.listSchedules({ kind: "task", taskId: task.id });
+            if (task.status === "completed" && schedules.some(s => s.rule.kind === "once"
+                && (s.state === "enabled" || s.state === "needs-attention"))) {
+                throw new StorageRecordError("Task has unfulfilled once Schedules; inspect and explicitly disable them before completion.");
+            }
+            if (["completed", "cancelled", "archived"].includes(task.status)) {
+                for (const schedule of schedules.filter(s => s.state === "enabled" || s.state === "needs-attention")) {
+                    this.saveSchedule({ ...schedule, state: "retired", revision: schedule.revision + 1,
+                        reason: `Task ${task.status}; no future admission. Pending intent and Run history retained.`,
+                        updatedAt: task.updatedAt });
+                }
+            }
+            else if (task.executionGate.state === "stopped") {
+                for (const schedule of schedules.filter(s => s.state === "enabled")) {
+                    this.saveSchedule({ ...schedule, state: "needs-attention", revision: schedule.revision + 1,
+                        reason: "Task execution stopped; inspect and explicitly enable after execution resumes.",
+                        updatedAt: task.updatedAt });
+                }
+            }
             for (const binding of task.projectBindings) {
                 const found = this.#db.prepare("SELECT 1 FROM projects WHERE id = ?").get(binding.projectId);
                 if (found === undefined)
@@ -1234,6 +1256,71 @@ export class SqliteTaskStore {
         return this.#getPayload("integration_attempts", "task_id = ? AND integration_id = ?", [taskId, integrationId]);
     }
     // -- durable jobs -----------------------------------------------------------
+    saveSchedule(schedule) {
+        validateSchedule(schedule);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO schedules VALUES(?,?,?,?,?)
+        ON CONFLICT(scope_key,schedule_id) DO UPDATE SET payload=excluded.payload,state=excluded.state,next_due=excluded.next_due`)
+                .run(jobScopeKey(schedule.scope), schedule.id, this.#recordJson("schedules", schedule), schedule.state, schedule.nextDue);
+        });
+    }
+    getSchedule(scope, id) {
+        return this.#getPayload("schedules", "scope_key=? AND schedule_id=?", [jobScopeKey(scope), id]);
+    }
+    listSchedules(scope) {
+        return this.#listPayload("schedules", "scope_key=?", [jobScopeKey(scope)]);
+    }
+    listDueSchedules(now, limit) {
+        const rows = this.#db.prepare(`SELECT payload FROM schedules
+      WHERE state='enabled' AND next_due<=?
+      ORDER BY COALESCE(json_extract(payload,'$.lastAttempt.at'),''),next_due,scope_key,schedule_id LIMIT ?`).all(now, limit);
+        return rows.map(row => validateSchedule(JSON.parse(row.payload)));
+    }
+    saveJobDefinition(job) {
+        validateJobDefinition(job);
+        if (job.scope.kind === "task")
+            this.#requireTask(job.scope.taskId);
+        const previous = this.getJobDefinition(job.scope, job.id);
+        if (previous !== null && (job.revision !== previous.revision + 1
+            || job.createdAt !== previous.createdAt || Date.parse(job.updatedAt) < Date.parse(previous.updatedAt))) {
+            throw new StorageRecordError("Job definition revision changed; reload before editing.");
+        }
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO job_definitions VALUES(?,?,?)
+        ON CONFLICT(scope_key,definition_id) DO UPDATE SET payload=excluded.payload`)
+                .run(jobScopeKey(job.scope), job.id, this.#recordJson("job_definitions", job));
+        });
+    }
+    getJobDefinition(scope, id) {
+        return this.#getPayload("job_definitions", "scope_key=? AND definition_id=?", [jobScopeKey(scope), id]);
+    }
+    listJobDefinitions(scope) {
+        return this.#listPayload("job_definitions", "scope_key=?", [jobScopeKey(scope)]);
+    }
+    saveGlobalJobRun(run) {
+        validateDurableJob(run);
+        if ("taskId" in run || run.scope !== "global")
+            throw new StorageRecordError("Global Run cannot have a Task.");
+        const previous = this.getGlobalJobRun(run.id);
+        if (previous !== null && (!validDurableJobTransition(previous, run)
+            || Date.parse(run.updatedAt) < Date.parse(previous.updatedAt))) {
+            throw new StorageRecordError("Invalid global JobRun transition.");
+        }
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO global_job_runs VALUES(?,?,?)
+        ON CONFLICT(run_id) DO UPDATE SET payload=excluded.payload,status=excluded.status`)
+                .run(run.id, this.#recordJson("global_job_runs", run), run.status);
+        });
+    }
+    getGlobalJobRun(id) {
+        return this.#getPayload("global_job_runs", "run_id=?", [id]);
+    }
+    listGlobalJobRuns() {
+        return this.#listPayload("global_job_runs", "1=1", []);
+    }
+    listActiveGlobalJobRuns() {
+        return this.#listPayload("global_job_runs", "status IN ('queued','running')", []);
+    }
     nextDurableJobId(taskId) {
         return this.#nextTaskRecordId(taskId, "durableJob");
     }
@@ -1243,21 +1330,35 @@ export class SqliteTaskStore {
         }
         validateDurableJob(job);
         this.#requireTask(taskId);
-        const existing = this.getDurableJob(taskId, job.id);
-        if (existing !== null) {
-            if (Date.parse(job.updatedAt) < Date.parse(existing.updatedAt)) {
-                throw new StorageRecordError(`DurableJob updatedAt cannot move backwards: ${job.id}`);
-            }
-            if (!validDurableJobTransition(existing, job)) {
-                throw new StorageRecordError(`DurableJob transition is invalid: ${job.id}`);
-            }
-        }
         this.#mutate(() => {
+            const existing = this.getDurableJob(taskId, job.id);
+            if (existing !== null) {
+                if (Date.parse(job.updatedAt) < Date.parse(existing.updatedAt)) {
+                    throw new StorageRecordError(`DurableJob updatedAt cannot move backwards: ${job.id}`);
+                }
+                if (!validDurableJobTransition(existing, job)) {
+                    throw new StorageRecordError(`DurableJob transition is invalid: ${job.id}`);
+                }
+            }
             this.#db.prepare(`INSERT INTO durable_jobs (job_id, task_id, idempotency_key, status, payload, created_at, updated_at)
          VALUES (?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(task_id, job_id) DO UPDATE SET idempotency_key = excluded.idempotency_key,
            status = excluded.status,
            payload = excluded.payload, updated_at = excluded.updated_at`).run(job.id, taskId, job.idempotencyKey ?? null, job.status, this.#recordJson("durable_jobs", job), job.createdAt, job.updatedAt);
+            // All Task Job writers share this boundary (including cancellation and
+            // unknown-result acknowledgement). Publish semantic changes atomically;
+            // heartbeat/checkpoint/notification bookkeeping is deliberately excluded.
+            if (existing === null || existing.status !== job.status
+                || !isDeepStrictEqual(existing.result, job.result)
+                || existing.cancelRequestedAt !== job.cancelRequestedAt
+                || existing.acknowledgedAt !== job.acknowledgedAt) {
+                this.saveEvent(taskId, createTaskEvent(this.nextEventId(taskId), taskId, "job.state-changed", {
+                    jobId: job.id, status: job.status,
+                    ...(existing === null ? {} : { previousStatus: existing.status }),
+                    ...(job.cancelRequestedAt === undefined ? {} : { cancelRequestedAt: job.cancelRequestedAt }),
+                    ...(job.acknowledgedAt === undefined ? {} : { acknowledgedAt: job.acknowledgedAt })
+                }, new Date(job.updatedAt)));
+            }
         });
     }
     listDurableJobs(taskId) {

package/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.8";
+export const CURRENT_STORAGE_VERSION = "1.11";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

package/dist/storage/storeRpc.js

@@ -70,6 +70,11 @@ const READ_ONLY_STORE_METHODS = new Set([
     "listIntegrationAttempts",
     "getIntegrationAttempt",
     "listActiveDurableJobs",
+    "getJobDefinition",
+    "listJobDefinitions",
+    "getGlobalJobRun",
+    "listGlobalJobRuns",
+    "listActiveGlobalJobRuns",
     "listRoles",
     "getRole",
     "listManagedWorkspaces",

package/dist/storage/upgrade/jobDefinitionMigration.js

@@ -0,0 +1,22 @@
+import { validateDurableJob } from "../../job/durableJob.js";
+import { definitionFromTaskRun } from "../../job/jobDefinition.js";
+export function migrateJobDefinitions(db) {
+    const rows = db.prepare("SELECT task_id, job_id, payload FROM durable_jobs").all();
+    for (const row of rows) {
+        const original = JSON.parse(row.payload);
+        if (original.taskId !== row.task_id || original.id !== row.job_id
+            || original.definitionId !== undefined || original.definitionRevision !== undefined || original.trigger !== undefined) {
+            throw new Error(`Invalid 1.8 Job identity: ${row.task_id}/${row.job_id}.`);
+        }
+        const run = validateDurableJob({
+            ...original, definitionId: original.id, definitionRevision: 1,
+            trigger: { source: "migration", key: original.operation.requestId }
+        });
+        db.prepare("INSERT INTO storage_migration_archive(migration_version,family,record_key,payload) VALUES(?,?,?,?)")
+            .run(9, "durable_jobs", `${row.task_id}/${row.job_id}`, row.payload);
+        db.prepare("INSERT INTO job_definitions VALUES(?,?,?)")
+            .run(row.task_id, run.definitionId, JSON.stringify(definitionFromTaskRun(run)));
+        db.prepare("UPDATE durable_jobs SET payload=? WHERE task_id=? AND job_id=?")
+            .run(JSON.stringify(run), row.task_id, row.job_id);
+    }
+}

package/dist/task/publicationToolObservation.js

@@ -0,0 +1,128 @@
+import { usageError } from "../errors/cliError.js";
+const REQUIRED = [
+    "taskId", "publicationId", "projectId", "localCommit", "provider", "repository",
+    "externalKind", "externalId", "externalUrl", "targetBranch", "state",
+    "headCommit", "observedAt", "tool", "command", "output"
+];
+const OPTIONAL = ["remoteCommit", "mergedAt"];
+const SHA = /^[0-9a-f]{40}$/u;
+const MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+export function parsePublicationToolObservation(text) {
+    if (Buffer.byteLength(text, "utf8") > 64 * 1024) {
+        throw usageError("Tool observation must not exceed 64 KiB; supply a sanitized relevant output excerpt.");
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw usageError("--observation requires a JSON object.");
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw usageError("--observation requires a JSON object.");
+    }
+    const record = value;
+    const allowed = new Set([...REQUIRED, ...OPTIONAL]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            throw usageError(`Unknown tool observation field: ${key}.`);
+    }
+    for (const key of [...REQUIRED, ...OPTIONAL]) {
+        if (OPTIONAL.includes(key) && record[key] === undefined)
+            continue;
+        if (typeof record[key] !== "string" || record[key].trim().length === 0) {
+            throw usageError(`Tool observation requires nonempty ${key}.`);
+        }
+    }
+    for (const key of ["localCommit", "headCommit", "remoteCommit"]) {
+        if (record[key] !== undefined && !SHA.test(record[key])) {
+            throw usageError(`Tool observation ${key} requires an exact lowercase Git SHA.`);
+        }
+    }
+    if (!((record.provider === "github" && record.externalKind === "pull-request")
+        || (record.provider === "gitlab" && record.externalKind === "merge-request"))) {
+        throw usageError("Tool observation requires a matching GitHub PR or GitLab MR kind.");
+    }
+    if (!["open", "merged", "closed"].includes(record.state)
+        || (record.state === "merged" && record.remoteCommit === undefined)) {
+        throw usageError("Tool observation requires a known state and an integrated commit for a merge.");
+    }
+    for (const key of ["observedAt", "mergedAt"]) {
+        if (record[key] !== undefined
+            && (!/^\d{4}-\d\d-\d\dT/u.test(record[key])
+                || !Number.isFinite(Date.parse(record[key])))) {
+            throw usageError(`Tool observation ${key} requires an ISO timestamp.`);
+        }
+    }
+    // Canonical key ordering makes retries independent of JSON whitespace/order.
+    const evidence = JSON.stringify(Object.fromEntries(Object.keys(record).sort().map(key => [key, record[key]])));
+    return { ...record, evidence };
+}
+export function assertPublicationToolObservation(publication, observation, now, observationNotBefore) {
+    for (const field of ["taskId", "projectId", "provider", "repository",
+        "externalKind", "externalId", "localCommit", "targetBranch"]) {
+        if (observation[field] !== publication[field]) {
+            throw usageError(`Tool observation ${field} does not match the Publication candidate.`);
+        }
+    }
+    if (observation.publicationId !== publication.id) {
+        throw usageError("Tool observation publicationId does not match the selected Publication.");
+    }
+    if (publication.externalUrl === undefined
+        || canonicalPublicationUrl(observation.externalUrl, publication.provider)
+            !== canonicalPublicationUrl(publication.externalUrl, publication.provider)) {
+        throw usageError("Tool observation externalUrl must match the recorded Publication service and object.");
+    }
+    const url = new URL(canonicalPublicationUrl(observation.externalUrl, publication.provider));
+    const path = publication.provider === "gitlab"
+        ? `/${publication.repository}/-/merge_requests/${publication.externalId}`
+        : `/${publication.repository.toLowerCase()}/pull/${publication.externalId}`;
+    // The registered URL comparison above pins the host AND any service prefix.
+    // GitLab may be served below a relative root such as /gitlab.
+    if (publication.provider === "gitlab" ? !url.pathname.endsWith(path) : url.pathname !== path) {
+        throw usageError("Tool observation URL does not match the repository and PR/MR identity.");
+    }
+    const observed = Date.parse(observation.observedAt);
+    if ((observationNotBefore !== undefined && observed < observationNotBefore)
+        || observed > now.getTime() || now.getTime() - observed > MAX_AGE_MS) {
+        throw usageError("Tool observation is stale or future-dated; observe the current Publication within 24 hours of recording.");
+    }
+    if (observation.mergedAt !== undefined && Date.parse(observation.mergedAt) > observed) {
+        throw usageError("Tool observation merge time cannot follow its observation time.");
+    }
+}
+/** Derive the latest material change from immutable history, not title edits or
+ * initial bookkeeping. A tool read may legitimately precede its first upsert.
+ * Changed-then-restored candidates still have a change boundary. */
+export function publicationObservationNotBefore(publication, previous) {
+    const fields = [
+        "projectId", "provider", "repository", "externalKind", "externalId",
+        "externalUrl", "localCommit", "targetBranch", "state", "headCommit", "remoteCommit", "mergedAt"
+    ];
+    let current = publication;
+    while (current.supersedes !== undefined) {
+        const prior = previous(current.supersedes);
+        if (prior === null)
+            throw usageError("Publication history is incomplete; cannot validate observation freshness.");
+        if (fields.some(field => current[field] !== prior[field])) {
+            return Date.parse(current.createdAt);
+        }
+        current = prior;
+    }
+    return undefined;
+}
+export function canonicalPublicationUrl(value, provider) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw usageError("Publication URL must be an absolute HTTP(S) URL.");
+    }
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password
+        || url.search || url.hash) {
+        throw usageError("Publication URL must be HTTP(S), without credentials, query or fragment.");
+    }
+    const path = url.pathname.replace(/\/$/u, "");
+    return `${url.origin}${provider === "github" ? path.toLowerCase() : path}`;
+}