@serve.zone/interfaces 31.7.0 → 31.9.0

package/ts/data/runtimeconfig.ts

@@ -12,6 +12,10 @@ import {
 import type { IRuntimeAssignmentV1, IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
 import { snapshotRuntimeAssignmentV1, validateRuntimeAssignmentV1 } from './runtimeassignment.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+import {
+  assertRuntimeReadiness, isBoundedInteger, isExactRecord, isRuntimeCpuMillis, isRuntimeIdentityNumber,
+  isRuntimeLogPolicy, isRuntimeMemoryBytes, isRuntimePortName, runtimePolicyLimits,
+} from '../private/runtimepolicy.js';
 
 /** A container target only; declaration does not publish a host or gateway port. */
 export interface IRuntimeConfigTargetPortV1 {
@@ -128,28 +132,16 @@ export const runtimeConfigV1Contract = Object.freeze({
   maximumCanonicalBytes: 262_144,
   maximumEnvironmentEntries: 128,
   maximumTargetPorts: 64,
-  maximumReadinessDurationMs: 3_600_000,
-  maximumLogRetentionMs: 31_536_000_000,
+  maximumReadinessDurationMs: runtimePolicyLimits.maximumReadinessDurationMs,
+  maximumLogRetentionMs: runtimePolicyLimits.maximumLogRetentionMs,
 } as const);
 
 const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
 const encoder = new TextEncoder();
-const isInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
-  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
-  && valueArg >= minimumArg && valueArg <= maximumArg;
 const isIdentifier = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
 const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
   typeof valueArg === 'string' && isSha256Digest(valueArg);
-const isPortName = (valueArg: unknown): valueArg is string =>
-  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
-const isExactRecord = (
-  valueArg: unknown, keysArg: readonly string[],
-): valueArg is Record<string, unknown> => {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
-  const keys = Object.keys(valueArg);
-  return keys.length === keysArg.length && keys.every((keyArg) => keysArg.includes(keyArg));
-};
 
 /**
  * Bound traversal before canonicalization and copy descriptor values so input
@@ -183,7 +175,7 @@ const snapshotBoundedJson = (valueArg: unknown): unknown => {
       if (array) {
         const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
         const length = lengthDescriptor?.value;
-        if (!isInteger(length, 0, 256) || keys.length !== length + 1) {
+        if (!isBoundedInteger(length, 0, 256) || keys.length !== length + 1) {
           fail('runtime config requires bounded dense arrays');
         }
         const result: unknown[] = [];
@@ -216,60 +208,12 @@ const snapshotBoundedJson = (valueArg: unknown): unknown => {
   return JSON.parse(canonical);
 };
 
-const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
-  'successThreshold', 'failureThreshold'] as const;
-const assertReadiness = (valueArg: unknown, portsArg: IRuntimeConfigTargetPortV1[]): void => {
-  if (!valueArg || typeof valueArg !== 'object') fail('runtime config readiness is required');
-  const value = valueArg as Record<string, unknown>;
-  const keys = value.kind === 'process' ? ['kind', ...timingKeys]
-    : value.kind === 'tcp' ? ['kind', ...timingKeys, 'targetPort', 'port']
-      : value.kind === 'http' ? ['kind', ...timingKeys, 'targetPort', 'port',
-        'scheme', 'host', 'path', 'expectedStatusCodes', 'followRedirects'] : [];
-  if (keys.length === 0 || !isExactRecord(value, keys)
-    || !isInteger(value.initialDelayMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.startupGraceMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.intervalMs, 100, runtimeConfigV1Contract.maximumReadinessDurationMs)
-    || !isInteger(value.timeoutMs, 1, 60_000)
-    || !isInteger(value.successThreshold, 1, 100)
-    || !isInteger(value.failureThreshold, 1, 100)
-    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
-    fail('runtime config readiness must use explicit bounded timing and exact schema');
-  }
-  if (value.kind === 'process') return;
-  const target = portsArg.find((portArg) => portArg.name === value.targetPort);
-  if (!isPortName(value.targetPort) || !target || target.protocol !== 'tcp'
-    || !isInteger(value.port, target.port, target.portEnd)) {
-    fail('runtime config readiness must select a declared TCP target and port');
-  }
-  if (value.kind === 'tcp') return;
-  if ((value.scheme !== 'http' && value.scheme !== 'https') || value.followRedirects !== false
-    || typeof value.host !== 'string' || value.host.length > 253
-    || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/.test(value.host)
-    || typeof value.path !== 'string' || value.path.length > 4096
-    || !value.path.startsWith('/') || value.path.startsWith('//')
-    || /[^\x21-\x7e]|[\\#]/.test(value.path)
-    || /%(?![0-9A-F]{2})/.test(value.path)
-    || !Array.isArray(value.expectedStatusCodes) || value.expectedStatusCodes.length === 0
-    || value.expectedStatusCodes.length > 32) {
-    fail('runtime config HTTP readiness must use an exact bounded request policy');
-  }
-  const parsed = new URL(value.path, 'http://runtime.invalid');
-  if (`${parsed.pathname}${parsed.search}` !== value.path) fail('runtime config HTTP path must be canonical');
-  let previousCode = 0;
-  for (const code of value.expectedStatusCodes) {
-    if (!isInteger(code, 200, 599) || code <= previousCode) {
-      fail('runtime config HTTP status expectations must be sorted unique final codes');
-    }
-    previousCode = code;
-  }
-};
-
 const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
   if (!isExactRecord(valueArg, ['schemaVersion', 'id', 'generation', 'organizationId', 'serviceId',
     'image', 'environment', 'workingDirectory', 'cpuMillis', 'memoryBytes', 'readonlyRootfs',
     'runAsUser', 'runAsGroup', 'targetPorts', 'readiness', 'logs', 'digest'])
     || valueArg.schemaVersion !== 1 || !isIdentifier(valueArg.id)
-    || !isInteger(valueArg.generation, 1, Number.MAX_SAFE_INTEGER)
+    || !isBoundedInteger(valueArg.generation, 1, Number.MAX_SAFE_INTEGER)
     || !isIdentifier(valueArg.organizationId) || !isIdentifier(valueArg.serviceId)
     || !isDigest(valueArg.digest)) fail('runtime config must use its exact v1 schema');
   const image = valueArg.image;
@@ -297,11 +241,11 @@ const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
   if (typeof directory !== 'string' || !directory.startsWith('/')
     || encoder.encode(directory).byteLength > 4096 || /[\u0000-\u001f\u007f]/.test(directory)
     || (directory !== '/' && directory.split('/').slice(1).some((partArg) => !partArg || partArg === '.' || partArg === '..'))
-    || !(valueArg.cpuMillis === null || isInteger(valueArg.cpuMillis, 1, 1_000_000))
-    || !isInteger(valueArg.memoryBytes, 16 * 1024 * 1024, 2 ** 50)
+    || !isRuntimeCpuMillis(valueArg.cpuMillis)
+    || !isRuntimeMemoryBytes(valueArg.memoryBytes)
     || typeof valueArg.readonlyRootfs !== 'boolean'
     || !((valueArg.runAsUser === null && valueArg.runAsGroup === null)
-      || (isInteger(valueArg.runAsUser, 0, 2 ** 31 - 1) && isInteger(valueArg.runAsGroup, 0, 2 ** 31 - 1)))) {
+      || (isRuntimeIdentityNumber(valueArg.runAsUser) && isRuntimeIdentityNumber(valueArg.runAsGroup)))) {
     fail('runtime config requires canonical directory and explicit resource and identity policies');
   }
   const ports = valueArg.targetPorts;
@@ -312,8 +256,8 @@ const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
   const validatedPorts: IRuntimeConfigTargetPortV1[] = [];
   for (const port of ports) {
     if (!isExactRecord(port, ['name', 'port', 'portEnd', 'protocol'])
-      || !isPortName(port.name) || port.name <= previousName
-      || !isInteger(port.port, 1, 65535) || !isInteger(port.portEnd, port.port, 65535)
+      || !isRuntimePortName(port.name) || port.name <= previousName
+      || !isBoundedInteger(port.port, 1, 65535) || !isBoundedInteger(port.portEnd, port.port, 65535)
       || (port.protocol !== 'tcp' && port.protocol !== 'udp')
       || validatedPorts.some((previousArg) => previousArg.protocol === port.protocol
         && (port.port as number) <= previousArg.portEnd && (port.portEnd as number) >= previousArg.port)) {
@@ -322,13 +266,10 @@ const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
     previousName = port.name;
     validatedPorts.push(port as unknown as IRuntimeConfigTargetPortV1);
   }
-  assertReadiness(valueArg.readiness, validatedPorts);
-  const logs = valueArg.logs;
-  if (!isExactRecord(logs, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
-    || !isInteger(logs.maximumLineBytes, 1, 1_048_576)
-    || !isInteger(logs.maximumBufferedBytes, 1, 67_108_864)
-    || logs.maximumBufferedBytes < logs.maximumLineBytes
-    || !isInteger(logs.retentionMs, 1, runtimeConfigV1Contract.maximumLogRetentionMs)) {
+  assertRuntimeReadiness(valueArg.readiness, (targetPortArg, portArg) => validatedPorts.some((targetArg) =>
+    targetArg.name === targetPortArg && targetArg.protocol === 'tcp'
+    && portArg >= targetArg.port && portArg <= targetArg.portEnd), fail);
+  if (!isRuntimeLogPolicy(valueArg.logs)) {
     fail('runtime config logs require explicit bounded line, buffer and retention limits');
   }
   return valueArg as unknown as IRuntimeConfigV1;

package/ts/data/serviceruntime.ts

@@ -0,0 +1,208 @@
+import type {
+  IRuntimeAssignmentObservationV1, IRuntimeAssignmentReferenceV1, TRuntimeAssignmentDispositionV1,
+} from './runtimeassignment.js';
+import type { IRuntimeConfigLogPolicyV1, TRuntimeConfigReadinessV1 } from './runtimeconfig.js';
+import { runtimeNetworkAuthorityV1Contract } from './networkauthority.js';
+import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkRecord, networkSorted,
+  requireNetwork } from '../private/networkcontract.js';
+import { failProducer, isOneOf, producerSafe, variantOf } from '../private/producercontract.js';
+import { assertRuntimeReadiness, isBoundedInteger, isRuntimeCpuMillis, isRuntimeIdentityNumber, isRuntimeLogPolicy,
+  isRuntimeMemoryBytes } from '../private/runtimepolicy.js';
+
+/** `nodes` pins the service to exactly these nodes: sorted, unique and never empty. */
+export type TServiceRuntimePlacement =
+  | { kind: 'every-node' }
+  | { kind: 'nodes'; nodeIds: string[] };
+
+/**
+ * The execution policy a service's runtime configs are built with. It carries everything the
+ * runtime config seals except what only the service and its image supply: environment, working
+ * directory and target ports. A readiness probe names a target port, which the runtime config then
+ * requires the service to declare.
+ */
+export interface IServiceRuntimeProfile {
+  /** null explicitly requests no CPU quota. */
+  cpuMillis: number | null;
+  memoryBytes: number;
+  readiness: TRuntimeConfigReadinessV1;
+  logs: IRuntimeConfigLogPolicyV1;
+  readonlyRootfs: boolean;
+  /** null runs the image's own OCI user, exactly as a runtime config's null identity pair does. */
+  runAs: { user: number; group: number } | null;
+}
+
+/**
+ * `isolated` gives the workload no network authority. `attached` joins the runtime network with
+ * public egress on or off and the platform endpoints it may reach, by id: sorted and unique.
+ */
+export type TServiceRuntimeNetwork =
+  | { mode: 'isolated' }
+  | { mode: 'attached'; publicEgress: boolean; platformEndpointIds: string[] };
+
+/**
+ * What Cloudly runs for one service on a Pallet cluster. Stored complete, never defaulted at read
+ * time, and beside the service document rather than inside it, so a hold written by a cutover
+ * never races an operator's service edit.
+ */
+export interface IServiceRuntimeSpec {
+  /** The service id. */
+  id: string;
+  /** The service's organization, copied by Cloudly; never caller-chosen. */
+  organizationId: string;
+  clusterId: string;
+  placement: TServiceRuntimePlacement;
+  replicasPerNode: number;
+  /** While true, the service runs nowhere and every slot keeps its storage. */
+  hold: boolean;
+  profile: IServiceRuntimeProfile;
+  network: TServiceRuntimeNetwork;
+  /** Compare-and-swap counter; every write advances it by one. */
+  revision: number;
+}
+
+/** What an administrator writes; Cloudly supplies the service id, organization and revision. */
+export type TServiceRuntimeSpecWritableData = Omit<IServiceRuntimeSpec, 'id' | 'organizationId' | 'revision'>;
+
+export const serviceRuntimeContract = Object.freeze({
+  maximumReplicasPerNode: 64,
+  /** A service whose placement desires more replicas than this is refused as `replica-limit`. */
+  maximumReplicas: 64,
+  /** A node can run workloads only as an egress member of the protected authority, which admits at most this many. */
+  maximumPinnedNodes: runtimeNetworkAuthorityV1Contract.maximumEgressAuthorities,
+  maximumPlatformEndpoints: runtimeNetworkAuthorityV1Contract.maximumPlatformEndpoints,
+  /** The largest `limit` `getClusterRuntimeAssignments` accepts; Cloudly refuses a larger one. */
+  maximumAssignmentPageSize: 256,
+} as const);
+
+const serviceRuntimeWaitingReasons = ['node-network-pending', 'conflict', 'failure-backoff'] as const;
+const serviceRuntimeRefusals = [
+  'cluster-runtime-missing', 'organization-missing', 'image-plan-missing', 'platform-unsupported',
+  'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'readiness-target-undeclared',
+  'environment-too-large', 'no-eligible-node', 'replica-limit',
+] as const;
+
+/**
+ * Why the producer is not converging yet, though nothing needs an administrator:
+ * `node-network-pending` waits for a node's network readiness, `conflict` for a sweep over inputs
+ * that changed while it ran, `failure-backoff` for a failed replica's backoff to elapse.
+ */
+export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
+
+/** Why the producer admits nothing for this spec revision. A refusal never retires running slots. */
+export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
+
+interface IServiceRuntimeStatusBase {
+  /** The service id. */
+  id: string;
+  /** The spec revision this verdict is about. */
+  specRevision: number;
+  /** Unix milliseconds on Cloudly's clock. Written only when the verdict changes. */
+  changedAt: number;
+}
+
+/** The producer's verdict on one spec revision. */
+export type IServiceRuntimeStatus = IServiceRuntimeStatusBase & (
+  | { state: 'converged' | 'converging'; reason: null }
+  | { state: 'waiting'; reason: TServiceRuntimeWaitingReason }
+  | { state: 'refused'; reason: TServiceRuntimeRefusal }
+);
+
+/**
+ * `delivered` once the node's own evidence, an observation or a terminal receipt, cites this exact
+ * revision; `undelivered` until then. Cloudly keeps no acknowledgement journal, so a revision the
+ * node admitted but has not yet reported on reads as undelivered.
+ */
+export type TServiceRuntimeAssignmentDelivery = 'undelivered' | 'delivered';
+
+/** One replica slot's current assignment, as an administrator reads it. */
+export interface IServiceRuntimeAssignmentView {
+  serviceId: string;
+  replicaId: string;
+  nodeId: string;
+  /** The current revision; its generation is the one the disposition belongs to. */
+  assignment: IRuntimeAssignmentReferenceV1;
+  disposition: TRuntimeAssignmentDispositionV1;
+  /** The latest accepted observation of this attempt, which may cite an earlier revision. */
+  observation: Pick<IRuntimeAssignmentObservationV1, 'phase' | 'ready' | 'observedAt' | 'sequence'> | null;
+  /** Joined stop and remove receipts of this attempt. */
+  terminalReceiptCount: 0 | 1 | 2;
+  delivery: TServiceRuntimeAssignmentDelivery;
+}
+
+const sortedIds = (value: unknown, maximum: number): string[] =>
+  networkSorted(networkList(value, maximum, networkId), id => id);
+
+const placementOf = (value: unknown): TServiceRuntimePlacement => {
+  const kind = variantOf(value, 'kind');
+  if (kind === 'every-node') {
+    networkRecord(value, ['kind']);
+    return { kind };
+  }
+  requireNetwork(kind === 'nodes');
+  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes);
+  requireNetwork(nodeIds.length > 0);
+  return { kind, nodeIds };
+};
+
+const runAsOf = (value: unknown): IServiceRuntimeProfile['runAs'] => {
+  if (value === null) return null;
+  const item = networkRecord(value, ['user', 'group']);
+  requireNetwork(isRuntimeIdentityNumber(item.user) && isRuntimeIdentityNumber(item.group));
+  return { user: item.user, group: item.group };
+};
+
+const profileOf = (value: unknown): IServiceRuntimeProfile => {
+  const item = networkRecord(value, ['cpuMillis', 'memoryBytes', 'readiness', 'logs', 'readonlyRootfs', 'runAs']);
+  requireNetwork(isRuntimeCpuMillis(item.cpuMillis) && isRuntimeMemoryBytes(item.memoryBytes)
+    && isRuntimeLogPolicy(item.logs) && typeof item.readonlyRootfs === 'boolean');
+  // The profile precedes the service's target ports; the runtime config refuses a target they do not declare.
+  assertRuntimeReadiness(item.readiness, () => true, failProducer);
+  const { maximumLineBytes, maximumBufferedBytes, retentionMs } = item.logs;
+  return { cpuMillis: item.cpuMillis, memoryBytes: item.memoryBytes,
+    readiness: JSON.parse(networkCanonical(item.readiness)) as TRuntimeConfigReadinessV1,
+    logs: { maximumLineBytes, maximumBufferedBytes, retentionMs }, readonlyRootfs: item.readonlyRootfs, runAs: runAsOf(item.runAs) };
+};
+
+const networkOf = (value: unknown): TServiceRuntimeNetwork => {
+  const mode = variantOf(value, 'mode');
+  if (mode === 'isolated') {
+    networkRecord(value, ['mode']);
+    return { mode };
+  }
+  requireNetwork(mode === 'attached');
+  const item = networkRecord(value, ['mode', 'publicEgress', 'platformEndpointIds']);
+  requireNetwork(typeof item.publicEgress === 'boolean');
+  return { mode, publicEgress: item.publicEgress,
+    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints) };
+};
+
+/**
+ * Structural snapshot for exact persistence and for a spec write. Whether the cluster, the nodes and
+ * the platform endpoints exist, and whether the service declares the readiness target, is Cloudly's.
+ */
+export const snapshotServiceRuntimeSpec = (value: unknown): IServiceRuntimeSpec => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'organizationId', 'clusterId', 'placement',
+    'replicasPerNode', 'hold', 'profile', 'network', 'revision']);
+  requireNetwork(isBoundedInteger(item.replicasPerNode, 1, serviceRuntimeContract.maximumReplicasPerNode)
+    && typeof item.hold === 'boolean');
+  return { id: networkId(item.id), organizationId: networkId(item.organizationId), clusterId: networkId(item.clusterId),
+    placement: placementOf(item.placement), replicasPerNode: item.replicasPerNode, hold: item.hold,
+    profile: profileOf(item.profile), network: networkOf(item.network), revision: networkCounter(item.revision) };
+});
+
+/** Structural snapshot for exact persistence: a reason belongs to exactly one state. */
+export const snapshotServiceRuntimeStatus = (value: unknown): IServiceRuntimeStatus => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'specRevision', 'state', 'reason', 'changedAt']);
+  const base: IServiceRuntimeStatusBase = { id: networkId(item.id), specRevision: networkCounter(item.specRevision),
+    changedAt: networkCounter(item.changedAt) };
+  if (item.state === 'converged' || item.state === 'converging') {
+    requireNetwork(item.reason === null);
+    return { ...base, state: item.state, reason: null };
+  }
+  if (item.state === 'waiting') {
+    requireNetwork(isOneOf(serviceRuntimeWaitingReasons, item.reason));
+    return { ...base, state: item.state, reason: item.reason };
+  }
+  requireNetwork(item.state === 'refused' && isOneOf(serviceRuntimeRefusals, item.reason));
+  return { ...base, state: item.state, reason: item.reason };
+});

package/ts/private/networkcontract.ts

@@ -1,5 +1,7 @@
 import type { TSha256Digest } from '../data/immutableimage.js';
 import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from '../data/runtimeassignment.js';
+import type { IRuntimeNetworkDnsLeaseRenewal } from '../data/networklease.js';
+import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScopeV1, IRuntimeNetworkProjectionV1 } from '../data/networkprojection.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
 
 export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
@@ -83,17 +85,49 @@ export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER
 export const networkDigest = (value: unknown): TSha256Digest => {
   requireNetwork(typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)); return value as TSha256Digest;
 };
+/** One encoding for every Ed25519 signature this contract carries: lowercase hex, 64 bytes. */
+export const networkSignature = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[a-f0-9]{128}$/.test(value)); return value;
+};
 export const networkController = (value: unknown): IRuntimeControllerV1 => {
   const item = networkRecord(value, ['kind', 'id', 'epoch']);
   requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');
   return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
 };
+export const networkScope = (item: Record<string, unknown>): IRuntimeNetworkNodeScopeV1 => ({
+  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
+});
+export const networkSameScope = (left: IRuntimeNetworkNodeScopeV1, right: IRuntimeNetworkNodeScopeV1): boolean =>
+  networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;
+export const networkMaximumDnsLeaseMs = 900_000;
+/** One rule for every signed DNS window, projection or renewal: ordered, non-empty, at most fifteen minutes. */
+export const networkDnsWindow = (value: unknown): IRuntimeNetworkDnsWindow => {
+  const item = networkRecord(value, ['issuedAt', 'notBefore', 'expiresAt']);
+  const window = { issuedAt: networkCounter(item.issuedAt), notBefore: networkCounter(item.notBefore), expiresAt: networkCounter(item.expiresAt) };
+  requireNetwork(window.notBefore >= window.issuedAt && window.expiresAt > window.notBefore
+    && window.expiresAt - window.issuedAt <= networkMaximumDnsLeaseMs);
+  return window;
+};
 export const networkReference = (value: unknown): IRuntimeAuthorityReferenceV1 => {
   const item = networkRecord(value, ['id', 'generation', 'digest']);
   return { id: networkId(item.id), generation: networkCounter(item.generation), digest: networkDigest(item.digest) };
 };
 export const networkReferenceOf = (value: IRuntimeAuthorityReferenceV1): IRuntimeAuthorityReferenceV1 =>
   ({ id: value.id, generation: value.generation, digest: value.digest });
+/** A renewal renews exactly one projection: the same node scope and that projection's exact reference. */
+export const networkRenewsProjection = (renewal: IRuntimeNetworkDnsLeaseRenewal, projection: IRuntimeNetworkProjectionV1): boolean =>
+  networkSameScope(renewal, projection) && networkEqual(renewal.projection, networkReferenceOf(projection));
+/**
+ * The one rule for the DNS window a node may use under a projection: its admitted renewal's, else
+ * the projection's own. Both inputs are already validated caller state; this verifies no signature.
+ */
+export const networkEffectiveDnsWindow = (
+  projection: IRuntimeNetworkProjectionV1, renewal: IRuntimeNetworkDnsLeaseRenewal | null,
+): IRuntimeNetworkDnsWindow => {
+  if (renewal === null) return projection.dns;
+  requireNetwork(networkRenewsProjection(renewal, projection));
+  return renewal.dns;
+};
 export const networkRevision = (item: Record<string, unknown>) => {
   const id = networkId(item.id), generation = networkCounter(item.generation);
   const previous = item.previous === null ? null : networkReference(item.previous);
@@ -115,6 +149,20 @@ export const networkPrefixBounds = (value: string): [number, number] => {
   const [address, bits] = value.split('/'), first = networkIpv4Number(address);
   return [first, first + 2 ** (32 - Number(bits)) - 1];
 };
+/** A canonical IPv4 prefix: a dotted quad whose host bits are zero. */
+export const networkPrefix = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && value.length <= 18);
+  const parts = value.split('/');
+  requireNetwork(parts.length === 2 && /^(?:[0-9]|[12][0-9]|3[0-2])$/.test(parts[1]));
+  requireNetwork(networkIpv4Number(networkIpv4(parts[0])) % 2 ** (32 - Number(parts[1])) === 0);
+  return value;
+};
+/** A canonical prefix inside the RFC 1918 private ranges. */
+export const networkPrivatePrefix = (value: unknown): string => {
+  const prefix = networkPrefix(value);
+  requireNetwork(['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'].some(range => networkContains(range, prefix)));
+  return prefix;
+};
 export const networkContains = (outer: string, inner: string): boolean => {
   const [a, b] = networkPrefixBounds(outer), [c, d] = networkPrefixBounds(inner); return a <= c && b >= d;
 };

package/ts/private/producercontract.ts

@@ -0,0 +1,19 @@
+import { requireNetwork } from './networkcontract.js';
+
+/**
+ * The runtime producer records read decoded input with the network family's strict JSON readers,
+ * and every producer snapshot runs inside `producerSafe`: whichever rule refused, a caller sees
+ * this one rejection and learns nothing about which field failed.
+ */
+export const failProducer = (): never => { throw new Error('Runtime producer contract rejected.'); };
+export const producerSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failProducer(); } };
+
+/** Membership in a closed union whose members are listed once, as the array the union is derived from. */
+export const isOneOf = <T extends string>(members: readonly T[], value: unknown): value is T =>
+  (members as readonly unknown[]).includes(value);
+
+/** The tag of a captured tagged record, read before the record's exact keys are known. */
+export const variantOf = (value: unknown, tag: string): unknown => {
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  return (value as Record<string, unknown>)[tag];
+};

package/ts/private/runtimepolicy.ts

@@ -0,0 +1,105 @@
+import type { IRuntimeConfigLogPolicyV1 } from '../data/runtimeconfig.js';
+
+/**
+ * The execution policy a runtime config seals and a service runtime profile states ahead of it.
+ * Both validators apply these timing, HTTP request, CPU, memory, identity and log rules. Only the
+ * service's target ports decide whether a readiness target exists, which a profile cannot know.
+ *
+ * Every check here reads captured plain data only, the output of `snapshotBoundedJson` or
+ * `captureNetwork`: on live input a getter could pass a check and then hand the caller another value.
+ */
+export const runtimePolicyLimits = Object.freeze({
+  minimumMemoryBytes: 16 * 1024 * 1024,
+  maximumMemoryBytes: 2 ** 50,
+  maximumCpuMillis: 1_000_000,
+  maximumIdentityNumber: 2 ** 31 - 1,
+  maximumReadinessDurationMs: 3_600_000,
+  maximumLogRetentionMs: 31_536_000_000,
+} as const);
+
+export type TRuntimePolicyFailure = (messageArg: string) => never;
+
+export const isBoundedInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
+  && valueArg >= minimumArg && valueArg <= maximumArg;
+export const isRuntimePortName = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
+export const isExactRecord = (
+  valueArg: unknown, keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const keys = Object.keys(valueArg);
+  return keys.length === keysArg.length && keys.every((keyArg) => keysArg.includes(keyArg));
+};
+
+/** null explicitly requests no CPU quota; zero is never a quota. */
+export const isRuntimeCpuMillis = (valueArg: unknown): valueArg is number | null =>
+  valueArg === null || isBoundedInteger(valueArg, 1, runtimePolicyLimits.maximumCpuMillis);
+export const isRuntimeMemoryBytes = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, runtimePolicyLimits.minimumMemoryBytes, runtimePolicyLimits.maximumMemoryBytes);
+export const isRuntimeIdentityNumber = (valueArg: unknown): valueArg is number =>
+  isBoundedInteger(valueArg, 0, runtimePolicyLimits.maximumIdentityNumber);
+
+export const isRuntimeLogPolicy = (valueArg: unknown): valueArg is IRuntimeConfigLogPolicyV1 =>
+  isExactRecord(valueArg, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
+  && isBoundedInteger(valueArg.maximumLineBytes, 1, 1_048_576)
+  && isBoundedInteger(valueArg.maximumBufferedBytes, 1, 67_108_864)
+  && valueArg.maximumBufferedBytes >= valueArg.maximumLineBytes
+  && isBoundedInteger(valueArg.retentionMs, 1, runtimePolicyLimits.maximumLogRetentionMs);
+
+const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
+  'successThreshold', 'failureThreshold'] as const;
+
+/**
+ * Readiness policy. `selectsTcpTargetArg` decides whether a probe's named target and port exist:
+ * a config answers from its own target ports, a profile ahead of any config cannot know them.
+ */
+export const assertRuntimeReadiness = (
+  valueArg: unknown,
+  selectsTcpTargetArg: (targetPortArg: string, portArg: number) => boolean,
+  failArg: TRuntimePolicyFailure,
+): void => {
+  if (!valueArg || typeof valueArg !== 'object') failArg('runtime config readiness is required');
+  const value = valueArg as Record<string, unknown>;
+  const keys = value.kind === 'process' ? ['kind', ...timingKeys]
+    : value.kind === 'tcp' ? ['kind', ...timingKeys, 'targetPort', 'port']
+      : value.kind === 'http' ? ['kind', ...timingKeys, 'targetPort', 'port',
+        'scheme', 'host', 'path', 'expectedStatusCodes', 'followRedirects'] : [];
+  const maximumDurationMs = runtimePolicyLimits.maximumReadinessDurationMs;
+  if (keys.length === 0 || !isExactRecord(value, keys)
+    || !isBoundedInteger(value.initialDelayMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.startupGraceMs, 0, maximumDurationMs)
+    || !isBoundedInteger(value.intervalMs, 100, maximumDurationMs)
+    || !isBoundedInteger(value.timeoutMs, 1, 60_000)
+    || !isBoundedInteger(value.successThreshold, 1, 100)
+    || !isBoundedInteger(value.failureThreshold, 1, 100)
+    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
+    failArg('runtime config readiness must use explicit bounded timing and exact schema');
+  }
+  if (value.kind === 'process') return;
+  if (!isRuntimePortName(value.targetPort) || !isBoundedInteger(value.port, 1, 65535)
+    || !selectsTcpTargetArg(value.targetPort, value.port)) {
+    failArg('runtime config readiness must select a declared TCP target and port');
+  }
+  if (value.kind === 'tcp') return;
+  if ((value.scheme !== 'http' && value.scheme !== 'https') || value.followRedirects !== false
+    || typeof value.host !== 'string' || value.host.length > 253
+    || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/.test(value.host)
+    || typeof value.path !== 'string' || value.path.length > 4096
+    || !value.path.startsWith('/') || value.path.startsWith('//')
+    || /[^\x21-\x7e]|[\\#]/.test(value.path)
+    || /%(?![0-9A-F]{2})/.test(value.path)
+    || !Array.isArray(value.expectedStatusCodes) || value.expectedStatusCodes.length === 0
+    || value.expectedStatusCodes.length > 32) {
+    failArg('runtime config HTTP readiness must use an exact bounded request policy');
+  }
+  const parsed = new URL(value.path, 'http://runtime.invalid');
+  if (`${parsed.pathname}${parsed.search}` !== value.path) failArg('runtime config HTTP path must be canonical');
+  let previousCode = 0;
+  for (const code of value.expectedStatusCodes) {
+    if (!isBoundedInteger(code, 200, 599) || code <= previousCode) {
+      failArg('runtime config HTTP status expectations must be sorted unique final codes');
+    }
+    previousCode = code;
+  }
+};

package/ts/requests/cluster.ts

@@ -1,5 +1,8 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
+import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
+import type * as leaseInterfaces from '../data/networklease.js';
 import * as plugins from '../plugins.js';
 
 /**
@@ -146,6 +149,25 @@ export interface IReq_Relay_Cloudly_RegisterClusterRelayV1 extends plugins.typed
   response: clusterInterfaces.IClusterRelayRegistrationResponseV1;
 }
 
+/**
+ * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
+ *
+ * A cluster is outbound-only, so a node that loses Cloudly loses the only signer of its DNS
+ * window. The relay holds this run in memory, replacing whatever it held for that node, and
+ * releases from it only the renewal whose window is current (`notBefore <= now < expiresAt`), and
+ * only while it has no Cloudly session: a node refuses a window that is not current. It signs nothing and verifies
+ * nothing: each renewal is Cloudly's statement and the node verifies it against its own pinned
+ * authority.
+ */
+export interface IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals
+> {
+  method: 'holdRuntimeNetworkDnsLeaseRenewals';
+  request: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsRequest;
+  response: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsResponse;
+}
+
 /**
  * deletes a cluster
  */
@@ -162,3 +184,46 @@ export interface IReq_Any_Cloudly_DeleteClusterById extends plugins.typedrequest
     ok: boolean;
   };
 }
+
+/**
+ * A cluster's runtime phase, and what still blocks it from leaving `swarm`.
+ *
+ * Cloudly refuses a cluster without a phase record as `cluster-runtime-missing` rather than
+ * assuming one. `blockers` is empty once nothing blocks the cutover.
+ */
+export interface IReq_Any_Cloudly_GetClusterRuntime extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRuntime
+> {
+  method: 'getClusterRuntime';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+  };
+  response: {
+    runtime: IClusterRuntime;
+    blockers: TClusterRuntimeBlocker[];
+  };
+}
+
+/**
+ * Every current runtime assignment on one cluster's nodes, a page at a time: a cluster carries
+ * every node's slots of every service, which no single response bounds. `limit` runs from 1 to
+ * `serviceRuntimeContract.maximumAssignmentPageSize`; Cloudly refuses any other.
+ */
+export interface IReq_Any_Cloudly_GetClusterRuntimeAssignments extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetClusterRuntimeAssignments
+> {
+  method: 'getClusterRuntimeAssignments';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+    cursor: string | null;
+    limit: number;
+  };
+  response: {
+    assignments: IServiceRuntimeAssignmentView[];
+    nextCursor: string | null;
+  };
+}