chainlesschain 0.163.7 → 0.163.8

package/src/lib/cowork-cron.js

@@ -31,12 +31,14 @@
 
 import crypto from "node:crypto";
 import {
-  existsSync,
+  closeSync,
+  fsyncSync,
   mkdirSync,
+  openSync,
   readFileSync,
   renameSync,
   unlinkSync,
-  writeFileSync,
+  writeSync,
 } from "node:fs";
 import { join } from "node:path";
 import {
@@ -47,12 +49,14 @@ import {
 import { withFileLock } from "./with-file-lock.js";
 
 export const _deps = {
-  existsSync,
+  closeSync,
+  fsyncSync,
   mkdirSync,
+  openSync,
   readFileSync,
   renameSync,
   unlinkSync,
-  writeFileSync,
+  writeSync,
   withFileLock,
   now: () => new Date(),
   runTask: null, // injected at runtime to avoid circular import
@@ -543,14 +547,33 @@ function _scheduleFile(cwd) {
 /** Load all schedules from disk. Returns [] if the file doesn't exist. */
 export function loadSchedules(cwd, { failOnMalformed = false } = {}) {
   const file = _scheduleFile(cwd);
-  if (!_deps.existsSync(file)) return [];
-  const raw = _deps.readFileSync(file, "utf-8");
+  let raw;
+  try {
+    raw = _deps.readFileSync(file, "utf-8");
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return [];
+    const error = new Error(`cowork schedule store read failed: ${file}`, {
+      cause,
+    });
+    error.code = "COWORK_SCHEDULE_STORE_READ_FAILED";
+    error.filePath = file;
+    if (typeof cause?.code === "string") error.fsCode = cause.code;
+    throw error;
+  }
   const out = [];
   for (const line of raw.split("\n")) {
     const trimmed = line.trim();
     if (!trimmed) continue;
     try {
-      out.push(JSON.parse(trimmed));
+      const schedule = JSON.parse(trimmed);
+      if (
+        !schedule ||
+        typeof schedule !== "object" ||
+        Array.isArray(schedule)
+      ) {
+        throw new TypeError("schedule entry must be an object");
+      }
+      out.push(schedule);
     } catch (cause) {
       if (failOnMalformed) {
         const error = new Error(
@@ -573,20 +596,68 @@ function _prepareScheduleDir(cwd) {
 }
 
 function _saveSchedulesUnlocked(cwd, schedules) {
-  _prepareScheduleDir(cwd);
+  const directory = _prepareScheduleDir(cwd);
   const file = _scheduleFile(cwd);
   const body = schedules.map((s) => JSON.stringify(s)).join("\n");
+  const contents = Buffer.from(body ? `${body}\n` : "", "utf8");
   const tmp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  let descriptor = null;
+  let renamed = false;
   try {
-    _deps.writeFileSync(tmp, body ? body + "\n" : "", "utf-8");
+    descriptor = _deps.openSync(tmp, "wx", 0o600);
+    let offset = 0;
+    while (offset < contents.length) {
+      const written = _deps.writeSync(
+        descriptor,
+        contents,
+        offset,
+        contents.length - offset,
+        null,
+      );
+      if (!Number.isSafeInteger(written) || written <= 0) {
+        const cause = new Error("write returned no progress");
+        cause.code = "EIO";
+        throw cause;
+      }
+      offset += written;
+    }
+    _deps.fsyncSync(descriptor);
+    _deps.closeSync(descriptor);
+    descriptor = null;
     _deps.renameSync(tmp, file);
+    renamed = true;
+
+    if (process.platform !== "win32") {
+      const directoryDescriptor = _deps.openSync(directory, "r");
+      try {
+        _deps.fsyncSync(directoryDescriptor);
+      } finally {
+        _deps.closeSync(directoryDescriptor);
+      }
+    }
   } catch (error) {
-    try {
-      _deps.unlinkSync(tmp);
-    } catch {
-      // Preserve the original persistence error.
+    if (descriptor !== null) {
+      try {
+        _deps.closeSync(descriptor);
+      } catch {
+        // Preserve the original persistence error.
+      }
     }
-    throw error;
+    if (!renamed) {
+      try {
+        _deps.unlinkSync(tmp);
+      } catch {
+        // Best-effort orphan cleanup; the authoritative file is unchanged.
+      }
+    }
+    const persistenceError =
+      error && (typeof error === "object" || typeof error === "function")
+        ? error
+        : new Error(`Cowork schedule persistence failed: ${String(error)}`, {
+            cause: error,
+          });
+    persistenceError.commitState = renamed ? "unknown" : "not-committed";
+    throw persistenceError;
   }
 }
 

package/src/lib/scheduler-kernel/agenda-adapter.js

@@ -15,6 +15,7 @@ import {
   normalizeJson,
 } from "./contract.js";
 import { SchedulerRuntime } from "./runtime.js";
+import { CHECKPOINT_V1_RUNTIME_CONTROL } from "./runtime-control-capabilities.js";
 import { schedulerMigrationSourceDigest } from "./store.js";
 import {
   bindSchedulerAuthorityPolicy,
@@ -677,6 +678,7 @@ export function createAgendaSchedulerAdapter({
   }
   return {
     kind: AGENDA_SCHEDULER_KIND,
+    runtimeControl: CHECKPOINT_V1_RUNTIME_CONTROL,
     async adjudicate({ occurrence, adjudication }) {
       const payload = occurrence.payload;
       const expected = agendaEntrySnapshot(payload?.entry);
@@ -711,7 +713,7 @@ export function createAgendaSchedulerAdapter({
       }
       return { continue: true };
     },
-    async execute({ occurrence }) {
+    async execute({ occurrence, checkpoint }) {
       const payload = occurrence.payload;
       const expected = agendaEntrySnapshot(payload?.entry);
       const expectedDigest = agendaEntrySnapshotDigest(expected);
@@ -757,6 +759,17 @@ export function createAgendaSchedulerAdapter({
           `Agenda entry changed after occurrence enqueue: ${expected.id}`,
         );
       }
+      if (expected.kind === "monitor" && typeof runMonitor !== "function") {
+        throw agendaError(
+          "AGENDA_SCHEDULER_MONITOR_RUNNER_REQUIRED",
+          "Agenda scheduler monitor execution requires a monitor runner",
+        );
+      }
+
+      checkpoint({
+        entryId: expected.id,
+        phase: "before_execution_bind",
+      });
 
       current = agendaStore.bindSchedulerExecution(expected.id, {
         occurrenceId: occurrence.id,
@@ -784,12 +797,6 @@ export function createAgendaSchedulerAdapter({
       let action = null;
       try {
         if (expected.kind === "monitor") {
-          if (typeof runMonitor !== "function") {
-            throw agendaError(
-              "AGENDA_SCHEDULER_MONITOR_RUNNER_REQUIRED",
-              "Agenda scheduler monitor execution requires a monitor runner",
-            );
-          }
           observation = normalizeMonitorObservation(
             expected,
             await runMonitor({
@@ -944,6 +951,9 @@ export function createAgendaSchedulerAdapter({
         );
       }
     },
+    async resume(context) {
+      return this.execute(context);
+    },
     classifyError(error) {
       return {
         retryable: error?.retryable === true,

package/src/lib/scheduler-kernel/automation-adapter.js

@@ -1,12 +1,18 @@
 import { createHash, randomUUID } from "node:crypto";
 import { nextCronTime } from "../agent-schedule-store.js";
 import {
+  assertAutomationRuntimeBoundary,
   automationExecutionAuthorityDigest,
   automationExecutionAuthoritySnapshot,
   automationSchedulerAuthority,
+  classifyAutomationBoundaryError,
   normalizeAutomationExecutionAuthoritySnapshot,
   reserveAutomationExecutionAuthority,
 } from "../automation-execution-authority.js";
+import {
+  resolveAutomationExecutionIncidentsForSucceededRun,
+  upsertAutomationExecutionIncident,
+} from "../automation-execution-incident.js";
 import {
   EXECUTION_STATUS,
   FLOW_STATUS,
@@ -33,6 +39,7 @@ import {
   normalizeJson,
 } from "./contract.js";
 import { SchedulerRuntime } from "./runtime.js";
+import { CHECKPOINT_V1_RUNTIME_CONTROL } from "./runtime-control-capabilities.js";
 import {
   schedulerJobDefinitionDigest,
   schedulerMigrationSourceDigest,
@@ -178,6 +185,54 @@ export function automationSchedulerExecutionId(occurrenceId) {
   return `exec-scheduler-${digest}`;
 }
 
+function automationBoundaryIncidentEvidence(error, snapshot) {
+  const classified = classifyAutomationBoundaryError(error);
+  if (!classified) return null;
+  const deniedPermissions = Array.isArray(error?.details?.permissions)
+    ? error.details.permissions.map(String).slice(0, 32)
+    : [];
+  return {
+    classified,
+    boundary: {
+      ...(deniedPermissions.length > 0 ? { deniedPermissions } : {}),
+      ...(snapshot?.budget?.revision === undefined
+        ? {}
+        : { budgetRevision: snapshot.budget.revision }),
+      ...(Array.isArray(snapshot?.connectors)
+        ? { connectors: snapshot.connectors }
+        : {}),
+    },
+    details: { reasonCode: classified.code, retryable: false },
+  };
+}
+
+function persistAutomationSchedulerIncident(
+  db,
+  occurrence,
+  flow,
+  snapshot,
+  error,
+  now,
+) {
+  const evidence = automationBoundaryIncidentEvidence(error, snapshot);
+  if (!evidence) return null;
+  return upsertAutomationExecutionIncident(
+    db,
+    {
+      runId: automationSchedulerExecutionId(occurrence.id),
+      flowId: flow.id,
+      occurrenceId: occurrence.id,
+      triggerType: TRIGGER_TYPE.SCHEDULE,
+      category: evidence.classified.category,
+      code: evidence.classified.code,
+      authorityDigest: automationExecutionAuthorityDigest(snapshot, flow),
+      boundary: evidence.boundary,
+      details: evidence.details,
+    },
+    { now },
+  );
+}
+
 export function buildAutomationSchedulerJob(flow, executionAuthority) {
   const snapshot = automationFlowSnapshot(flow);
   const normalizedExecutionAuthority =
@@ -702,7 +757,7 @@ export function authorizeAutomationOccurrence({ job, occurrence }) {
   }
 }
 
-function existingExecutionResult(db, occurrence, expected) {
+function existingExecutionResult(db, occurrence, expected, now) {
   const executionId = automationSchedulerExecutionId(occurrence.id);
   const execution = getExecution(db, executionId);
   if (!execution) return null;
@@ -729,6 +784,9 @@ function existingExecutionResult(db, occurrence, expected) {
       { executionId: execution.id, status: execution.status },
     );
   }
+  resolveAutomationExecutionIncidentsForSucceededRun(db, execution.id, {
+    now,
+  });
   return execution;
 }
 
@@ -741,6 +799,7 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
   }
   return {
     kind: AUTOMATION_SCHEDULER_KIND,
+    runtimeControl: CHECKPOINT_V1_RUNTIME_CONTROL,
     async adjudicate({ occurrence, adjudication }) {
       const payload = occurrence?.payload;
       const expected = automationFlowSnapshot(payload?.flow);
@@ -772,7 +831,7 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
       }
       return { continue: true };
     },
-    async execute({ occurrence }) {
+    async execute({ occurrence, checkpoint }) {
       const payload = occurrence?.payload;
       const expected = automationFlowSnapshot(payload?.flow);
       const expectedDigest = automationFlowSnapshotDigest(expected);
@@ -789,7 +848,7 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
       // A prior process may have committed the flow result and died before the
       // scheduler settlement. Durable success is authoritative even if the flow
       // was subsequently paused or edited.
-      const recovered = existingExecutionResult(db, occurrence, expected);
+      const recovered = existingExecutionResult(db, occurrence, expected, now);
       if (recovered) return recovered;
 
       const current = getFlow(db, expected.id);
@@ -813,14 +872,31 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
         );
       }
 
-      reserveAutomationExecutionAuthority(
-        db,
-        effectiveCurrent,
-        occurrence.id,
-        payload.executionAuthority,
-        payload.executionAuthorityDigest,
-        { now },
-      );
+      checkpoint({
+        executionId: automationSchedulerExecutionId(occurrence.id),
+        phase: "before_execution_reservation",
+      });
+
+      try {
+        reserveAutomationExecutionAuthority(
+          db,
+          effectiveCurrent,
+          occurrence.id,
+          payload.executionAuthority,
+          payload.executionAuthorityDigest,
+          { now },
+        );
+      } catch (error) {
+        persistAutomationSchedulerIncident(
+          db,
+          occurrence,
+          effectiveCurrent,
+          payload.executionAuthority,
+          error,
+          now,
+        );
+        throw error;
+      }
 
       let execution;
       try {
@@ -828,8 +904,20 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
           inputData: {},
           triggerType: TRIGGER_TYPE.SCHEDULE,
           executionId: automationSchedulerExecutionId(occurrence.id),
+          executionAuthority: payload.executionAuthority,
+          assertRuntimeBoundary: assertAutomationRuntimeBoundary,
         });
       } catch (cause) {
+        if (classifyAutomationBoundaryError(cause)) {
+          persistAutomationSchedulerIncident(
+            db,
+            occurrence,
+            effectiveCurrent,
+            payload.executionAuthority,
+            cause,
+            now,
+          );
+        }
         if (cause?.code === "AUTOMATION_EXECUTION_OUTCOME_UNKNOWN") {
           throw automationError(
             "AUTOMATION_SCHEDULER_OUTCOME_UNKNOWN",
@@ -847,8 +935,14 @@ export function createAutomationSchedulerAdapter({ db, now = Date.now } = {}) {
           { executionId: execution.id, error: execution.error },
         );
       }
+      resolveAutomationExecutionIncidentsForSucceededRun(db, execution.id, {
+        now,
+      });
       return execution;
     },
+    async resume(context) {
+      return this.execute(context);
+    },
     classifyError() {
       return { retryable: false };
     },

package/src/lib/scheduler-kernel/automation-event-adapter.js

@@ -1,12 +1,18 @@
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import {
+  assertAutomationRuntimeBoundary,
   automationExecutionAuthorityDigest,
   automationExecutionAuthoritySnapshot,
   automationSchedulerAuthority,
+  classifyAutomationBoundaryError,
   normalizeAutomationExecutionAuthoritySnapshot,
   reserveAutomationExecutionAuthority,
 } from "../automation-execution-authority.js";
+import {
+  resolveAutomationExecutionIncidentsForSucceededRun,
+  upsertAutomationExecutionIncident,
+} from "../automation-execution-incident.js";
 import {
   EXECUTION_STATUS,
   FLOW_STATUS,
@@ -26,6 +32,7 @@ import {
   normalizeJson,
 } from "./contract.js";
 import { SchedulerRuntime } from "./runtime.js";
+import { CHECKPOINT_V1_RUNTIME_CONTROL } from "./runtime-control-capabilities.js";
 
 export const AUTOMATION_EVENT_KIND = "automation-event";
 export const AUTOMATION_EVENT_CAPABILITY = "automation.execute";
@@ -294,6 +301,39 @@ export function automationEventExecutionId(occurrenceId) {
     .digest("hex")}`;
 }
 
+function persistAutomationEventIncident(db, occurrence, flow, error, now) {
+  const classified = classifyAutomationBoundaryError(error);
+  if (!classified) return null;
+  const snapshot = occurrence.payload.executionAuthority;
+  const deniedPermissions = Array.isArray(error?.details?.permissions)
+    ? error.details.permissions.map(String).slice(0, 32)
+    : [];
+  return upsertAutomationExecutionIncident(
+    db,
+    {
+      runId: automationEventExecutionId(occurrence.id),
+      flowId: flow.id,
+      occurrenceId: occurrence.id,
+      triggerType: TRIGGER_TYPE.EVENT,
+      triggerId: occurrence.payload?.trigger?.id || null,
+      category: classified.category,
+      code: classified.code,
+      authorityDigest: automationExecutionAuthorityDigest(snapshot, flow),
+      boundary: {
+        ...(deniedPermissions.length > 0 ? { deniedPermissions } : {}),
+        ...(snapshot?.budget?.revision === undefined
+          ? {}
+          : { budgetRevision: snapshot.budget.revision }),
+        ...(Array.isArray(snapshot?.connectors)
+          ? { connectors: snapshot.connectors }
+          : {}),
+      },
+      details: { reasonCode: classified.code, retryable: false },
+    },
+    { now },
+  );
+}
+
 export function automationEventTriggerKey(event) {
   const normalized = normalizeAutomationChannelEvent(event);
   return `channel:${createHash("sha256")
@@ -514,7 +554,7 @@ export function authorizeAutomationEventOccurrence({ job, occurrence }) {
   }
 }
 
-function existingExecutionResult(db, occurrence, expectedFlow) {
+function existingExecutionResult(db, occurrence, expectedFlow, now) {
   const executionId = automationEventExecutionId(occurrence.id);
   const execution = getExecution(db, executionId);
   if (!execution) return null;
@@ -541,6 +581,9 @@ function existingExecutionResult(db, occurrence, expectedFlow) {
       { executionId: execution.id, status: execution.status },
     );
   }
+  resolveAutomationExecutionIncidentsForSucceededRun(db, execution.id, {
+    now,
+  });
   return execution;
 }
 
@@ -553,6 +596,7 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
   }
   return {
     kind: AUTOMATION_EVENT_KIND,
+    runtimeControl: CHECKPOINT_V1_RUNTIME_CONTROL,
     async adjudicate({ occurrence, adjudication }) {
       const payload = occurrence?.payload;
       const expectedFlow = automationEventFlowSnapshot(payload?.flow);
@@ -588,7 +632,7 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
       }
       return { continue: true };
     },
-    async execute({ occurrence }) {
+    async execute({ occurrence, checkpoint }) {
       const payload = occurrence?.payload;
       const expectedFlow = automationEventFlowSnapshot(payload?.flow);
       const expectedTrigger = automationEventTriggerSnapshot(payload?.trigger);
@@ -605,7 +649,12 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
         );
       }
 
-      const recovered = existingExecutionResult(db, occurrence, expectedFlow);
+      const recovered = existingExecutionResult(
+        db,
+        occurrence,
+        expectedFlow,
+        now,
+      );
       if (recovered) return recovered;
 
       const currentFlow = getFlow(db, expectedFlow.id);
@@ -630,14 +679,24 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
         );
       }
 
-      reserveAutomationExecutionAuthority(
-        db,
-        currentFlow,
-        occurrence.id,
-        payload.executionAuthority,
-        payload.executionAuthorityDigest,
-        { now },
-      );
+      checkpoint({
+        executionId: automationEventExecutionId(occurrence.id),
+        phase: "before_execution_reservation",
+      });
+
+      try {
+        reserveAutomationExecutionAuthority(
+          db,
+          currentFlow,
+          occurrence.id,
+          payload.executionAuthority,
+          payload.executionAuthorityDigest,
+          { now },
+        );
+      } catch (error) {
+        persistAutomationEventIncident(db, occurrence, currentFlow, error, now);
+        throw error;
+      }
 
       let execution;
       try {
@@ -645,8 +704,19 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
           inputData: { event: expectedEvent },
           triggerType: TRIGGER_TYPE.EVENT,
           executionId: automationEventExecutionId(occurrence.id),
+          executionAuthority: payload.executionAuthority,
+          assertRuntimeBoundary: assertAutomationRuntimeBoundary,
         });
       } catch (cause) {
+        if (classifyAutomationBoundaryError(cause)) {
+          persistAutomationEventIncident(
+            db,
+            occurrence,
+            currentFlow,
+            cause,
+            now,
+          );
+        }
         if (cause?.code === "AUTOMATION_EXECUTION_OUTCOME_UNKNOWN") {
           throw eventError(
             "AUTOMATION_EVENT_OUTCOME_UNKNOWN",
@@ -664,8 +734,14 @@ export function createAutomationEventAdapter({ db, now = Date.now } = {}) {
           { executionId: execution.id, error: execution.error },
         );
       }
+      resolveAutomationExecutionIncidentsForSucceededRun(db, execution.id, {
+        now,
+      });
       return execution;
     },
+    async resume(context) {
+      return this.execute(context);
+    },
     classifyError() {
       return { retryable: false };
     },

package/src/lib/scheduler-kernel/contract.js

@@ -3,6 +3,26 @@ import { Buffer } from "node:buffer";
 
 export const SCHEDULER_SCHEMA_VERSION = 1;
 export const AUTHORITY_ENVELOPE_VERSION = 1;
+export const RUNTIME_CONTROL_SCHEMA_VERSION = 1;
+
+export const RUNTIME_PAUSE_RESUME = Object.freeze({
+  NONE: "none",
+  CHECKPOINT_V1: "checkpoint_v1",
+});
+
+export const RUNTIME_CONTROL_SAFE_POINTS = Object.freeze({
+  BEFORE_EXECUTE: "before_execute",
+  ADAPTER_CHECKPOINT: "adapter_checkpoint",
+});
+
+const RUNTIME_CONTROL_FIELDS = new Set([
+  "schemaVersion",
+  "pauseResume",
+  "safePoints",
+]);
+const RUNTIME_CONTROL_SAFE_POINT_SET = new Set(
+  Object.values(RUNTIME_CONTROL_SAFE_POINTS),
+);
 
 export const OCCURRENCE_STATUS = Object.freeze({
   QUEUED: "queued",
@@ -286,6 +306,77 @@ export function normalizeHistoryLimit(value = DEFAULT_HISTORY_LIMIT) {
   return Math.min(value, MAX_HISTORY_LIMIT);
 }
 
+/**
+ * Normalize the durable runtime-control capability advertised by an adapter.
+ *
+ * Missing declarations are deliberately treated as unsupported. A checkpoint
+ * declaration is evidence, not a hint: only the two kernel-owned safe points
+ * are accepted and every persisted pause request is bound to these canonical
+ * bytes.
+ */
+export function normalizeRuntimeControlCapability(input) {
+  if (input === undefined || input === null) {
+    return Object.freeze({
+      schemaVersion: RUNTIME_CONTROL_SCHEMA_VERSION,
+      pauseResume: RUNTIME_PAUSE_RESUME.NONE,
+      safePoints: Object.freeze([]),
+    });
+  }
+  const capability = assertPlainObject(input, "runtimeControl");
+  assertKnownFields(capability, RUNTIME_CONTROL_FIELDS, "runtimeControl");
+  if (
+    capability.schemaVersion !== undefined &&
+    capability.schemaVersion !== RUNTIME_CONTROL_SCHEMA_VERSION
+  ) {
+    throw invalidArgument(
+      `runtimeControl.schemaVersion must be ${RUNTIME_CONTROL_SCHEMA_VERSION}`,
+    );
+  }
+  const pauseResume = capability.pauseResume ?? RUNTIME_PAUSE_RESUME.NONE;
+  if (!Object.values(RUNTIME_PAUSE_RESUME).includes(pauseResume)) {
+    throw invalidArgument(
+      "runtimeControl.pauseResume must be none or checkpoint_v1",
+    );
+  }
+  const inputSafePoints = capability.safePoints ?? [];
+  if (!Array.isArray(inputSafePoints)) {
+    throw invalidArgument("runtimeControl.safePoints must be an array");
+  }
+  const safePoints = [
+    ...new Set(
+      inputSafePoints.map((safePoint, index) =>
+        normalizeIdentifier(safePoint, `runtimeControl.safePoints[${index}]`, {
+          maxLength: 64,
+        }),
+      ),
+    ),
+  ].sort();
+  const unknownSafePoints = safePoints.filter(
+    (safePoint) => !RUNTIME_CONTROL_SAFE_POINT_SET.has(safePoint),
+  );
+  if (unknownSafePoints.length > 0) {
+    throw invalidArgument("runtimeControl.safePoints contains unknown values", {
+      safePoints: unknownSafePoints,
+    });
+  }
+  if (
+    (pauseResume === RUNTIME_PAUSE_RESUME.NONE && safePoints.length !== 0) ||
+    (pauseResume === RUNTIME_PAUSE_RESUME.CHECKPOINT_V1 &&
+      safePoints.length === 0)
+  ) {
+    throw invalidArgument(
+      pauseResume === RUNTIME_PAUSE_RESUME.NONE
+        ? "runtimeControl.safePoints must be empty when pauseResume is none"
+        : "runtimeControl.safePoints must declare at least one checkpoint",
+    );
+  }
+  return Object.freeze({
+    schemaVersion: RUNTIME_CONTROL_SCHEMA_VERSION,
+    pauseResume,
+    safePoints: Object.freeze(safePoints),
+  });
+}
+
 /**
  * Stable identity for one logical firing. All adapters must supply the same
  * triggerKey for the same logical schedule. Including jobRevision prevents an