@serve.zone/interfaces 31.8.0 → 31.9.0

package/ts/data/networkaddressplan.ts

@@ -0,0 +1,175 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import { computeRuntimeNetworkProtectedAuthorityV1Digest, snapshotRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import type { IGetRuntimeManagedVpnCredentialResponseV1 } from './networkcredential.js';
+import { captureNetwork, failNetwork, networkContains, networkCounter, networkEqual, networkId, networkIpv4, networkOverlaps,
+  networkPrefixBounds, networkPrivatePrefix, networkRecord, networkSafe, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * The address space an administrator gives the runtime network, and the one input the protected
+ * authority is composed from. Cloudly keeps a single plan; pools and prefixes only grow, and the
+ * managed VPN never changes once set.
+ */
+export interface IRuntimeNetworkAddressPlan {
+  id: 'address-plan';
+  /** Compare-and-swap counter; every accepted change advances it by one. */
+  revision: number;
+  /** Every protected prefix: they cover the pools, resolvers, platform endpoints and the VPN. */
+  prefixes: string[];
+  pools: IRuntimeNetworkProtectedAuthorityV1['pools'];
+  resolvers: IRuntimeNetworkProtectedAuthorityV1['resolvers'];
+  /** Without the VPN relay, which the composed authority adds as a UDP platform endpoint. */
+  platformEndpoints: IRuntimeNetworkProtectedAuthorityV1['platformEndpoints'];
+  vpn: {
+    /** The private prefix VPN control addresses are allocated from. */
+    controlPrefix: string;
+    /** The endpoint every node dials for the managed VPN. */
+    relay: IGetRuntimeManagedVpnCredentialResponseV1['relay'];
+  };
+}
+
+/** What an administrator writes; Cloudly supplies the id and the revision. */
+export type TRuntimeNetworkAddressPlanWritableData = Omit<IRuntimeNetworkAddressPlan, 'id' | 'revision'>;
+
+/** What a protection producer fixes around a plan: the authority's identity, revision chain and egress. */
+export type TRuntimeNetworkProtectedAuthorityFrame = Pick<IRuntimeNetworkProtectedAuthorityV1,
+  'id' | 'generation' | 'controller' | 'previous' | 'egressAuthorities'>;
+
+/** Refusals the pure change check decides from the two plans alone. */
+export type TRuntimeNetworkAddressPlanChangeRefusal = 'plan-vpn-immutable' | 'plan-pool-removed' | 'plan-prefix-shrunk';
+
+/**
+ * Every refusal of a plan write. Cloudly adds the two that need live references: a resolver or
+ * platform endpoint the change removes or changes while a router selection or a service still names it.
+ */
+export type TRuntimeNetworkAddressPlanRefusal =
+  | TRuntimeNetworkAddressPlanChangeRefusal | 'plan-resolver-referenced' | 'plan-endpoint-referenced';
+
+export type TRuntimeNetworkAddressPlanChange =
+  | { status: 'unchanged' }
+  /** The ids the change removes or changes, which Cloudly checks against live references before it writes. */
+  | { status: 'accepted'; removed: { resolverIds: string[]; platformEndpointIds: string[] } }
+  | { status: 'refused'; reason: TRuntimeNetworkAddressPlanChangeRefusal };
+
+export const runtimeNetworkAddressPlanContract = Object.freeze({
+  id: 'address-plan',
+  /**
+   * SmartVPN needs its gateway and at least one member inside the control prefix. No minimum length
+   * is stated: the private-range rule already keeps the control prefix at /8 or longer.
+   */
+  maximumControlPrefixLength: 30,
+  relayProtocol: 'udp',
+} as const);
+
+/**
+ * The structural authority validator reads a frame's shape and nothing else, and a plan fixes none of
+ * the frame, so every valid frame decides a plan the same way. The digest is a well-formed
+ * placeholder: this candidate is never hashed or stored.
+ */
+const validationFrame: TRuntimeNetworkProtectedAuthorityFrame = {
+  id: 'address-plan', generation: 1, controller: { kind: 'cloudly', id: 'address-plan', epoch: 'address-plan' },
+  previous: null, egressAuthorities: [{ nodeId: 'address-plan', runtimeNamespace: 'address-plan' }],
+};
+const unsealedDigest = `sha256:${'0'.repeat(64)}` as TSha256Digest;
+
+type TAuthoritySets = Pick<IRuntimeNetworkProtectedAuthorityV1, 'prefixes' | 'pools' | 'resolvers' | 'platformEndpoints'>;
+
+/** Unvalidated sets and frame in, the protected authority validator's verdict out. */
+const authorityOf = (
+  sets: Record<keyof TAuthoritySets, unknown>, frame: Record<keyof TRuntimeNetworkProtectedAuthorityFrame, unknown>,
+): IRuntimeNetworkProtectedAuthorityV1 => snapshotRuntimeNetworkProtectedAuthorityV1({ schemaVersion: 1, id: frame.id,
+  generation: frame.generation, controller: frame.controller, previous: frame.previous, egressAuthorities: frame.egressAuthorities,
+  prefixes: sets.prefixes, pools: sets.pools, resolvers: sets.resolvers, platformEndpoints: sets.platformEndpoints, digest: unsealedDigest });
+
+const setsWithRelay = (plan: IRuntimeNetworkAddressPlan): TAuthoritySets => ({
+  prefixes: plan.prefixes, pools: plan.pools, resolvers: plan.resolvers,
+  platformEndpoints: [...plan.platformEndpoints, { ...plan.vpn.relay, protocol: runtimeNetworkAddressPlanContract.relayProtocol }]
+    .sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0),
+});
+
+const vpnOf = (value: unknown): IRuntimeNetworkAddressPlan['vpn'] => {
+  const item = networkRecord(value, ['controlPrefix', 'relay']);
+  const relay = networkRecord(item.relay, ['id', 'address', 'port']);
+  const controlPrefix = networkPrivatePrefix(item.controlPrefix);
+  requireNetwork(Number(controlPrefix.split('/')[1]) <= runtimeNetworkAddressPlanContract.maximumControlPrefixLength);
+  return { controlPrefix, relay: { id: networkId(relay.id), address: networkIpv4(relay.address), port: networkCounter(relay.port, 65535) } };
+};
+
+/** The control prefix is protected, and no pool, resolver or platform endpoint, the relay included, sits inside it. */
+const requireVpnProtected = (authority: IRuntimeNetworkProtectedAuthorityV1, controlPrefix: string): void => {
+  requireNetwork(authority.prefixes.some(prefix => networkContains(prefix, controlPrefix))
+    && authority.pools.every(pool => !networkOverlaps(pool.prefix, controlPrefix))
+    && [...authority.resolvers, ...authority.platformEndpoints].every(endpoint => !networkContains(controlPrefix, `${endpoint.address}/32`)));
+};
+
+/**
+ * Structural snapshot for exact persistence and for a plan write. A plan passes only when both
+ * authorities it can describe pass the protected authority's own validator: its sets alone, and
+ * its sets with the relay added, so no plan can compose an authority that contract refuses.
+ */
+export const snapshotRuntimeNetworkAddressPlan = (value: unknown): IRuntimeNetworkAddressPlan => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'revision', 'prefixes', 'pools', 'resolvers', 'platformEndpoints', 'vpn']);
+  requireNetwork(item.id === runtimeNetworkAddressPlanContract.id);
+  const own = authorityOf({ prefixes: item.prefixes, pools: item.pools, resolvers: item.resolvers,
+    platformEndpoints: item.platformEndpoints }, validationFrame);
+  const plan: IRuntimeNetworkAddressPlan = { id: runtimeNetworkAddressPlanContract.id, revision: networkCounter(item.revision),
+    prefixes: own.prefixes, pools: own.pools, resolvers: own.resolvers, platformEndpoints: own.platformEndpoints, vpn: vpnOf(item.vpn) };
+  requireVpnProtected(authorityOf(setsWithRelay(plan), validationFrame), plan.vpn.controlPrefix);
+  return plan;
+});
+
+/**
+ * The protected authority a plan describes inside a producer's frame, digest included: the plan's
+ * sets with the VPN relay as the UDP platform endpoint every node dials. Both inputs are read before
+ * the digest is computed.
+ */
+export const composeRuntimeNetworkProtectedAuthority = async (
+  planValue: unknown, frameValue: unknown,
+): Promise<IRuntimeNetworkProtectedAuthorityV1> => {
+  try {
+    const plan = snapshotRuntimeNetworkAddressPlan(planValue);
+    const frame = networkRecord(captureNetwork(frameValue), ['id', 'generation', 'controller', 'previous', 'egressAuthorities']);
+    const authority = authorityOf(setsWithRelay(plan), frame);
+    return { ...authority, digest: await computeRuntimeNetworkProtectedAuthorityV1Digest(authority) };
+  } catch { return failNetwork(); }
+};
+
+/** Whether the union of `prefixes`, which never overlap one another, covers every address of `prefix`. */
+const coveredBy = (prefixes: string[], prefix: string): boolean => {
+  const [first, last] = networkPrefixBounds(prefix);
+  const covered = prefixes.reduce((sum, candidate) => {
+    const [low, high] = networkPrefixBounds(candidate);
+    return sum + Math.max(0, Math.min(last, high) - Math.max(first, low) + 1);
+  }, 0);
+  return covered === last - first + 1;
+};
+
+/**
+ * The entries of `previous` that `next` does not hold exactly as they were. An entry changed under its
+ * old id counts: whatever still names that id would now reach something else.
+ */
+const removedOrChanged = <T>(previous: T[], next: T[]): T[] =>
+  previous.filter(item => !next.some(candidate => networkEqual(candidate, item)));
+
+const idsOf = (entries: Array<{ id: string }>): string[] => entries.map(entry => entry.id);
+
+/**
+ * The pure decision for replacing `previousValue`, the stored plan or null, with `nextValue` at the
+ * following revision. Leases and the managed VPN outlive a plan revision, so every pool stays exactly
+ * as it was, the protected address space only grows, and the VPN never changes. Resolvers and platform
+ * endpoints may go or change; `accepted` names every one that did. Equal content is `unchanged`:
+ * Cloudly writes nothing and the stored revision stands.
+ */
+export const admitRuntimeNetworkAddressPlanChange = (previousValue: unknown | null, nextValue: unknown): TRuntimeNetworkAddressPlanChange =>
+  networkSafe(() => {
+    const previous = previousValue === null ? null : snapshotRuntimeNetworkAddressPlan(previousValue);
+    const next = snapshotRuntimeNetworkAddressPlan(nextValue);
+    requireNetwork(next.revision === (previous?.revision ?? 0) + 1);
+    if (previous === null) return { status: 'accepted', removed: { resolverIds: [], platformEndpointIds: [] } };
+    if (networkEqual({ ...previous, revision: next.revision }, next)) return { status: 'unchanged' };
+    if (!networkEqual(previous.vpn, next.vpn)) return { status: 'refused', reason: 'plan-vpn-immutable' };
+    if (removedOrChanged(previous.pools, next.pools).length > 0) return { status: 'refused', reason: 'plan-pool-removed' };
+    if (!previous.prefixes.every(prefix => coveredBy(next.prefixes, prefix))) return { status: 'refused', reason: 'plan-prefix-shrunk' };
+    return { status: 'accepted', removed: { resolverIds: idsOf(removedOrChanged(previous.resolvers, next.resolvers)),
+      platformEndpointIds: idsOf(removedOrChanged(previous.platformEndpoints, next.platformEndpoints)) } };
+  });

package/ts/data/networkauthority.ts

@@ -1,6 +1,7 @@
 import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './runtimeassignment.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+import { networkPrefix, networkPrivatePrefix } from '../private/networkcontract.js';
 
 /** Controller declaration; a digest does not authenticate completeness or activate a pool. */
 export interface IRuntimeNetworkProtectedAuthorityV1 {
@@ -129,14 +130,6 @@ const endpointAddress = (value: unknown): string => {
   requireValue(first > 0 && first < 224 && first !== 127);
   return result;
 };
-const prefix = (value: unknown): string => {
-  requireValue(typeof value === 'string' && value.length <= 18);
-  const parts = value.split('/');
-  requireValue(parts.length === 2 && /^(?:[0-9]|[12][0-9]|3[0-2])$/.test(parts[1]));
-  const base = numericAddress(address(parts[0])), width = 2 ** (32 - Number(parts[1]));
-  requireValue(base % width === 0);
-  return value;
-};
 const bounds = (value: string): [number, number] => {
   const [base, bits] = value.split('/'), first = numericAddress(base);
   return [first, first + 2 ** (32 - Number(bits)) - 1];
@@ -149,11 +142,6 @@ const overlaps = (left: string, right: string): boolean => {
   const [a, b] = bounds(left), [c, d] = bounds(right);
   return a <= d && c <= b;
 };
-const privatePrefix = (value: unknown): string => {
-  const result = prefix(value);
-  requireValue(['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'].some(range => contains(range, result)));
-  return result;
-};
 const nonoverlapping = (values: string[]): void => {
   for (let index = 0; index < values.length; index++) for (let other = 0; other < index; other++) {
     requireValue(!overlaps(values[index], values[other]));
@@ -170,7 +158,7 @@ export const snapshotRuntimeNetworkProtectedAuthorityV1 = (value: unknown): IRun
   const identity = id(item.id), generation = integer(item.generation);
   const previous = item.previous === null ? null : reference(item.previous);
   requireValue(generation === 1 ? previous === null : previous?.id === identity && previous.generation === generation - 1);
-  const prefixes = sorted(list(item.prefixes, runtimeNetworkAuthorityV1Contract.maximumPrefixes, prefix), value => value);
+  const prefixes = sorted(list(item.prefixes, runtimeNetworkAuthorityV1Contract.maximumPrefixes, networkPrefix), value => value);
   requireValue(prefixes.length > 0);
   nonoverlapping(prefixes);
   const protectedPrefix = (value: string) => requireValue(prefixes.some(range => contains(range, value)));
@@ -178,7 +166,7 @@ export const snapshotRuntimeNetworkProtectedAuthorityV1 = (value: unknown): IRun
     const pool = record(value, ['id', 'purpose', 'prefix']);
     requireValue(pool.purpose === 'workload' || pool.purpose === 'transit');
     const result: IRuntimeNetworkProtectedAuthorityV1['pools'][number] = {
-      id: id(pool.id), purpose: pool.purpose, prefix: privatePrefix(pool.prefix),
+      id: id(pool.id), purpose: pool.purpose, prefix: networkPrivatePrefix(pool.prefix),
     };
     protectedPrefix(result.prefix);
     return result;
@@ -212,7 +200,7 @@ export const snapshotRuntimeNetworkHandoffLeaseV1 = (value: unknown): IRuntimeNe
     'protectedAuthority', 'routerIncarnationId', 'transit', 'sourcePortRanges', 'conntrackZone', 'conntrackLabel', 'digest']);
   requireValue(item.schemaVersion === 1);
   const transit = record(item.transit, ['poolId', 'prefix', 'routerAddress', 'hostAddress']);
-  const transitPrefix = privatePrefix(transit.prefix), [first, last] = bounds(transitPrefix);
+  const transitPrefix = networkPrivatePrefix(transit.prefix), [first, last] = bounds(transitPrefix);
   const routerAddress = endpointAddress(transit.routerAddress), hostAddress = endpointAddress(transit.hostAddress);
   requireValue(first !== last && routerAddress !== hostAddress);
   for (const value of [routerAddress, hostAddress]) {

package/ts/data/networknode.ts

@@ -0,0 +1,37 @@
+import type { IRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import { captureNetwork, networkCounter, networkId, networkRecord, networkSafe } from '../private/networkcontract.js';
+
+type TEgressOwner = IRuntimeNetworkProtectedAuthorityV1['egressAuthorities'][number];
+
+/**
+ * One unmet condition of a node's runtime network readiness, in the order the node producer meets
+ * them: the node joins the protected authority's egress, every egress owner reports current
+ * protection, a handoff is reserved, the router selection carries it, the node's acknowledged
+ * projection carries it, and the node is a managed VPN member. `protection-receipts-pending` names
+ * the egress owners whose current receipts are still missing.
+ */
+export type TRuntimeNetworkNodeReadinessGap =
+  | { condition: 'egress-pending' | 'handoff-pending' | 'selection-pending' | 'projection-pending' | 'vpn-member-pending' }
+  | { condition: 'protection-receipts-pending'; owners: [TEgressOwner, ...TEgressOwner[]] };
+
+/** A node is ready exactly when nothing is missing. */
+export type IRuntimeNetworkNodeReadiness = { nodeId: string } & (
+  | { ready: true; missing: [] }
+  | { ready: false; missing: [TRuntimeNetworkNodeReadinessGap, ...TRuntimeNetworkNodeReadinessGap[]] }
+);
+
+/**
+ * The router incarnation of one node. A handoff's id and router incarnation id derive from it, so
+ * advancing it is the only way to give a node's router a fresh handoff.
+ */
+export interface IRuntimeRouterIncarnation {
+  /** The node id. */
+  id: string;
+  /** Starts at 1 with the node's first handoff; every reincarnation advances it by one. */
+  incarnation: number;
+}
+
+export const snapshotRuntimeRouterIncarnation = (value: unknown): IRuntimeRouterIncarnation => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'incarnation']);
+  return { id: networkId(item.id), incarnation: networkCounter(item.incarnation) };
+});

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 };
+});