chainlesschain 0.166.91 → 0.166.92

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

@@ -1,414 +1,27 @@
-import { createHash } from "node:crypto";
-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",
-  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",
-  "schedulerPolicyRevision",
-  "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. The runtime
- * still has to resolve and enforce those references 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",
-      ),
-      ...(refs.schedulerPolicyRevision === undefined
-        ? {}
-        : {
-            schedulerPolicyRevision: normalizeOptionalIdentifier(
-              refs.schedulerPolicyRevision,
-              "authority.authorizationRefs.schedulerPolicyRevision",
-            ),
-          }),
-      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);
-}
-
-/**
- * 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
- * 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}`,
-  });
-}
+// Compatibility entry: both hosts share the same implementation and error type.
+import schedulerContract from "@chainlesschain/session-core/scheduler-contract";
+
+export const {
+  SCHEDULER_SCHEMA_VERSION,
+  AUTHORITY_ENVELOPE_VERSION,
+  RUNTIME_CONTROL_SCHEMA_VERSION,
+  RUNTIME_PAUSE_RESUME,
+  RUNTIME_CONTROL_SAFE_POINTS,
+  OCCURRENCE_STATUS,
+  DEFAULT_MAX_ATTEMPTS,
+  MAX_JOB_ATTEMPTS,
+  DEFAULT_HISTORY_LIMIT,
+  MAX_HISTORY_LIMIT,
+  MAX_JSON_BYTES,
+  SchedulerKernelError,
+  invalidArgument,
+  normalizeIdentifier,
+  normalizeAuthorityEnvelope,
+  normalizeJson,
+  canonicalJson,
+  normalizeEpochMs,
+  normalizeMaxAttempts,
+  normalizeHistoryLimit,
+  normalizeRuntimeControlCapability,
+  deriveOccurrenceIdentity,
+} = schedulerContract;