@serve.zone/interfaces 27.3.1 → 27.5.0

package/ts/data/runtimeassignment.ts

@@ -0,0 +1,402 @@
+import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
+import { buildDigestPinnedImageReference, isSha256Digest } from './immutableimage.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+
+export interface IRuntimeControllerV1 {
+  kind: 'cloudly' | 'onebox';
+  id: string;
+  /** Persisted authority incarnation; changing it requires explicit re-admission. */
+  epoch: string;
+}
+
+/** Content-bound reference, not a credential, mount path or permission grant. */
+export interface IRuntimeAuthorityReferenceV1 {
+  id: string;
+  generation: number;
+  digest: TSha256Digest;
+}
+
+export interface IRuntimeAssignmentReferenceV1 {
+  assignmentId: string;
+  generation: number;
+  digest: TSha256Digest;
+}
+
+/** Derived from authenticated transport and locally configured ownership. */
+export interface IRuntimeAssignmentScopeV1 {
+  controller: IRuntimeControllerV1;
+  organizationId: string;
+  nodeId: string;
+  runtimeNamespace: string;
+}
+
+export type TRuntimeAssignmentDispositionV1 =
+  | 'run'
+  | 'stop-preserve'
+  | 'remove-runtime-preserve-storage';
+
+export interface IRuntimeAssignmentV1 extends IRuntimeAssignmentScopeV1 {
+  schemaVersion: 1;
+  assignmentId: string;
+  serviceId: string;
+  /** Stable logical replica; independent of container IDs and execution attempts. */
+  replicaId: string;
+  /** One execution attempt, immutable for this assignment. */
+  attemptId: string;
+  /** Logical topology provenance; placement authority remains nodeId. */
+  workerGroupId: string | null;
+  siteId: string | null;
+  generation: number;
+  /** Exact CAS predecessor; null only at generation 1. */
+  previous: IRuntimeAssignmentReferenceV1 | null;
+  disposition: TRuntimeAssignmentDispositionV1;
+  /** No automatic relocation or expiry-based claim of a stopped writer. */
+  offlinePolicy: 'continue-node-bound';
+  workload: {
+    registryHost: string;
+    repository: string;
+    imageDigest: TSha256Digest;
+    platform: TImmutableContainerPlatform;
+    /** Immutable complete invocation/configuration owned by the controller. */
+    config: IRuntimeAuthorityReferenceV1;
+    network: IRuntimeAuthorityReferenceV1 | null;
+    secrets: IRuntimeAuthorityReferenceV1 | null;
+    /** Sorted unique reference IDs. Empty means no persistent storage claims. */
+    storage: IRuntimeAuthorityReferenceV1[];
+  };
+  digest: TSha256Digest;
+}
+
+export type TRuntimeAssignmentDecisionV1 =
+  | { status: 'accept' | 'replay'; assignment: IRuntimeAssignmentV1 }
+  | { status: 'reject'; reason: 'invalid' | 'scope-mismatch' | 'conflict' | 'stale'
+      | 'predecessor-mismatch' | 'attempt-mismatch' | 'disposition-regression' };
+
+/** Value-free execution evidence. Receipt/acceptance alone never means ready. */
+export interface IRuntimeAssignmentObservationV1 {
+  schemaVersion: 1;
+  assignment: IRuntimeAssignmentReferenceV1;
+  /** Authenticated reporter session; its authority is verified by the receiver. */
+  reporterSessionId: string;
+  /** Durable per-assignment counter; never resets when a reporter reconnects. */
+  sequence: number;
+  observedAt: number;
+  phase: 'pending' | 'running' | 'stopped' | 'removed' | 'failed' | 'unknown';
+  ready: boolean;
+  runtime: {
+    sandboxId: string;
+    containerId: string;
+    imageDigest: TSha256Digest;
+  } | null;
+  digest: TSha256Digest;
+}
+
+export const runtimeAssignmentV1Contract = Object.freeze({
+  assignmentDigestDomain: 'serve.zone/runtime-assignment-v1',
+  observationDigestDomain: 'serve.zone/runtime-assignment-observation-v1',
+  maximumStorageReferences: 64,
+  omission: 'no-effect',
+  removal: 'retain-assignment-tombstone-and-storage',
+} as const);
+
+const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
+const isIdentifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+const isPositiveInteger = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg > 0;
+const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
+  typeof valueArg === 'string' && isSha256Digest(valueArg);
+
+/** Reject accessors before reading any fields; do not run input-owned code. */
+const isExactRecord = (
+  valueArg: unknown,
+  keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const prototype = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  const keys = Reflect.ownKeys(valueArg);
+  return keys.length === keysArg.length && keys.every((keyArg) => {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
+    return typeof keyArg === 'string' && keysArg.includes(keyArg)
+      && descriptor?.enumerable === true && Object.hasOwn(descriptor, 'value');
+  });
+};
+
+const isController = (valueArg: unknown): valueArg is IRuntimeControllerV1 =>
+  isExactRecord(valueArg, ['kind', 'id', 'epoch'])
+  && (valueArg.kind === 'cloudly' || valueArg.kind === 'onebox')
+  && isIdentifier(valueArg.id) && isIdentifier(valueArg.epoch);
+const isAuthorityReference = (valueArg: unknown): valueArg is IRuntimeAuthorityReferenceV1 =>
+  isExactRecord(valueArg, ['id', 'generation', 'digest'])
+  && isIdentifier(valueArg.id) && isPositiveInteger(valueArg.generation) && isDigest(valueArg.digest);
+const isAssignmentReference = (valueArg: unknown): valueArg is IRuntimeAssignmentReferenceV1 =>
+  isExactRecord(valueArg, ['assignmentId', 'generation', 'digest'])
+  && isIdentifier(valueArg.assignmentId) && isPositiveInteger(valueArg.generation)
+  && isDigest(valueArg.digest);
+
+const assignmentKeys = [
+  'schemaVersion', 'controller', 'organizationId', 'nodeId', 'runtimeNamespace',
+  'assignmentId', 'serviceId', 'replicaId', 'attemptId', 'workerGroupId', 'siteId',
+  'generation', 'previous', 'disposition', 'offlinePolicy', 'workload', 'digest',
+] as const;
+
+const assertAssignment = (valueArg: unknown): IRuntimeAssignmentV1 => {
+  if (!isExactRecord(valueArg, assignmentKeys)
+    || valueArg.schemaVersion !== 1 || !isController(valueArg.controller)
+    || !isPositiveInteger(valueArg.generation) || !isDigest(valueArg.digest)
+    || valueArg.offlinePolicy !== 'continue-node-bound'
+    || !['run', 'stop-preserve', 'remove-runtime-preserve-storage'].includes(
+      valueArg.disposition as string,
+    )) fail('runtime assignment must use its exact v1 schema');
+  for (const key of ['organizationId', 'nodeId', 'runtimeNamespace', 'assignmentId',
+    'serviceId', 'replicaId', 'attemptId']) {
+    if (!isIdentifier(valueArg[key])) fail(`runtime assignment ${key} must be a canonical identifier`);
+  }
+  for (const key of ['workerGroupId', 'siteId']) {
+    if (valueArg[key] !== null && !isIdentifier(valueArg[key])) fail('invalid runtime topology ID');
+  }
+  if (valueArg.generation === 1 ? valueArg.previous !== null
+    : !isAssignmentReference(valueArg.previous)
+      || valueArg.previous.assignmentId !== valueArg.assignmentId
+      || valueArg.previous.generation !== (valueArg.generation as number) - 1) {
+    fail('runtime assignment must bind its exact preceding generation');
+  }
+  const workload = valueArg.workload;
+  if (!isExactRecord(workload, ['registryHost', 'repository', 'imageDigest', 'platform',
+    'config', 'network', 'secrets', 'storage'])
+    || typeof workload.registryHost !== 'string' || workload.registryHost.length > 253
+    || typeof workload.repository !== 'string' || workload.repository.length > 255
+    || !isDigest(workload.imageDigest)
+    || !['linux/amd64', 'linux/arm64'].includes(workload.platform as string)
+    || !isAuthorityReference(workload.config)
+    || (workload.network !== null && !isAuthorityReference(workload.network))
+    || (workload.secrets !== null && !isAuthorityReference(workload.secrets))
+    || !Array.isArray(workload.storage)
+    || workload.storage.length > runtimeAssignmentV1Contract.maximumStorageReferences) {
+    fail('runtime assignment workload must use exact immutable references');
+  }
+  buildDigestPinnedImageReference(workload.registryHost as string,
+    workload.repository as string, workload.imageDigest as TSha256Digest);
+  let previousId = '';
+  for (let index = 0; index < (workload.storage as unknown[]).length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(workload.storage, String(index));
+    if (!descriptor || !Object.hasOwn(descriptor, 'value')
+      || !isAuthorityReference(descriptor.value) || descriptor.value.id <= previousId) {
+      fail('runtime assignment storage references must be dense, sorted and unique');
+    }
+    previousId = descriptor.value.id;
+  }
+  canonicalizeStrictJson(valueArg, fail);
+  return valueArg as unknown as IRuntimeAssignmentV1;
+};
+
+const digestPayload = async (domainArg: string, valueArg: { digest: TSha256Digest }): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = valueArg;
+  return `sha256:${await createCanonicalJsonSha256Hex(
+    canonicalizeStrictJson({ domain: domainArg, payload }, fail), fail,
+  )}`;
+};
+
+/** Digest helpers validate structure and exclude only the object's own digest. */
+export const computeRuntimeAssignmentV1Digest = async (
+  assignmentArg: IRuntimeAssignmentV1,
+): Promise<TSha256Digest> => digestPayload(
+  runtimeAssignmentV1Contract.assignmentDigestDomain, assertAssignment(assignmentArg),
+);
+
+export const validateRuntimeAssignmentV1 = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const assignment = snapshotAssignment(valueArg);
+    return assignment.digest === await computeRuntimeAssignmentV1Digest(assignment)
+      ? [] : ['runtime assignment digest does not match'];
+  } catch {
+    return ['runtime assignment must use its exact canonical v1 schema'];
+  }
+};
+
+const snapshotAssignment = (valueArg: unknown): IRuntimeAssignmentV1 =>
+  JSON.parse(canonicalizeStrictJson(assertAssignment(valueArg), fail)) as IRuntimeAssignmentV1;
+
+export const getRuntimeAssignmentV1Reference = (
+  assignmentArg: IRuntimeAssignmentV1,
+): IRuntimeAssignmentReferenceV1 => ({
+  assignmentId: assignmentArg.assignmentId,
+  generation: assignmentArg.generation,
+  digest: assignmentArg.digest,
+});
+
+const canonical = (valueArg: unknown): string => canonicalizeStrictJson(valueArg, fail);
+const immutableAttempt = (assignmentArg: IRuntimeAssignmentV1): string => {
+  const { generation, previous, disposition, digest, ...attempt } = assignmentArg;
+  return canonical(attempt);
+};
+
+/**
+ * Pure CAS decision, not authentication or execution. The caller must persist
+ * acceptance atomically before effects, serialize replica ownership, and retain
+ * removed assignments as tombstones. New attempts require separate stop/fencing
+ * admission for every older writer. An omitted assignment causes no transition.
+ * Persist only the returned detached snapshot, never the mutable input object.
+ */
+export const evaluateRuntimeAssignmentV1 = async (
+  incomingArg: IRuntimeAssignmentV1,
+  acceptedArg: IRuntimeAssignmentV1 | null,
+  trustedScopeArg: IRuntimeAssignmentScopeV1,
+): Promise<TRuntimeAssignmentDecisionV1> => {
+  try {
+    incomingArg = snapshotAssignment(incomingArg);
+    acceptedArg = acceptedArg === null ? null : snapshotAssignment(acceptedArg);
+    if (!isExactRecord(trustedScopeArg, ['controller', 'organizationId', 'nodeId', 'runtimeNamespace'])
+      || !isController(trustedScopeArg.controller)
+      || !isIdentifier(trustedScopeArg.organizationId) || !isIdentifier(trustedScopeArg.nodeId)
+      || !isIdentifier(trustedScopeArg.runtimeNamespace)) return { status: 'reject', reason: 'invalid' };
+    trustedScopeArg = JSON.parse(canonical(trustedScopeArg)) as IRuntimeAssignmentScopeV1;
+  } catch {
+    return { status: 'reject', reason: 'invalid' };
+  }
+  if ((await validateRuntimeAssignmentV1(incomingArg)).length
+    || (acceptedArg !== null && (await validateRuntimeAssignmentV1(acceptedArg)).length)) {
+    return { status: 'reject', reason: 'invalid' };
+  }
+  const matchesScope = (assignmentArg: IRuntimeAssignmentV1): boolean =>
+    assignmentArg.controller.kind === trustedScopeArg.controller.kind
+    && assignmentArg.controller.id === trustedScopeArg.controller.id
+    && assignmentArg.controller.epoch === trustedScopeArg.controller.epoch
+    && assignmentArg.organizationId === trustedScopeArg.organizationId
+    && assignmentArg.nodeId === trustedScopeArg.nodeId
+    && assignmentArg.runtimeNamespace === trustedScopeArg.runtimeNamespace;
+  if (!matchesScope(incomingArg) || (acceptedArg !== null && !matchesScope(acceptedArg))) {
+    return { status: 'reject', reason: 'scope-mismatch' };
+  }
+  if (acceptedArg === null) {
+    return incomingArg.generation === 1
+      && incomingArg.disposition === 'run'
+      ? { status: 'accept', assignment: incomingArg }
+      : { status: 'reject', reason: 'predecessor-mismatch' };
+  }
+  if (incomingArg.assignmentId !== acceptedArg.assignmentId) {
+    return { status: 'reject', reason: 'attempt-mismatch' };
+  }
+  if (incomingArg.generation < acceptedArg.generation) return { status: 'reject', reason: 'stale' };
+  if (incomingArg.generation === acceptedArg.generation) {
+    return incomingArg.digest === acceptedArg.digest
+      ? { status: 'replay', assignment: acceptedArg } : { status: 'reject', reason: 'conflict' };
+  }
+  if (canonical(incomingArg.previous) !== canonical(getRuntimeAssignmentV1Reference(acceptedArg))) {
+    return { status: 'reject', reason: 'predecessor-mismatch' };
+  }
+  if (immutableAttempt(incomingArg) !== immutableAttempt(acceptedArg)) {
+    return { status: 'reject', reason: 'attempt-mismatch' };
+  }
+  const order: Record<TRuntimeAssignmentDispositionV1, number> = {
+    run: 0, 'stop-preserve': 1, 'remove-runtime-preserve-storage': 2,
+  };
+  if (order[incomingArg.disposition] !== order[acceptedArg.disposition] + 1) {
+    return { status: 'reject', reason: 'disposition-regression' };
+  }
+  return { status: 'accept', assignment: incomingArg };
+};
+
+const assertObservation = (valueArg: unknown): IRuntimeAssignmentObservationV1 => {
+  if (!isExactRecord(valueArg, ['schemaVersion', 'assignment', 'reporterSessionId',
+    'sequence', 'observedAt', 'phase', 'ready', 'runtime', 'digest'])
+    || valueArg.schemaVersion !== 1 || !isAssignmentReference(valueArg.assignment)
+    || !isIdentifier(valueArg.reporterSessionId) || !isPositiveInteger(valueArg.sequence)
+    || !isPositiveInteger(valueArg.observedAt) || !isDigest(valueArg.digest)
+    || typeof valueArg.ready !== 'boolean'
+    || !['pending', 'running', 'stopped', 'removed', 'failed', 'unknown'].includes(valueArg.phase as string)) {
+    fail('runtime observation must use its exact v1 schema');
+  }
+  if (valueArg.runtime !== null && (!isExactRecord(valueArg.runtime, [
+    'sandboxId', 'containerId', 'imageDigest',
+  ]) || !isIdentifier(valueArg.runtime.sandboxId) || !isIdentifier(valueArg.runtime.containerId)
+    || !isDigest(valueArg.runtime.imageDigest))) fail('runtime identity must be canonical');
+  if ((valueArg.ready && valueArg.phase !== 'running')
+    || (valueArg.phase === 'running' && valueArg.runtime === null)
+    || (valueArg.phase === 'removed' && valueArg.runtime !== null)) {
+    fail('runtime observation readiness and identity contradict its phase');
+  }
+  canonical(valueArg);
+  return valueArg as unknown as IRuntimeAssignmentObservationV1;
+};
+
+export const computeRuntimeAssignmentObservationV1Digest = async (
+  observationArg: IRuntimeAssignmentObservationV1,
+): Promise<TSha256Digest> => digestPayload(
+  runtimeAssignmentV1Contract.observationDigestDomain, assertObservation(observationArg),
+);
+
+/** Checks exact assignment evidence; transport must separately bind reporter/session. */
+export const validateRuntimeAssignmentObservationV1 = async (
+  observationArg: unknown,
+  assignmentArg: IRuntimeAssignmentV1,
+): Promise<string[]> => {
+  try {
+    const observation = JSON.parse(canonical(assertObservation(observationArg))) as IRuntimeAssignmentObservationV1;
+    assignmentArg = snapshotAssignment(assignmentArg);
+    if ((await validateRuntimeAssignmentV1(assignmentArg)).length) return ['invalid assignment'];
+    if (canonical(observation.assignment) !== canonical(getRuntimeAssignmentV1Reference(assignmentArg))) {
+      return ['runtime observation does not match the exact assignment'];
+    }
+    if (observation.digest !== await computeRuntimeAssignmentObservationV1Digest(observation)) {
+      return ['runtime observation digest does not match'];
+    }
+    if (observation.ready && (assignmentArg.disposition !== 'run'
+      || observation.runtime?.imageDigest !== assignmentArg.workload.imageDigest)) {
+      return ['runtime readiness does not match authorized execution'];
+    }
+    return [];
+  } catch {
+    return ['runtime observation must use its exact canonical v1 schema'];
+  }
+};
+
+export type TRuntimeObservationDecisionV1 =
+  | { status: 'accept' | 'replay'; observation: IRuntimeAssignmentObservationV1 }
+  | { status: 'reject'; reason: 'invalid' | 'session-mismatch' | 'stale' | 'conflict' | 'sequence-gap' };
+
+/**
+ * Receiver must authorize the assignment's node before calling this helper.
+ * Compare/persist the returned snapshot atomically with the old receipt. A new
+ * session continues the durable counter; it does not reset observation history.
+ * Across dispositions, the old receipt must reference the exact predecessor;
+ * receivers must process each revision's observations in order.
+ * These observations are never sufficient authority to relocate a storage writer.
+ */
+export const evaluateRuntimeAssignmentObservationV1 = async (
+  incomingArg: IRuntimeAssignmentObservationV1,
+  acceptedArg: IRuntimeAssignmentObservationV1 | null,
+  assignmentArg: IRuntimeAssignmentV1,
+  trustedReporterSessionIdArg: string,
+): Promise<TRuntimeObservationDecisionV1> => {
+  try {
+    incomingArg = JSON.parse(canonical(assertObservation(incomingArg))) as IRuntimeAssignmentObservationV1;
+    acceptedArg = acceptedArg === null ? null
+      : JSON.parse(canonical(assertObservation(acceptedArg))) as IRuntimeAssignmentObservationV1;
+    assignmentArg = snapshotAssignment(assignmentArg);
+    if (!isIdentifier(trustedReporterSessionIdArg)
+      || (await validateRuntimeAssignmentObservationV1(incomingArg, assignmentArg)).length
+      || (acceptedArg !== null && (
+        acceptedArg.digest !== await computeRuntimeAssignmentObservationV1Digest(acceptedArg)
+        || acceptedArg.assignment.assignmentId !== assignmentArg.assignmentId
+        || (canonical(acceptedArg.assignment) !== canonical(getRuntimeAssignmentV1Reference(assignmentArg))
+          && canonical(acceptedArg.assignment) !== canonical(assignmentArg.previous))
+      ))) return { status: 'reject', reason: 'invalid' };
+    if (incomingArg.reporterSessionId !== trustedReporterSessionIdArg) {
+      return { status: 'reject', reason: 'session-mismatch' };
+    }
+    if (acceptedArg !== null && incomingArg.sequence <= acceptedArg.sequence) {
+      if (incomingArg.sequence < acceptedArg.sequence) return { status: 'reject', reason: 'stale' };
+      return incomingArg.digest === acceptedArg.digest
+        ? { status: 'replay', observation: acceptedArg }
+        : { status: 'reject', reason: 'conflict' };
+    }
+    if (incomingArg.sequence !== (acceptedArg?.sequence ?? 0) + 1) {
+      return { status: 'reject', reason: 'sequence-gap' };
+    }
+    return { status: 'accept', observation: incomingArg };
+  } catch {
+    return { status: 'reject', reason: 'invalid' };
+  }
+};