@serve.zone/interfaces 31.7.0 → 31.9.0

package/readme.md

@@ -371,7 +371,8 @@ set. An empty array declares NODATA; absent/unauthorized names remain NXDOMAIN,
 and IPv4-only service names have AAAA NODATA. The view carries the existing
 forwarding intersection and zero or one search suffix. Pallet must prove the
 actual sandbox/veth/source binding, block private/bare-name forwarding, clip
-TTLs and convert the absolute window using its qualified boot/time authority.
+TTLs and convert the effective window from `getRuntimeNetworkEffectiveDnsWindow` (see
+[DNS Lease Renewals](#dns-lease-renewals)) using its qualified boot/time authority.
 These helpers neither cache queries nor renew a lease.
 
 The DNS composer accepts an optional second argument of exact local workload
@@ -454,10 +455,11 @@ capture closed detached JSON shapes and canonical 32-byte key encodings.
 `bindGetRuntimeManagedVpnCredentialRequestV1(request, projection, trustedSession)`
 validates the complete projection digest and binds node, controller, namespace,
 physical-session identity and projection reference. The response binder takes
-`(response, request, projection, trustedSession, now)` and additionally requires
+`(response, request, projection, trustedSession, now, renewal = null)` and additionally requires
 the relay's exact UDP tuple to be selected in `router.platformEndpointIds`.
 Expiry must be after the caller-qualified time and no later than the referenced
-projection's DNS lease; acceptance before that lease starts rejects.
+projection's effective DNS window (see [DNS Lease Renewals](#dns-lease-renewals));
+acceptance before that window starts rejects.
 
 These helpers perform content validation. Callers authenticate and fence the
 current physical peer and projection before and after native work, qualify time
@@ -466,6 +468,188 @@ Noise implementation owns cryptographic validation and authentication. Credentia
 delivery does not prove a connected VPN, TUN ownership, packet enforcement or
 workload readiness, and does not replace explicit packet withdrawals.
 
+### DNS Lease Renewals
+
+A projection's `dns` window lasts at most fifteen minutes and is signed content, so a node's
+private DNS stops when the window ends unless a newer signed statement extends it. Re-issuing the
+projection would extend it too, but a node applies every new projection as new network state,
+which restarts its data plane. `IRuntimeNetworkDnsLeaseRenewal` extends the window and nothing
+else: it carries the node scope (`controller`, `nodeId`, `runtimeNamespace`), the exact
+`projection` reference it renews, a `sequence`, a fresh `dns { issuedAt, notBefore, expiresAt }`
+window and its `digest`. It names the projection by reference, so it never joins the projection
+chain and never changes what the node applied. The new shapes carry no `schemaVersion` and no
+version suffix; the installed package version is the protocol version.
+
+`issuedAt` is the start of the window's slot, not the moment of signing: Cloudly signs renewals
+ahead of time on a grid, so the fifteen-minute rule (`maximumDnsLeaseMs`, the same limit a
+projection's window has) is measured from the slot. `computeRuntimeNetworkDnsLeaseRenewalDigest`
+hashes every field except `digest` under its own domain, and `validateRuntimeNetworkDnsLeaseRenewal`
+checks structure and digest only; a digest authenticates nothing.
+
+The Node-only `@serve.zone/interfaces/runtime` export signs and verifies renewals with the same
+authority and key that sign the controller's projections, under a separate signature domain.
+`signRuntimeNetworkDnsLeaseRenewal(renewal, authority, privateKey)` produces
+`ISignedRuntimeNetworkDnsLeaseRenewal { authority, renewal, signature }`.
+`verifyRuntimeNetworkDnsLeaseRenewal(signed, trustedAuthority, trustedScope, projectionAuthority)`
+takes the authority and scope from the node's own stored trust, never from the envelope.
+`projectionAuthority` is the reference of the authority revision that signed the projection the
+node admitted, and a renewal verifies only when it was signed under exactly that revision.
+Rotation and revocation end renewals exactly as they end projections: nothing signed under an
+earlier revision verifies after, and a renewal signed under a rotated revision does not renew a
+projection signed under the one before. A renewal never closes a key gap; after rotation, DNS
+continues only with a newly signed projection.
+
+`admitRuntimeNetworkDnsLeaseRenewal(renewal, currentProjection, previousRenewal | null, trustedScope, now)`
+is the pure admission decision after verification. The projection and the previous renewal are
+the node's own admitted state, and `now` is its caller-qualified clock, read before the first
+await like every other input. It admits a renewal only when:
+
+- the renewal and the projection are in the trusted scope, and the renewal names the current
+  projection's exact reference. Once a successor projection is admitted, every renewal of its
+  predecessor is refused, and a renewal never introduces a projection the node has not admitted;
+- its `sequence` is higher than the previous renewal's, with gaps allowed, or equal with
+  byte-identical content, which is answered as `replay` whatever `now` is, so re-delivery is
+  idempotent. The same sequence with any other content is refused;
+- its window is current: `notBefore <= now < expiresAt`. Admitting a window that has not opened
+  would displace the coverage the node has now, so a sender delivers a window only once its slot
+  has opened; a renewal refused for arriving early is simply delivered again once it has. An
+  expired window is refused as well;
+- its window does not move `issuedAt` back and ends later than the previous window. Without a
+  previous renewal, the projection's own window is the baseline. Windows need not touch, so a node
+  whose lease lapsed can still admit the next renewal it is given.
+
+The caller stores the admitted renewal in the same transaction as its trust fence, and deletes it
+in the transaction that admits a successor projection. Admission is not conversion: the node still
+turns the window into a deadline with its qualified clock, and must not use a window before its
+`notBefore`.
+
+`requests.runtimesession.IReq_Controller_Pallet_ApplyRuntimeNetworkDnsLeaseRenewal`
+(`applyRuntimeNetworkDnsLeaseRenewal`) delivers one renewal as
+`IApplyRuntimeNetworkDnsLeaseRenewalRequest { session, signed }`.
+`bindApplyRuntimeNetworkDnsLeaseRenewalRequest(request, trustedSession)` requires the node's
+current physical-session binding and a renewal in that session's scope. It does not care who sent
+the request: a cluster relay pushes under the binding the node obtained itself. The answer,
+`IApplyRuntimeNetworkDnsLeaseRenewalResponse { status, renewal }`, repeats
+`IRuntimeNetworkDnsLeaseRenewalReference { projection, sequence, digest }`.
+`bindApplyRuntimeNetworkDnsLeaseRenewalResponse(response, sentRenewal)` compares it with the exact
+renewal that was sent. The ACK asserts durable admission only, not that the node serves DNS.
+
+A cluster is outbound-only, so while its relay cannot reach Cloudly nobody can sign a new window.
+Cloudly therefore hands the elected relay a run of renewals it signed ahead of time, with
+`requests.cluster.IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals`
+(`holdRuntimeNetworkDnsLeaseRenewals`):
+`IHoldRuntimeNetworkDnsLeaseRenewalsRequest { nodeId, projection, renewals }` answered by
+`{ held }`. Each request replaces what the relay held for that node, and an empty run holds
+nothing. The relay keeps the run in memory only, pushes only the renewal whose window is current
+and only while it has no Cloudly session (`escrowRelease`), and holds no key and no trust.
+`snapshotHoldRuntimeNetworkDnsLeaseRenewalsRequest` checks the rules a relay can evaluate without
+the projection itself; the node still measures the first window against its admitted projection,
+and every window against its clock, when it admits it. The run must have:
+
+- one node, one projection and one signing authority revision, in one scope;
+- strictly ascending sequences, each window extending the one before;
+- at most `maximumEscrowedRenewals` (32) renewals;
+- at most `maximumEscrowHorizonMs` (four hours) from the first window's `issuedAt` to the last
+  window's `expiresAt`. On the intended grid of fifteen-minute windows every ten minutes, the
+  horizon allows 23 windows, so it is the limit that binds.
+
+`validateHoldRuntimeNetworkDnsLeaseRenewalsRequest` adds every renewal's digest check and
+verifies no signature. `bindHoldRuntimeNetworkDnsLeaseRenewalsResponse(response, sentRequest)`
+requires `held` to equal the number of renewals sent.
+
+The horizon is also the revocation latency: a detached cluster keeps DNS authority until its last
+held window ends. So a controller must not release an address or a DNS name before the latest
+`expiresAt` it has signed for that node. Renewals extend DNS only. They grant no packet authority
+and cannot introduce new network state, and they do not extend an already-issued VPN credential;
+a newly issued one may be bound to the renewed window.
+
+`getRuntimeNetworkEffectiveDnsWindow(projection, renewal | null)` is the one rule for the window a
+node may use: the admitted renewal's if there is one, else the projection's own. `renewal` is the
+bare `IRuntimeNetworkDnsLeaseRenewal` that admission takes and returns, which is what a node
+stores; Cloudly passes `signed.renewal`. It checks digests and that the renewal names exactly that
+projection, but verifies no signature. Controller and node use it for every limit tied to the
+window, and `bindGetRuntimeManagedVpnCredentialResponseV1` takes the same bare admitted renewal as
+an optional last argument, so a newly issued managed-VPN credential may run to the end of the
+renewed window instead of the projection's original one.
+
+```typescript
+import { data } from '@serve.zone/interfaces';
+import { signRuntimeNetworkDnsLeaseRenewal, verifyRuntimeNetworkDnsLeaseRenewal } from '@serve.zone/interfaces/runtime';
+
+const renewal: data.IRuntimeNetworkDnsLeaseRenewal = {
+  ...scope,
+  projection: { id: projection.id, generation: projection.generation, digest: projection.digest },
+  sequence: 1,
+  dns: { issuedAt: slotStart, notBefore: slotStart, expiresAt: slotStart + 900_000 },
+  digest: `sha256:${'0'.repeat(64)}` as data.TSha256Digest, // well-formed placeholder, replaced below
+};
+renewal.digest = await data.computeRuntimeNetworkDnsLeaseRenewalDigest(renewal);
+const signed = await signRuntimeNetworkDnsLeaseRenewal(renewal, signingAuthority, privateKey);
+
+// On the node: stored trust, then the node's own admitted state and qualified clock.
+const verified = await verifyRuntimeNetworkDnsLeaseRenewal(
+  signed, storedAuthority, nodeScope, admittedProjectionAuthority);
+const { renewal: admittedRenewal } = await data.admitRuntimeNetworkDnsLeaseRenewal(
+  verified.renewal, admittedProjection, previousRenewal, nodeScope, qualifiedNow);
+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,
@@ -599,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.7.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,9 +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';
@@ -47,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';

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]) {