@serve.zone/interfaces 31.8.0 → 31.9.0

package/dist_ts/private/runtimepolicy.js

@@ -0,0 +1,90 @@
+/**
+ * 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,
+});
+export const isBoundedInteger = (valueArg, minimumArg, maximumArg) => typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
+    && valueArg >= minimumArg && valueArg <= maximumArg;
+export const isRuntimePortName = (valueArg) => typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
+export const isExactRecord = (valueArg, keysArg) => {
+    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) => valueArg === null || isBoundedInteger(valueArg, 1, runtimePolicyLimits.maximumCpuMillis);
+export const isRuntimeMemoryBytes = (valueArg) => isBoundedInteger(valueArg, runtimePolicyLimits.minimumMemoryBytes, runtimePolicyLimits.maximumMemoryBytes);
+export const isRuntimeIdentityNumber = (valueArg) => isBoundedInteger(valueArg, 0, runtimePolicyLimits.maximumIdentityNumber);
+export const isRuntimeLogPolicy = (valueArg) => 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'];
+/**
+ * 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, selectsTcpTargetArg, failArg) => {
+    if (!valueArg || typeof valueArg !== 'object')
+        failArg('runtime config readiness is required');
+    const value = valueArg;
+    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;
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZXBvbGljeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3ByaXZhdGUvcnVudGltZXBvbGljeS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFFQTs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sbUJBQW1CLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUMvQyxrQkFBa0IsRUFBRSxFQUFFLEdBQUcsSUFBSSxHQUFHLElBQUk7SUFDcEMsa0JBQWtCLEVBQUUsQ0FBQyxJQUFJLEVBQUU7SUFDM0IsZ0JBQWdCLEVBQUUsU0FBUztJQUMzQixxQkFBcUIsRUFBRSxDQUFDLElBQUksRUFBRSxHQUFHLENBQUM7SUFDbEMsMEJBQTBCLEVBQUUsU0FBUztJQUNyQyxxQkFBcUIsRUFBRSxjQUFjO0NBQzdCLENBQUMsQ0FBQztBQUlaLE1BQU0sQ0FBQyxNQUFNLGdCQUFnQixHQUFHLENBQUMsUUFBaUIsRUFBRSxVQUFrQixFQUFFLFVBQWtCLEVBQXNCLEVBQUUsQ0FDaEgsT0FBTyxRQUFRLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDLFFBQVEsRUFBRSxDQUFDLENBQUMsQ0FBQztPQUN2RixRQUFRLElBQUksVUFBVSxJQUFJLFFBQVEsSUFBSSxVQUFVLENBQUM7QUFDdEQsTUFBTSxDQUFDLE1BQU0saUJBQWlCLEdBQUcsQ0FBQyxRQUFpQixFQUFzQixFQUFFLENBQ3pFLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSw2QkFBNkIsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDL0UsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLENBQzNCLFFBQWlCLEVBQUUsT0FBMEIsRUFDUixFQUFFO0lBQ3ZDLElBQUksQ0FBQyxRQUFRLElBQUksT0FBTyxRQUFRLEtBQUssUUFBUSxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsUUFBUSxD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

package/dist_ts/requests/cluster.d.ts

@@ -1,5 +1,7 @@
 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';
 /**
@@ -141,3 +143,38 @@ 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;
+    };
+}

package/dist_ts/requests/cluster.js

@@ -1,4 +1,4 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
 import * as plugins from '../plugins.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL2NsdXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLGNBQWMsTUFBTSxpQkFBaUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssaUJBQWlCLE1BQU0sb0JBQW9CLENBQUM7QUFFeEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL2NsdXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLGNBQWMsTUFBTSxpQkFBaUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssaUJBQWlCLE1BQU0sb0JBQW9CLENBQUM7QUFJeEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/dist_ts/requests/network.d.ts

@@ -1,5 +1,7 @@
 import * as plugins from '../plugins.js';
-import type { IIdentityCredential } from '../data/user.js';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
+import type { IRuntimeNetworkAddressPlan, TRuntimeNetworkAddressPlanWritableData } from '../data/networkaddressplan.js';
+import type { IRuntimeNetworkNodeReadiness, IRuntimeRouterIncarnation } from '../data/networknode.js';
 import type { IPrivateNetworkV1, IServicePrivateNetworksV1, ISetServicePrivateNetworksV1, TPrivateNetworkMutationV1 } from '../data/privatenetwork.js';
 import type { IServicePublishedPortsV1, ISetServicePublishedPortsV1 } from '../data/networkprojection.js';
 /** Current organization picker data. Entries are never cached authorization grants. */
@@ -130,3 +132,57 @@ export interface IRequest_Any_Cloudly_GetNetworkNodes {
         networkNodes: plugins.tsclass.network.INetworkNode[];
     };
 }
+/**
+ * Writes the runtime network's address plan.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when no plan exists yet. Cloudly
+ * validates the plan with `snapshotRuntimeNetworkAddressPlan`, decides the change with
+ * `admitRuntimeNetworkAddressPlanChange`, refuses the change while a resolver or platform endpoint
+ * it removes or changes is still referenced, and answers with the stored plan: at its new revision,
+ * or unchanged.
+ */
+export interface IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan> {
+    method: 'setRuntimeNetworkAddressPlan';
+    request: {
+        identity: IIdentity;
+        expectedRevision: number | null;
+        plan: TRuntimeNetworkAddressPlanWritableData;
+    };
+    response: {
+        plan: IRuntimeNetworkAddressPlan;
+    };
+}
+/** `null` until an administrator sets the first plan; the runtime network stays unconfigured until then. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan> {
+    method: 'getRuntimeNetworkAddressPlan';
+    request: {
+        identity: IIdentity;
+    };
+    response: {
+        plan: IRuntimeNetworkAddressPlan | null;
+    };
+}
+/** Whether one node's runtime network is ready for workloads, and every condition still missing. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness> {
+    method: 'getRuntimeNetworkNodeReadiness';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+    };
+    response: IRuntimeNetworkNodeReadiness;
+}
+/**
+ * Advances one node's router incarnation, so the node producer reserves the router a fresh handoff.
+ * `expectedIncarnation` is the incarnation the caller read; any other refuses the request.
+ */
+export interface IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter> {
+    method: 'reincarnateRuntimeNetworkRouter';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        expectedIncarnation: number;
+    };
+    response: {
+        incarnation: IRuntimeRouterIncarnation;
+    };
+}

package/dist_ts/requests/service.d.ts

@@ -8,6 +8,7 @@ import type { IImageRelease } from '../data/immutableimage.js';
 import type { IDeploymentPreflightReport, IDeploymentPreflightRequestData } from '../data/deploymentpreflight.js';
 import type { IDeploymentReservationInput, IServiceDeploymentOperation, IServiceDeploymentStatus } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type { IServiceRuntimeAssignmentView, IServiceRuntimeSpec, IServiceRuntimeStatus, TServiceRuntimeSpecWritableData } from '../data/serviceruntime.js';
 import type { IServiceDeploymentAdoptionInput, IServiceDeploymentAdoptionImagePromotionInput, IServiceDeploymentAdoptionImagePromotionResult, IServiceDeploymentAdoptionRolloutInput, IServiceDeploymentAdoptionRolloutResult, IServiceDeploymentAdoptionPreflightInput, IServiceDeploymentAdoptionReport, IServiceDeploymentAdoptionResult } from '../data/deploymentadoption.js';
 export interface IRequest_Any_Cloudly_BootstrapServiceDeploymentAdoptionRollout extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_BootstrapServiceDeploymentAdoptionRollout> {
     method: 'bootstrapServiceDeploymentAdoptionRollout';
@@ -253,3 +254,62 @@ export interface IRequest_Any_Cloudly_DeleteServiceById extends plugins.typedreq
         success: boolean;
     };
 }
+/**
+ * Writes the complete runtime spec of one service.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when the service has never had a
+ * spec; any other stored revision refuses the write. Cloudly copies the organization from the
+ * service and answers with the stored spec at its new revision.
+ */
+export interface IRequest_Any_Cloudly_SetServiceRuntimeSpec extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_SetServiceRuntimeSpec> {
+    method: 'setServiceRuntimeSpec';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        expectedRevision: number | null;
+        spec: TServiceRuntimeSpecWritableData;
+    };
+    response: {
+        spec: IServiceRuntimeSpec;
+    };
+}
+/**
+ * A service's runtime spec and the producer's verdict on it. Both are `null` before the first spec;
+ * a spec's status is `null` until the producer first decides it.
+ */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeSpec extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceRuntimeSpec> {
+    method: 'getServiceRuntimeSpec';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+    };
+    response: {
+        spec: null;
+        status: null;
+    } | {
+        spec: IServiceRuntimeSpec;
+        status: IServiceRuntimeStatus | null;
+    };
+}
+/** Every current runtime assignment of one service, one per replica slot. */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeAssignments extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceRuntimeAssignments> {
+    method: 'getServiceRuntimeAssignments';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+    };
+    response: {
+        assignments: IServiceRuntimeAssignmentView[];
+    };
+}
+/**
+ * Cloudly -> admin UIs: a service's runtime spec, status or assignments changed. It carries no
+ * state, so a late or repeated push can never overwrite a newer read; the UI reads the views again.
+ */
+export interface IReq_Cloudly_Any_PushServiceRuntimeChanged extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Any_PushServiceRuntimeChanged> {
+    method: 'pushServiceRuntimeChanged';
+    request: {
+        serviceId: string;
+    };
+    response: Record<string, never>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "31.8.0",
+  "version": "31.9.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -594,6 +594,62 @@ const { renewal: admittedRenewal } = await data.admitRuntimeNetworkDnsLeaseRenew
 const window = await data.getRuntimeNetworkEffectiveDnsWindow(admittedProjection, admittedRenewal);
 ```
 
+### Runtime Network Address Plan
+
+`data.IRuntimeNetworkAddressPlan` is the address space an administrator gives the runtime network,
+and the single input Cloudly composes the protected authority from:
+`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, relay } }`.
+Pools, resolvers and platform endpoints use the protected authority's own element shapes, and the
+relay uses the managed-VPN credential's `{ id, address, port }`. `platformEndpoints` never lists the
+relay: the composed authority adds it, in id order, as the UDP platform endpoint every node dials.
+
+`snapshotRuntimeNetworkAddressPlan` refuses any plan that could describe an authority the authority
+contract refuses. It runs `snapshotRuntimeNetworkProtectedAuthorityV1` twice, once over the plan's
+own sets and once with the relay added, so overlapping pools, more than 16 resolvers, a resolver or
+endpoint outside `prefixes` or inside a pool, and a relay that `prefixes` do not cover are all
+refused by that one validator. On top it requires the VPN `controlPrefix` to be a private prefix no
+longer than /30 (`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`) inside `prefixes`
+that overlaps no pool and holds no resolver or platform endpoint, the relay included. No minimum
+length is stated: the private-range rule already keeps it at /8 or longer.
+`composeRuntimeNetworkProtectedAuthority(plan, frame)` is the composition itself: the producer
+supplies the frame (`TRuntimeNetworkProtectedAuthorityFrame`: authority id, generation, controller,
+previous reference and egress authorities) and receives the complete authority with its digest, so
+the validator and the protection producer can never compose differently.
+
+`admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
+the following revision; any other revision is a contract violation. Leases and the managed VPN
+outlive a plan revision, so it answers:
+
+- `unchanged` when the content equals the stored plan; Cloudly writes nothing;
+- `refused` with `plan-vpn-immutable` when the VPN differs, `plan-pool-removed` when any pool is gone
+  or changed its purpose or prefix, and `plan-prefix-shrunk` when the new prefixes, however split,
+  no longer cover every address the old ones did;
+- `accepted` with the ids of the resolvers and platform endpoints the change removes or changes. An
+  entry that keeps its id but differs in any field counts, so moving it goes through the same
+  reference check as removing it.
+
+`TRuntimeNetworkAddressPlanRefusal` adds `plan-resolver-referenced` and `plan-endpoint-referenced`,
+which only Cloudly can decide against live references, so every plan refusal has one type.
+`requests.network` carries `setRuntimeNetworkAddressPlan { identity, expectedRevision, plan }`
+(`expectedRevision: null` when no plan exists yet) and `getRuntimeNetworkAddressPlan`, which answers
+`null` until the first plan is set.
+
+### Node Network Readiness
+
+`requests.network.getRuntimeNetworkNodeReadiness { identity, nodeId }` answers
+`data.IRuntimeNetworkNodeReadiness`: `ready: true` with nothing missing, or `ready: false` with at
+least one `TRuntimeNetworkNodeReadinessGap`. The gaps follow the node producer's order: the node
+joins the protected authority's egress (`egress-pending`), every egress owner reports current
+protection (`protection-receipts-pending`, naming those `owners`, at least one), a handoff is reserved
+(`handoff-pending`), the router selection carries it (`selection-pending`), the node's acknowledged
+projection carries it (`projection-pending`), and the node is a managed VPN member
+(`vpn-member-pending`).
+
+`data.IRuntimeRouterIncarnation { id, incarnation }` is a node's router incarnation, from which its
+handoff and router incarnation ids derive; `snapshotRuntimeRouterIncarnation` checks the record.
+`reincarnateRuntimeNetworkRouter { identity, nodeId, expectedIncarnation }` advances it, so the node
+producer reserves the router a fresh handoff, and answers with the new incarnation.
+
 ### Node-Bound Runtime Assignments
 
 The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,
@@ -727,6 +783,70 @@ only the named Pallet attempt. They do not authorize storage relocation, prove
 whole-host or Docker/Coreflow absence, grant another controller or organization
 authority, or replace independently qualified readiness and routing evidence.
 
+### Cluster Runtime Phase
+
+`data.IClusterRuntime { id, phase, generation, changedAt, changedBy }` records which runtime owns a
+cluster's workloads: `TClusterRuntimePhase` is `swarm`, `draining`, `switching` or `pallet`. It is
+stored beside the cluster document, because a cluster update merges caller data and no caller may
+move a phase with it; `generation` is its compare-and-swap counter. `snapshotClusterRuntime` checks
+the record. Which phase may follow which belongs to the cutover, whose requests ship with it.
+
+`requests.cluster.getClusterRuntime { identity, clusterId }` answers `{ runtime, blockers }`. Each
+`TClusterRuntimeBlocker` names what it is about: cluster-wide blockers (`relay-not-enabled`,
+`relay-not-registered`, `address-plan-missing`, `vpn-unconfigured`) name nothing, node blockers
+(`node-without-pallet-credential`, `node-arch-unsupported`) name the `nodeId`, and service blockers
+(`service-multi-cluster-scope`, `service-authority-unsupported`, `platform-binding-present`) name
+the `serviceId`.
+
+### Service Runtime Specs And Status
+
+`data.IServiceRuntimeSpec` is what Cloudly runs for one service on a Pallet cluster:
+`{ id, organizationId, clusterId, placement, replicasPerNode, hold, profile, network, revision }`.
+It is stored complete and beside the service document, so a hold written by a cutover never races
+an operator's service edit.
+
+- `placement` is `{ kind: 'every-node' }` or `{ kind: 'nodes', nodeIds }`, with `nodeIds` sorted,
+  unique, never empty and at most `maximumPinnedNodes`, the protected authority's egress limit.
+- `replicasPerNode` runs from 1 to 64; Cloudly refuses a service desiring more than `maximumReplicas` (64) as `replica-limit`.
+- `profile { cpuMillis, memoryBytes, readiness, logs, readonlyRootfs, runAs }` is the runtime config's
+  execution policy ahead of any image: the same readiness and log shapes, and the same CPU, memory
+  (at least 16 MiB), identity, log, readiness timing and HTTP request rules, which both validators
+  share. `runAs: null` runs the image's own OCI user. Only the service's target ports decide whether
+  a readiness probe's target exists: the runtime config requires the service to declare it, and the
+  producer refuses a service that does not as `readiness-target-undeclared`.
+- `network` is `{ mode: 'isolated' }` or `{ mode: 'attached', publicEgress, platformEndpointIds }`
+  with sorted unique endpoint ids.
+
+`snapshotServiceRuntimeSpec` checks all of that; whether the cluster, the nodes and the endpoints
+exist is Cloudly's. `requests.service.setServiceRuntimeSpec { identity, serviceId, expectedRevision, spec }`
+writes `TServiceRuntimeSpecWritableData`, and Cloudly copies the organization from the service.
+`getServiceRuntimeSpec` answers `{ spec, status }`: both `null` before the first spec, and `status`
+`null` until the producer first decides the spec. A status never comes without its spec.
+
+`data.IServiceRuntimeStatus { id, specRevision, state, reason, changedAt }` is the producer's verdict
+on one spec revision, and each reason belongs to exactly one state. `converged` and `converging`
+carry `reason: null`. `waiting` carries a `TServiceRuntimeWaitingReason`: `node-network-pending`,
+`conflict` or `failure-backoff`. `refused` carries a `TServiceRuntimeRefusal`:
+`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` or `replica-limit`. A
+refusal never retires running slots. `snapshotServiceRuntimeStatus` enforces the pairing.
+
+### Runtime Assignment Views
+
+`data.IServiceRuntimeAssignmentView` is one replica slot's current assignment as an administrator
+reads it: `serviceId`, `replicaId`, `nodeId`, the current `assignment` reference, its `disposition`,
+the latest accepted `observation { phase, ready, observedAt, sequence }` (which may cite an earlier
+revision), `terminalReceiptCount` (0 to 2) and `delivery`. `delivered` means the node's own evidence,
+an observation or a terminal receipt, cites the current revision; until then it is `undelivered`.
+
+`requests.service.getServiceRuntimeAssignments { identity, serviceId }` answers every slot of one
+service. `requests.cluster.getClusterRuntimeAssignments { identity, clusterId, cursor, limit }` pages
+through every slot on a cluster's nodes; `limit` runs from 1 to
+`serviceRuntimeContract.maximumAssignmentPageSize` (256), and Cloudly refuses any other.
+`requests.service.pushServiceRuntimeChanged { serviceId }` tells admin UIs that a service's spec,
+status or assignments changed; it carries no state, so a late push never overwrites a newer read.
+
 ### Offline Database Settlement And Packaging
 
 The Node-only `@serve.zone/interfaces/runtime` export includes isolated V1

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '31.8.0',
+  version: '31.9.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusterruntime.ts

@@ -0,0 +1,45 @@
+import { captureNetwork, networkCounter, networkId, networkRecord, requireNetwork } from '../private/networkcontract.js';
+import { isOneOf, producerSafe } from '../private/producercontract.js';
+
+const clusterRuntimePhases = ['swarm', 'draining', 'switching', 'pallet'] as const;
+
+/**
+ * Which runtime owns a cluster's workloads.
+ *
+ * `swarm` is Coreflow's; `draining` stops every service while its volumes stay; `switching` lets the
+ * cluster's nodes join the runtime network while nothing runs; `pallet` is Pallet's alone.
+ */
+export type TClusterRuntimePhase = typeof clusterRuntimePhases[number];
+
+/**
+ * The runtime phase of one cluster, stored beside the cluster document rather than inside it: a
+ * cluster update merges caller data, and no caller may move a phase with it.
+ */
+export interface IClusterRuntime {
+  /** The cluster id. */
+  id: string;
+  phase: TClusterRuntimePhase;
+  /** Compare-and-swap counter; every phase write advances it by one. */
+  generation: number;
+  /** Unix milliseconds on Cloudly's clock. */
+  changedAt: number;
+  /** The administrator or producer that made the change. */
+  changedBy: string;
+}
+
+/**
+ * Why a cluster cannot leave `swarm` yet. Each blocker names the node or service it is about, so an
+ * administrator can act on it without a second query.
+ */
+export type TClusterRuntimeBlocker =
+  | { code: 'relay-not-enabled' | 'relay-not-registered' | 'address-plan-missing' | 'vpn-unconfigured' }
+  | { code: 'node-without-pallet-credential' | 'node-arch-unsupported'; nodeId: string }
+  | { code: 'service-multi-cluster-scope' | 'service-authority-unsupported' | 'platform-binding-present'; serviceId: string };
+
+/** Structural snapshot for exact persistence; which phase may follow which is the cutover's decision. */
+export const snapshotClusterRuntime = (value: unknown): IClusterRuntime => producerSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'phase', 'generation', 'changedAt', 'changedBy']);
+  requireNetwork(isOneOf(clusterRuntimePhases, item.phase));
+  return { id: networkId(item.id), phase: item.phase, generation: networkCounter(item.generation),
+    changedAt: networkCounter(item.changedAt), changedBy: networkId(item.changedBy) };
+});

package/ts/data/index.ts

@@ -1,5 +1,6 @@
 export * from './cloudlyconfig.js';
 export * from './cluster.js';
+export * from './clusterruntime.js';
 export * from './clusteringress.js';
 export * from './config.js';
 export * from './corestore.js';
@@ -24,10 +25,12 @@ export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './nodecredential.js';
 export * from './nodeenrollment.js';
+export * from './networkaddressplan.js';
 export * from './networkauthority.js';
 export * from './networkcredential.js';
 export * from './networkdelivery.js';
 export * from './networklease.js';
+export * from './networknode.js';
 export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrantV1, IRuntimeNetworkRouterProjectionV1 } from './networkrouter.js';
 export * from './networkprotection.js';
@@ -48,6 +51,7 @@ export * from './sparknodereport.js';
 export * from './service.js';
 export * from './servicecredential.js';
 export * from './serviceports.js';
+export * from './serviceruntime.js';
 export * from './status.js';
 export * from './taskexecution.js';
 export * from './traffic.js';