chainlesschain 0.163.3 → 0.163.4

package/src/lib/observability/index.js

@@ -186,6 +186,7 @@ export class ObservabilityRuntime {
           unit: "{invocation}",
           value: 1,
           monotonic: true,
+          aggregationTemporality: 1,
           attributes,
         },
         {
@@ -194,6 +195,7 @@ export class ObservabilityRuntime {
           unit: "ms",
           count: 1,
           sum: durationMs,
+          aggregationTemporality: 1,
           attributes,
         },
       ]);

package/src/lib/observability/otlp-exporter.js

@@ -924,7 +924,7 @@ export class OtlpExporter {
         description: metric.description || "",
         unit: metric.unit || "1",
         histogram: {
-          aggregationTemporality: 2,
+          aggregationTemporality: metric.aggregationTemporality === 1 ? 1 : 2,
           dataPoints: [
             {
               ...point,
@@ -945,7 +945,7 @@ export class OtlpExporter {
           : { asDouble: Number(metric.value) || 0 };
     const data = { dataPoints: [{ ...point, ...number }] };
     if (metric.type === "sum" || metric.type === "counter") {
-      data.aggregationTemporality = 2;
+      data.aggregationTemporality = metric.aggregationTemporality === 1 ? 1 : 2;
       data.isMonotonic = metric.monotonic !== false;
       return {
         name: metric.name,

package/src/lib/packer/pack-update-applier.js

@@ -46,6 +46,13 @@ export const _deps = {
   tmpdir: () => os.tmpdir(),
 };
 
+// A real Windows sidecar performs path, lock-token and digest checks before it
+// publishes the readiness marker. Loaded hosted runners have exceeded the old
+// 10 second allowance while still completing successfully. Keep the parent in
+// charge of the lock until the marker is verified, but give the safety
+// preflight a bounded budget that also covers heavily contended machines.
+export const WINDOWS_SIDECAR_READY_TIMEOUT_MS = 30_000;
+
 export async function scheduleReplace(ctx = {}) {
   const {
     newExePath,
@@ -778,7 +785,7 @@ function scheduleWindowsTransaction(ctx) {
           waitForReadyImpl({
             readyPath,
             transactionId,
-            timeoutMs: 10_000,
+            timeoutMs: WINDOWS_SIDECAR_READY_TIMEOUT_MS,
             child,
           }),
         ) && !childError;

package/src/lib/packer/pkg-config-generator.js

@@ -18,8 +18,41 @@
  */
 
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
+function capsuleBuilderAssets(cliRoot) {
+  const requireFromCli = createRequire(path.join(cliRoot, "package.json"));
+  const realpath = fs.realpathSync.native || fs.realpathSync;
+  let packageJsonPath;
+  try {
+    packageJsonPath = realpath(
+      requireFromCli.resolve("esbuild-wasm/package.json"),
+    );
+  } catch (cause) {
+    throw new Error(
+      `Cannot resolve the pinned esbuild-wasm package for pkg assets: ${cause.message}`,
+    );
+  }
+  const packageRoot = path.dirname(packageJsonPath);
+  const sourceAssets = [
+    packageJsonPath,
+    path.join(packageRoot, "lib", "browser.js"),
+    path.join(packageRoot, "esbuild.wasm"),
+    path.join(cliRoot, "src", "lib", "mcp-stdio-capsule-builder-worker.cjs"),
+    path.join(cliRoot, "src", "lib", "mcp-stdio-immutable-vfs-resolver.cjs"),
+  ];
+  for (const asset of sourceAssets) {
+    const stat = fs.lstatSync(asset);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error(
+        `Pinned capsule builder pkg asset is not a regular file: ${asset}`,
+      );
+    }
+  }
+  return sourceAssets.map((asset) => realpath(asset));
+}
+
 /**
  * @param {object} ctx
  * @param {string} ctx.cliRoot                packages/cli/
@@ -396,6 +429,7 @@ export function generatePkgConfig(ctx) {
     `${posixify(cliRoot)}/src/lib/process-execution-broker/windows-sandbox-helper.exe`,
     `${posixify(cliRoot)}/src/lib/process-execution-broker/windows-sandbox.cs`,
     `${posixify(cliRoot)}/install/install.ps1`,
+    ...capsuleBuilderAssets(cliRoot).map(posixify),
   ];
   if (prebuildsDir) assets.push(`${posixify(prebuildsDir)}/**/*`);
   // Project mode: bundle the collected .chainlesschain/ snapshot as an asset.

package/src/lib/process-execution-broker/index.js

@@ -73,7 +73,7 @@ const _ipcBus = null;
 function getTraceCtx() {
   if (!_traceCtx) {
     try {
-      _traceCtx = require("../execution-trace/trace-context.js");
+      _traceCtx = require("../execution-trace/trace-context.cjs");
     } catch {
       _traceCtx = null;
     }
@@ -1218,6 +1218,7 @@ class ProcessExecutionBroker extends EventEmitter {
         "entrySnapshotAtomic",
         "runtimeLaunchAtomic",
         "mcpCapsuleCodeSnapshot",
+        "runtimeDetachedChildSpawnVerified",
       ]) {
         if (
           plan.runtimeProbe[field] !== undefined &&
@@ -1237,6 +1238,7 @@ class ProcessExecutionBroker extends EventEmitter {
         "runtimeSnapshotBytes",
         "runtimeAttestedBytes",
         "entrySnapshotBytes",
+        "capabilityCount",
       ]) {
         if (
           plan.runtimeProbe[field] !== undefined &&
@@ -1758,6 +1760,7 @@ class ProcessExecutionBroker extends EventEmitter {
           plan.runtimeProbe.runtimeLaunchAtomic === true &&
           plan.runtimeProbe.runtimeLaunchMechanism ===
             "bwrap-descriptor-mount-node-runtime-exec-v1" &&
+          plan.runtimeProbe.runtimeDetachedChildSpawnVerified === true &&
           plan.runtimeProbe.supervisorDescriptorBound === true &&
           plan.runtimeProbe.pluginTreeContentSnapshot === true &&
           plan.runtimeProbe.runtimeLaunchPath ===
@@ -1794,6 +1797,7 @@ class ProcessExecutionBroker extends EventEmitter {
             (backend === "windows-appcontainer-job-restricted-token" &&
               plan.runtimeProbe.kind ===
                 "windows-appcontainer-launch-attestation-v1" &&
+              plan.runtimeProbe.capabilityCount === 0 &&
               policyAttested === true &&
               policyDigest !== null)) &&
           plan.runtimeProbe.contentSnapshotScope ===
@@ -1829,6 +1833,17 @@ class ProcessExecutionBroker extends EventEmitter {
           );
         }
       }
+      if (
+        plan.runtimeProbe.kind ===
+          "windows-appcontainer-launch-attestation-v1" &&
+        plan.runtimeProbe.runnable === true &&
+        plan.runtimeProbe.capabilityCount !== 0
+      ) {
+        throw this._sandboxError(
+          "invalid_sandbox_plan",
+          "Windows AppContainer runtime evidence must attest zero capabilities",
+        );
+      }
       const genericWorkspaceEvidenceFields = [
         "contractDigest",
         "policyDigest",
@@ -2103,6 +2118,9 @@ class ProcessExecutionBroker extends EventEmitter {
         ...(plan.runtimeProbe.targetRuntime !== undefined
           ? { targetRuntime: plan.runtimeProbe.targetRuntime }
           : {}),
+        ...(plan.runtimeProbe.capabilityCount !== undefined
+          ? { capabilityCount: plan.runtimeProbe.capabilityCount }
+          : {}),
         ...(plan.runtimeProbe.contentSnapshot !== undefined
           ? { contentSnapshot: plan.runtimeProbe.contentSnapshot }
           : {}),
@@ -2115,6 +2133,12 @@ class ProcessExecutionBroker extends EventEmitter {
         ...(plan.runtimeProbe.runtimeLaunchAtomic !== undefined
           ? { runtimeLaunchAtomic: plan.runtimeProbe.runtimeLaunchAtomic }
           : {}),
+        ...(plan.runtimeProbe.runtimeDetachedChildSpawnVerified !== undefined
+          ? {
+              runtimeDetachedChildSpawnVerified:
+                plan.runtimeProbe.runtimeDetachedChildSpawnVerified,
+            }
+          : {}),
         ...(plan.runtimeProbe.runtimeLaunchMechanism !== undefined
           ? {
               runtimeLaunchMechanism: plan.runtimeProbe.runtimeLaunchMechanism,
@@ -2922,10 +2946,15 @@ class ProcessExecutionBroker extends EventEmitter {
 
   _getTraceContext() {
     const traceCtx = getTraceCtx();
-    if (traceCtx && traceCtx.activeContext) {
-      return traceCtx.activeContext.value || null;
-    }
-    return null;
+    const activeContext = traceCtx?.traceContext?.getCurrentContext?.() || null;
+    if (!activeContext) return null;
+    return {
+      ...activeContext,
+      traceparent: traceCtx.traceContext.formatTraceparent(
+        activeContext.traceId,
+        activeContext.spanId,
+      ),
+    };
   }
 
   _writeRplEntry(auditEntry, status = "started", error = null) {

package/src/lib/process-execution-broker/platform-sandbox.js

@@ -159,6 +159,9 @@ const LINUX_BWRAP_PATH = "/usr/bin/bwrap";
 const LINUX_LDD_PATH = "/usr/bin/ldd";
 const LINUX_BWRAP_BACKEND = "linux-bwrap";
 const LINUX_BWRAP_NODE_PROBE_SENTINEL = "chainless-linux-bwrap-plugin-node-v1";
+const LINUX_BWRAP_CHILD_RUNTIME_PROBE_SENTINEL =
+  "chainless-linux-bwrap-child-runtime-v1";
+const LINUX_BWRAP_CHILD_RUNTIME_PROBE_FAILURE_STATUS = 86;
 const LINUX_BWRAP_MAX_PLUGIN_ENTRIES = 512;
 const LINUX_PLUGIN_TREE_SNAPSHOT_MAX_FILES = 256;
 const LINUX_PLUGIN_TREE_SNAPSHOT_MAX_BYTES = 256 * 1024 * 1024;
@@ -2544,6 +2547,7 @@ function waitForWindowsTargetIdentity(
         proc.sandboxAppContainerProfile =
           expectedAppContainer.appContainerProfileName;
         proc.sandboxAppContainerSid = expectedAppContainer.appContainerSid;
+        proc.sandboxAppContainerCapabilityCount = identity.capabilityCount;
       }
       // ChildProcess.pid is a writable data property. The native ChildProcess
       // handle still points at the helper, so kill()/ref()/unref() retain Job
@@ -2747,6 +2751,7 @@ function appContainerReadinessResult(
       ...runtimeProbe,
       runnable: true,
       reason: null,
+      capabilityCount: readiness.capabilityCount,
       ...(targetRuntime
         ? {
             probeRuntime: targetRuntime,
@@ -3877,6 +3882,7 @@ function linuxBubblewrapProbe(
   supervisorBinding = null,
   pluginTreeSnapshot = null,
   nativeDynamicClosure = null,
+  runtimeDetachedChildSpawnVerified = false,
 ) {
   const native =
     typeof targetRuntime === "string" && targetRuntime.startsWith("native-");
@@ -3942,6 +3948,7 @@ function linuxBubblewrapProbe(
     reason,
     probeRuntime: "node",
     targetRuntime,
+    runtimeDetachedChildSpawnVerified,
     contentSnapshot: snapshot,
     ...(snapshot
       ? {
@@ -6791,8 +6798,22 @@ function probeLinuxBubblewrapPolicy(
     ino: supervisorBinding.fileId.ino,
     bytes: supervisorBinding.bytes,
   });
+  const childProbeSource = [
+    'const fs = require("node:fs");',
+    "const sentinel = process.argv[1];",
+    'const raw = fs.readFileSync("/proc/self/stat", "utf8");',
+    'const close = raw.lastIndexOf(")");',
+    'const pid = Number(raw.slice(0, raw.indexOf(" ")));',
+    "const fields = raw.slice(close + 2).trim().split(/\\s+/);",
+    "const processGroupPid = Number(fields[2]);",
+    "const sessionPid = Number(fields[3]);",
+    "fs.writeSync(1, JSON.stringify({ sentinel, pid, processGroupPid, sessionPid }));",
+    "if (processGroupPid !== pid || sessionPid !== pid) process.exit(2);",
+  ].join("\n");
   const probeSource = [
     'const fs = require("node:fs");',
+    'const crypto = require("node:crypto");',
+    'const { spawnSync } = require("node:child_process");',
     `const expected = ${supervisorIdentity};`,
     'for (const name of fs.readdirSync("/proc/self/fd")) {',
     "  let current;",
@@ -6809,10 +6830,62 @@ function probeLinuxBubblewrapPolicy(
     "} catch (error) {",
     '  if (error?.code !== "ENOENT") throw error;',
     "}",
+    "// /tmp is a fresh private bwrap tmpfs; read the same O_EXCL inode by fd.",
+    'const childReportPath = "/tmp/.chainless-runtime-child-probe.json";',
+    `const expectedChildSentinel = ${JSON.stringify(
+      `${LINUX_BWRAP_CHILD_RUNTIME_PROBE_SENTINEL}:`,
+    )} + crypto.randomBytes(16).toString("hex");`,
+    "let reportFd;",
+    "let runtimeDetachedChildSpawnVerified = false;",
+    "try {",
+    '  reportFd = fs.openSync(childReportPath, "wx+", 0o600);',
+    `  const child = spawnSync("/opt/chainless/runtime/node", ["-e", ${JSON.stringify(
+      childProbeSource,
+    )}, expectedChildSentinel], {`,
+    '    cwd: "/",',
+    "    detached: true,",
+    "    env: process.env,",
+    "    shell: false,",
+    '    stdio: ["ignore", reportFd, "ignore"],',
+    "    timeout: 5_000,",
+    "  });",
+    "  const reportStat = fs.fstatSync(reportFd);",
+    "  const reportBytes = Number(reportStat.size);",
+    "  if (!child.error && child.status === 0 && child.signal === null &&",
+    "      Number.isSafeInteger(child.pid) && child.pid > 0 &&",
+    "      reportStat.isFile() && Number.isSafeInteger(reportBytes) &&",
+    "      reportBytes > 0 && reportBytes <= 1_024) {",
+    "    const reportBuffer = Buffer.alloc(reportBytes);",
+    "    const reportRead = fs.readSync(reportFd, reportBuffer, 0, reportBytes, 0);",
+    "    if (reportRead === reportBytes) {",
+    '      const reportText = reportBuffer.toString("utf8");',
+    "      const report = JSON.parse(reportText);",
+    "      const canonicalReport = JSON.stringify({ sentinel: report.sentinel,",
+    "        pid: report.pid, processGroupPid: report.processGroupPid,",
+    "        sessionPid: report.sessionPid });",
+    "      runtimeDetachedChildSpawnVerified = reportText === canonicalReport &&",
+    "        report.sentinel === expectedChildSentinel &&",
+    "        Number.isSafeInteger(report.pid) && report.pid > 0 &&",
+    "        report.pid === child.pid && report.processGroupPid === report.pid &&",
+    "        report.sessionPid === report.pid;",
+    "    }",
+    "  }",
+    "} catch {} finally {",
+    "  try { if (Number.isInteger(reportFd)) fs.closeSync(reportFd); } catch {",
+    "    runtimeDetachedChildSpawnVerified = false;",
+    "  }",
+    "  try { fs.unlinkSync(childReportPath); } catch {",
+    "    runtimeDetachedChildSpawnVerified = false;",
+    "  }",
+    "}",
+    `if (!runtimeDetachedChildSpawnVerified) process.exit(${LINUX_BWRAP_CHILD_RUNTIME_PROBE_FAILURE_STATUS});`,
     `process.stdout.write(${JSON.stringify(LINUX_BWRAP_NODE_PROBE_SENTINEL)});`,
   ].join("\n");
   let result;
   try {
+    // These pipes connect the host Broker to bwrap and are created before
+    // bwrap installs the target seccomp filter. The nested runtime probe above
+    // inherits a regular-file descriptor and never requests UV_CREATE_PIPE.
     result = runtime.spawnSync(
       supervisorLaunch.command,
       [...policyArgs, "--", "/opt/chainless/runtime/node", "-e", probeSource],
@@ -6846,7 +6919,11 @@ function probeLinuxBubblewrapPolicy(
     return linuxBubblewrapProbe(
       true,
       false,
-      result?.error ? "probe_spawn_failed" : "probe_failed",
+      result?.error
+        ? "probe_spawn_failed"
+        : result?.status === LINUX_BWRAP_CHILD_RUNTIME_PROBE_FAILURE_STATUS
+          ? "detached_child_runtime_probe_failed"
+          : "probe_failed",
       targetRuntime,
       contentSnapshot,
       supervisorBinding,
@@ -6869,6 +6946,9 @@ function probeLinuxBubblewrapPolicy(
     targetRuntime,
     contentSnapshot,
     supervisorBinding,
+    null,
+    null,
+    true,
   );
 }
 
@@ -7588,6 +7668,7 @@ export function applyLinuxSandbox(
       supervisorBinding,
       pluginTreeSnapshot,
       nativeDynamicClosure,
+      policyProbe.runtimeDetachedChildSpawnVerified === true,
     );
     const runtimeProbe = Object.freeze(
       capsuleContract

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

@@ -0,0 +1,315 @@
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+
+export const SCHEDULER_SCHEMA_VERSION = 1;
+export const AUTHORITY_ENVELOPE_VERSION = 1;
+
+export const OCCURRENCE_STATUS = Object.freeze({
+  QUEUED: "queued",
+  RUNNING: "running",
+  RETRY_WAIT: "retry_wait",
+  SUCCEEDED: "succeeded",
+  DEAD_LETTER: "dead_letter",
+});
+
+export const DEFAULT_MAX_ATTEMPTS = 3;
+export const MAX_JOB_ATTEMPTS = 32;
+export const DEFAULT_HISTORY_LIMIT = 50;
+export const MAX_HISTORY_LIMIT = 200;
+export const MAX_JSON_BYTES = 1024 * 1024;
+
+const AUTHORITY_FIELDS = new Set([
+  "schemaVersion",
+  "principal",
+  "tenantId",
+  "workspaceId",
+  "requestedCapabilities",
+  "authorizationRefs",
+]);
+const PRINCIPAL_FIELDS = new Set(["type", "id"]);
+const AUTHORIZATION_REF_FIELDS = new Set([
+  "decisionId",
+  "policyRevision",
+  "grantIds",
+  "approvalIds",
+  "delegationIds",
+]);
+
+export class SchedulerKernelError extends Error {
+  constructor(code, message, details = undefined, options = undefined) {
+    super(message, options);
+    this.name = "SchedulerKernelError";
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function invalidArgument(message, details = undefined) {
+  return new SchedulerKernelError(
+    "SCHEDULER_INVALID_ARGUMENT",
+    message,
+    details,
+  );
+}
+
+function assertPlainObject(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidArgument(`${field} must be an object`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw invalidArgument(`${field} must be a plain object`);
+  }
+  return value;
+}
+
+function assertKnownFields(value, fields, field) {
+  const unknown = Object.keys(value).filter((key) => !fields.has(key));
+  if (unknown.length > 0) {
+    throw invalidArgument(`${field} contains unknown fields`, {
+      fields: unknown.sort(),
+    });
+  }
+}
+
+export function normalizeIdentifier(value, field, { maxLength = 256 } = {}) {
+  if (typeof value !== "string") {
+    throw invalidArgument(`${field} must be a string`);
+  }
+  const normalized = value.trim();
+  const hasControlCharacter = [...normalized].some((character) => {
+    const codePoint = character.codePointAt(0);
+    return codePoint <= 31 || codePoint === 127;
+  });
+  if (
+    normalized.length === 0 ||
+    normalized.length > maxLength ||
+    hasControlCharacter
+  ) {
+    throw invalidArgument(`${field} is not a valid identifier`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalIdentifier(value, field) {
+  if (value === undefined || value === null) return null;
+  return normalizeIdentifier(value, field);
+}
+
+function normalizeIdentifierList(value, field) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw invalidArgument(`${field} must be an array`);
+  }
+  if (value.length > 256) {
+    throw invalidArgument(`${field} exceeds 256 entries`);
+  }
+  return [
+    ...new Set(
+      value.map((entry, index) =>
+        normalizeIdentifier(entry, `${field}[${index}]`),
+      ),
+    ),
+  ].sort();
+}
+
+/**
+ * Normalize the authority evidence carried by a job and every occurrence.
+ *
+ * This envelope is deliberately descriptive. The scheduler stores the actor,
+ * requested capabilities and immutable decision/grant references, but it does
+ * not infer that those references authorize execution. A future dispatcher
+ * must still resolve and enforce the referenced policy before doing work.
+ */
+export function normalizeAuthorityEnvelope(input) {
+  const authority = assertPlainObject(input, "authority");
+  assertKnownFields(authority, AUTHORITY_FIELDS, "authority");
+  if (
+    authority.schemaVersion !== undefined &&
+    authority.schemaVersion !== AUTHORITY_ENVELOPE_VERSION
+  ) {
+    throw invalidArgument(
+      `authority.schemaVersion must be ${AUTHORITY_ENVELOPE_VERSION}`,
+    );
+  }
+
+  const principal = assertPlainObject(
+    authority.principal,
+    "authority.principal",
+  );
+  assertKnownFields(principal, PRINCIPAL_FIELDS, "authority.principal");
+  const refs = assertPlainObject(
+    authority.authorizationRefs ?? {},
+    "authority.authorizationRefs",
+  );
+  assertKnownFields(
+    refs,
+    AUTHORIZATION_REF_FIELDS,
+    "authority.authorizationRefs",
+  );
+
+  return {
+    schemaVersion: AUTHORITY_ENVELOPE_VERSION,
+    principal: {
+      type: normalizeIdentifier(principal.type, "authority.principal.type", {
+        maxLength: 64,
+      }),
+      id: normalizeIdentifier(principal.id, "authority.principal.id"),
+    },
+    tenantId: normalizeOptionalIdentifier(
+      authority.tenantId,
+      "authority.tenantId",
+    ),
+    workspaceId: normalizeOptionalIdentifier(
+      authority.workspaceId,
+      "authority.workspaceId",
+    ),
+    requestedCapabilities: normalizeIdentifierList(
+      authority.requestedCapabilities,
+      "authority.requestedCapabilities",
+    ),
+    authorizationRefs: {
+      decisionId: normalizeOptionalIdentifier(
+        refs.decisionId,
+        "authority.authorizationRefs.decisionId",
+      ),
+      policyRevision: normalizeOptionalIdentifier(
+        refs.policyRevision,
+        "authority.authorizationRefs.policyRevision",
+      ),
+      grantIds: normalizeIdentifierList(
+        refs.grantIds,
+        "authority.authorizationRefs.grantIds",
+      ),
+      approvalIds: normalizeIdentifierList(
+        refs.approvalIds,
+        "authority.authorizationRefs.approvalIds",
+      ),
+      delegationIds: normalizeIdentifierList(
+        refs.delegationIds,
+        "authority.authorizationRefs.delegationIds",
+      ),
+    },
+  };
+}
+
+function normalizeJsonValue(value, field, state, depth) {
+  if (depth > 64) throw invalidArgument(`${field} exceeds maximum JSON depth`);
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw invalidArgument(`${field} contains a non-finite number`);
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (typeof value !== "object") {
+    throw invalidArgument(`${field} contains a non-JSON value`);
+  }
+  if (state.seen.has(value)) {
+    throw invalidArgument(`${field} contains a cycle`);
+  }
+  state.seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((entry, index) =>
+        normalizeJsonValue(entry, `${field}[${index}]`, state, depth + 1),
+      );
+    }
+    assertPlainObject(value, field);
+    // A JSON object may legitimately contain an own `__proto__` key. A normal
+    // object assignment would interpret that key as a prototype mutation and
+    // silently drop it from the canonical bytes.
+    const normalized = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+      normalized[key] = normalizeJsonValue(
+        value[key],
+        `${field}.${key}`,
+        state,
+        depth + 1,
+      );
+    }
+    return normalized;
+  } finally {
+    state.seen.delete(value);
+  }
+}
+
+export function normalizeJson(value, field = "value") {
+  const normalized = normalizeJsonValue(value, field, { seen: new Set() }, 0);
+  const encoded = JSON.stringify(normalized);
+  if (Buffer.byteLength(encoded, "utf8") > MAX_JSON_BYTES) {
+    throw invalidArgument(`${field} exceeds ${MAX_JSON_BYTES} encoded bytes`);
+  }
+  return normalized;
+}
+
+export function canonicalJson(value, field = "value") {
+  return JSON.stringify(normalizeJson(value, field));
+}
+
+export function normalizeEpochMs(value, field) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw invalidArgument(
+      `${field} must be a non-negative safe-integer epoch ms`,
+    );
+  }
+  return value;
+}
+
+export function normalizeMaxAttempts(value = DEFAULT_MAX_ATTEMPTS) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_JOB_ATTEMPTS) {
+    throw invalidArgument(
+      `maxAttempts must be an integer between 1 and ${MAX_JOB_ATTEMPTS}`,
+    );
+  }
+  return value;
+}
+
+export function normalizeHistoryLimit(value = DEFAULT_HISTORY_LIMIT) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw invalidArgument("history limit must be a positive integer");
+  }
+  return Math.min(value, MAX_HISTORY_LIMIT);
+}
+
+/**
+ * Stable identity for one logical firing. All adapters must supply the same
+ * triggerKey for the same logical schedule. Including jobRevision prevents an
+ * edited job from silently inheriting the old definition's idempotency slot.
+ */
+export function deriveOccurrenceIdentity({
+  jobId,
+  jobRevision,
+  scheduledFor,
+  triggerKey,
+}) {
+  const material = canonicalJson(
+    {
+      contractVersion: SCHEDULER_SCHEMA_VERSION,
+      jobId: normalizeIdentifier(jobId, "jobId"),
+      jobRevision:
+        Number.isSafeInteger(jobRevision) && jobRevision >= 1
+          ? jobRevision
+          : (() => {
+              throw invalidArgument("jobRevision must be a positive integer");
+            })(),
+      scheduledFor: normalizeEpochMs(scheduledFor, "scheduledFor"),
+      triggerKey: normalizeIdentifier(triggerKey, "triggerKey"),
+    },
+    "occurrenceIdentity",
+  );
+  const digest = createHash("sha256")
+    .update("chainlesschain.scheduler.occurrence.v1\0", "utf8")
+    .update(material, "utf8")
+    .digest("hex");
+  return Object.freeze({
+    occurrenceId: `occ_${digest}`,
+    idempotencyKey: `scheduler:v1:${digest}`,
+  });
+}