@serve.zone/interfaces 32.41.0 → 32.42.0

package/ts/data/networkauthority.ts

@@ -249,6 +249,52 @@ export const computeRuntimeNetworkProtectedAuthorityDigest = (value: IRuntimeNet
 export const computeRuntimeNetworkHandoffLeaseDigest = (value: IRuntimeNetworkHandoffLease): Promise<TSha256Digest> =>
   computeDigest(runtimeNetworkAuthorityContract.handoffDigestDomain, snapshotRuntimeNetworkHandoffLease(value));
 
+/** Every address of `prefix` lies in one of `cover`, which must not overlap itself. */
+const covered = (prefix: string, cover: string[]): boolean => {
+  const [first, last] = bounds(prefix);
+  let held = 0;
+  for (const range of cover) {
+    const [low, high] = bounds(range);
+    if (low <= last && first <= high) held += Math.min(last, high) - Math.max(first, low) + 1;
+  }
+  return held === last - first + 1;
+};
+/** Every entry of `previous` is in `next` with exactly the same content, matched by `key`. */
+const retains = <T>(previous: T[], next: T[], key: (value: T) => string): boolean =>
+  previous.every(entry => next.some(candidate => key(candidate) === key(entry) && equals(candidate, entry)));
+
+/**
+ * Whether `next` continues the protection `previous` states without taking anything from it:
+ * `next` is `previous` itself, or exactly the next step of its chain (the same `id` and controller,
+ * `next.previous` naming `previous`) that only adds. Every egress authority, pool, resolver and
+ * platform endpoint of `previous` is in `next` with exactly the same content, and the prefixes of
+ * `next` still cover every address `previous` protected, however split.
+ *
+ * Such a step is a cluster topology change: a node joins the egress, or a cluster's hub joins the
+ * platform endpoints. It changes no address, endpoint or pool anything already allocated or selected
+ * under `previous` relies on. It does not waive the step's barrier: every egress authority still
+ * acknowledges `next` with its own protection receipt before an allocation is bound to it
+ * (`bindRuntimeNetworkAllocationProtection`). Any removal or change, a later step than the next one,
+ * or another chain answers `false`. It validates both authorities, including their digests, and
+ * rejects either that does not validate.
+ */
+export const continuesRuntimeNetworkProtection = async (previousValue: unknown, nextValue: unknown): Promise<boolean> => {
+  const previous = snapshotRuntimeNetworkProtectedAuthority(previousValue);
+  const next = snapshotRuntimeNetworkProtectedAuthority(nextValue);
+  requireValue(previous.digest === await computeRuntimeNetworkProtectedAuthorityDigest(previous)
+    && next.digest === await computeRuntimeNetworkProtectedAuthorityDigest(next));
+  if (equals(previous, next)) return true;
+  const ownerKey = (value: IRuntimeNetworkProtectedAuthority['egressAuthorities'][number]) =>
+    canonical([value.nodeId, value.runtimeNamespace]);
+  return next.id === previous.id && equals(next.controller, previous.controller)
+    && equals(next.previous, { id: previous.id, generation: previous.generation, digest: previous.digest })
+    && retains(previous.egressAuthorities, next.egressAuthorities, ownerKey)
+    && retains(previous.pools, next.pools, value => value.id)
+    && retains(previous.resolvers, next.resolvers, value => value.id)
+    && retains(previous.platformEndpoints, next.platformEndpoints, value => value.id)
+    && previous.prefixes.every(prefix => covered(prefix, next.prefixes));
+};
+
 /** Detached, digest-verified allocation binding. Does not establish pool activation or live link identity. */
 export const bindRuntimeNetworkHandoffLease = async (leaseValue: unknown, authorityValue: unknown): Promise<{
   lease: IRuntimeNetworkHandoffLease; authority: IRuntimeNetworkProtectedAuthority;

package/ts/data/networkcredential.ts

@@ -1,6 +1,7 @@
 import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
 import { runtimeNetworkAddressPlanContract, type TRuntimeNetworkVpnTransport } from './networkaddressplan.js';
 import { snapshotRuntimeSessionBinding, type IRuntimeSessionBinding } from './runtimesession.js';
+import { continuesRuntimeNetworkProtection } from './networkauthority.js';
 import { snapshotRuntimeNetworkProjection, validateRuntimeNetworkProjection,
   type IRuntimeNetworkProjection } from './networkprojection.js';
 import { snapshotRuntimeNetworkDnsLeaseRenewal, validateRuntimeNetworkDnsLeaseRenewal,
@@ -84,11 +85,11 @@ export const bindGetRuntimeManagedVpnCredentialRequest = async (value: unknown,
  * A valid projection's handoff lease names the projection's own node scope, so one handoff
  * reference is one node scope and the scope needs no comparison of its own.
  */
-const continuesMembership = (previous: IRuntimeNetworkProjection, next: IRuntimeNetworkProjection): boolean =>
+const continuesMembership = async (previous: IRuntimeNetworkProjection, next: IRuntimeNetworkProjection): Promise<boolean> =>
   previous.handoff !== null && next.handoff !== null && previous.id === next.id
-  && networkEqual(networkReferenceOf(previous.protectedAuthority), networkReferenceOf(next.protectedAuthority))
   && networkEqual(networkReferenceOf(previous.handoff), networkReferenceOf(next.handoff))
-  && (next.generation > previous.generation || networkEqual(networkReferenceOf(previous), networkReferenceOf(next)));
+  && (next.generation > previous.generation || networkEqual(networkReferenceOf(previous), networkReferenceOf(next)))
+  && await continuesRuntimeNetworkProtection(previous.protectedAuthority, next.protectedAuthority);
 
 /** What a membership's credential keeps across its projections: everything but the projection and the expiry. */
 const credentialIdentity = (value: IGetRuntimeManagedVpnCredentialResponse) => ({
@@ -98,17 +99,21 @@ const credentialIdentity = (value: IGetRuntimeManagedVpnCredentialResponse) => (
 
 /**
  * Whether `next` continues the managed VPN membership `previous` belongs to: the same projection
- * lineage (`id`), the same protected authority, and the same handoff lease, which names the node
- * scope and carries the node's router incarnation. Both must hold a handoff, because a node without
- * one is no member. `next` is `previous` itself or a later generation; an earlier one, or another
- * projection under the same generation, continues nothing.
+ * lineage (`id`), a protected authority that continues the previous one
+ * (`continuesRuntimeNetworkProtection`: the same authority, or its next step that only adds), and
+ * the same handoff lease, which names the node scope and carries the node's router incarnation.
+ * Both must hold a handoff, because a node without one is no member. `next` is `previous` itself
+ * or a later generation; an earlier one, or another projection under the same generation,
+ * continues nothing.
  *
  * Everything else a projection states may move under one membership: its workload endpoints, their
  * readiness, observations and egress, its private networks, its router selection and its DNS window.
- * Those are what the member's network carries, never who the member is. A protection bump, a fresh
- * handoff (router reincarnation) or a new controller epoch ends the membership. Whether the hub a
- * credential names is still selected is the credential's question
- * (`bindGetRuntimeManagedVpnCredentialSuccessor`), not the membership's.
+ * Those are what the member's network carries, never who the member is. So does a cluster topology
+ * change: a node joining the egress or a cluster hub joining the platform endpoints is an additive
+ * protection step, and every member keeps its key pair across it. A protection step that removes or
+ * changes anything, or skips a step, a fresh handoff (router reincarnation) or a new controller
+ * epoch ends the membership. Whether the hub a credential names is still selected is the
+ * credential's question (`bindGetRuntimeManagedVpnCredentialSuccessor`), not the membership's.
  *
  * Validates both complete projections and rejects either that does not validate; a valid pair that
  * is not one membership answers `false`. It samples no clock and fences no session.
@@ -190,7 +195,7 @@ export const bindGetRuntimeManagedVpnCredentialSuccessor = async (value: unknown
     const previousProjection = await validateRuntimeNetworkProjection(previousInput);
     const projection = await validateRuntimeNetworkProjection(projectionInput);
     const renewal = renewalInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(renewalInput);
-    requireNetwork(continuesMembership(previousProjection, projection));
+    requireNetwork(await continuesMembership(previousProjection, projection));
     requireNetwork(networkEqual(previous.session, trusted)
       && networkEqual(previous.projection, networkReferenceOf(previousProjection)));
     requireNetwork(networkEqual(credentialIdentity(previous), credentialIdentity(response)));

package/ts/data/networkegressretirement.ts

@@ -0,0 +1,195 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeNetworkNodeScope } from './networkprojection.js';
+import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
+import { computeRuntimeNetworkProtectedAuthorityDigest, runtimeNetworkAuthorityContract,
+  snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
+import { nodeRuntimeRetirementDispositions, type TNodeRuntimeRetirementDisposition } from './noderetirement.js';
+import { readDataElements } from '../private/dataproperties.js';
+import { isOneOf } from '../private/producercontract.js';
+import { captureNetwork, failNetwork, networkCanonical, networkCounter, networkCoveredBy, networkDigest, networkEqual,
+  networkHash, networkId, networkList, networkNodeId, networkRecord, networkReference, networkReferenceOf, networkSafe,
+  networkScope, networkSorted, requireNetwork } from '../private/networkcontract.js';
+
+/** One egress owner of a protected authority, as `IRuntimeNetworkProtectedAuthority.egressAuthorities` names it. */
+export interface IRuntimeNetworkEgressOwner {
+  nodeId: string;
+  runtimeNamespace: string;
+}
+
+/** A remaining owner's acknowledged projection head, which carries no endpoint of the retired owner. */
+export interface IRuntimeNetworkEgressRetirementClearance extends IRuntimeNetworkEgressOwner {
+  projection: IRuntimeAuthorityReference;
+}
+
+/**
+ * The independent fence that lets one egress owner leave a protected authority.
+ *
+ * A protected authority's egress owners only grow by default: an owner that is offline, revoked or
+ * gone can never acknowledge a successor, and omitting it is not a revocation. This record is the
+ * controller's statement that the owner holds no packet authority any more, recorded against the
+ * exact authority it is about to leave. Every member is evidence the controller read from its own
+ * durable state when it recorded the fence:
+ *
+ * 1. the node carries an `INodeRuntimeRetirement` row (`disposition` copies it);
+ * 2. both node credentials are revoked (`revokedCredentials`, committed at `revokedAt`), so the node
+ *    can no longer register, renew a DNS lease or fetch a managed VPN credential;
+ * 3. every DNS and managed VPN window the node was ever issued has ended (`packetWindowExpiresAt`),
+ *    so no hub relays for it even if it was never told to stop;
+ * 4. every handoff and workload lease the node was granted is quarantined (`quarantinedHandoffs`,
+ *    `quarantinedWorkloads`) and is never handed out again;
+ * 5. every remaining owner of `protectedAuthority` acknowledged a projection head that carries no
+ *    endpoint of the node (`clearedProjections`).
+ *
+ * `lastReceipt` is the node's last accepted protection receipt. A `withdrawn` node took part in its
+ * retirement, so it always has one — its null withdrawal; a `lost` node may never have reported.
+ *
+ * A structural snapshot and digest do not authenticate any of it: the controller must fence the
+ * rows it read together with the authority it stages.
+ */
+export interface IRuntimeNetworkEgressRetirement extends IRuntimeNetworkNodeScope {
+  /** The exact protected authority the owner leaves: the predecessor of the step that drops it. */
+  protectedAuthority: IRuntimeAuthorityReference;
+  disposition: TNodeRuntimeRetirementDisposition;
+  lastReceipt: IRuntimeAuthorityReference | null;
+  /** The generation each node credential was revoked at. */
+  revokedCredentials: { spark: number; pallet: number };
+  /** Unix milliseconds on the controller's clock when the later of the two revocations committed. */
+  revokedAt: number;
+  /**
+   * Unix milliseconds: the latest end of any DNS or managed VPN window the node was ever issued, or
+   * `revokedAt` when it was issued none.
+   */
+  packetWindowExpiresAt: number;
+  /** Unix milliseconds when the fence was recorded: never before `revokedAt` or `packetWindowExpiresAt`. */
+  fencedAt: number;
+  /** Every handoff lease the node was granted, each quarantined, in canonical order. */
+  quarantinedHandoffs: IRuntimeAuthorityReference[];
+  /** Every workload lease the node was granted, each quarantined, in canonical order. */
+  quarantinedWorkloads: IRuntimeAuthorityReference[];
+  /** One entry per remaining owner of `protectedAuthority`, in canonical owner order. */
+  clearedProjections: IRuntimeNetworkEgressRetirementClearance[];
+  digest: TSha256Digest;
+}
+
+export const runtimeNetworkEgressRetirementContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-network-egress-retirement',
+  maximumQuarantinedHandoffs: runtimeNetworkAuthorityContract.maximumRetainedHandoffLeases,
+  maximumQuarantinedWorkloads: 512,
+  maximumClearedProjections: runtimeNetworkAuthorityContract.maximumEgressAuthorities - 1,
+  /** Fences one step may consume. Each is read on its own, so one step stays bounded. */
+  maximumFencesPerStep: 16,
+  /** Owners every earlier step fenced, over the lifetime of one protected authority. */
+  maximumRetiredOwners: 4096,
+  removal: 'absent-owner-requires-fence-bound-to-exact-previous-authority',
+  reentry: 'a-fenced-owner-never-returns',
+} as const);
+
+const ownerKey = (value: IRuntimeNetworkEgressOwner): string => networkCanonical([value.nodeId, value.runtimeNamespace]);
+const referenceKey = (value: IRuntimeAuthorityReference): string => networkCanonical(value);
+
+const readOwner = (value: unknown): IRuntimeNetworkEgressOwner => {
+  const item = networkRecord(value, ['nodeId', 'runtimeNamespace']);
+  return { nodeId: networkNodeId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace) };
+};
+const readReferences = (value: unknown, maximum: number): IRuntimeAuthorityReference[] =>
+  networkSorted(networkList(value, maximum, networkReference), referenceKey);
+const readClearance = (value: unknown): IRuntimeNetworkEgressRetirementClearance => {
+  const item = networkRecord(value, ['nodeId', 'runtimeNamespace', 'projection']);
+  return { ...readOwner({ nodeId: item.nodeId, runtimeNamespace: item.runtimeNamespace }),
+    projection: networkReference(item.projection) };
+};
+
+/** Exact-key structural snapshot, detached from its input. It verifies no digest and fences nothing. */
+export const snapshotRuntimeNetworkEgressRetirement = (value: unknown): IRuntimeNetworkEgressRetirement => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace', 'protectedAuthority',
+    'disposition', 'lastReceipt', 'revokedCredentials', 'revokedAt', 'packetWindowExpiresAt', 'fencedAt',
+    'quarantinedHandoffs', 'quarantinedWorkloads', 'clearedProjections', 'digest']);
+  const scope = networkScope(item);
+  const disposition = item.disposition;
+  requireNetwork(isOneOf(nodeRuntimeRetirementDispositions, disposition));
+  const lastReceipt = item.lastReceipt === null ? null : networkReference(item.lastReceipt);
+  requireNetwork(disposition === 'lost' || lastReceipt !== null);
+  const credentials = networkRecord(item.revokedCredentials, ['spark', 'pallet']);
+  const revokedAt = networkCounter(item.revokedAt), packetWindowExpiresAt = networkCounter(item.packetWindowExpiresAt);
+  const fencedAt = networkCounter(item.fencedAt);
+  requireNetwork(fencedAt >= revokedAt && fencedAt >= packetWindowExpiresAt);
+  const contract = runtimeNetworkEgressRetirementContract;
+  const clearedProjections = networkSorted(networkList(item.clearedProjections, contract.maximumClearedProjections,
+    readClearance), ownerKey);
+  requireNetwork(clearedProjections.every(owner => ownerKey(owner) !== ownerKey(scope)));
+  return { ...scope, protectedAuthority: networkReference(item.protectedAuthority), disposition, lastReceipt,
+    revokedCredentials: { spark: networkCounter(credentials.spark), pallet: networkCounter(credentials.pallet) },
+    revokedAt, packetWindowExpiresAt, fencedAt,
+    quarantinedHandoffs: readReferences(item.quarantinedHandoffs, contract.maximumQuarantinedHandoffs),
+    quarantinedWorkloads: readReferences(item.quarantinedWorkloads, contract.maximumQuarantinedWorkloads),
+    clearedProjections, digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkEgressRetirementDigest = (value: IRuntimeNetworkEgressRetirement): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkEgressRetirementContract.digestDomain, snapshotRuntimeNetworkEgressRetirement(value));
+
+/**
+ * Whether `next` may succeed `previous`, judged on its egress owners and the address space it keeps.
+ *
+ * Pure and fail-closed. `fences` are the egress retirements this step consumes; `retiredOwners` is
+ * the complete list of owners every earlier step fenced, which the caller's durable history must
+ * supply in canonical owner order. The step is accepted only when:
+ *
+ * - `next` is the exact successor of `previous` under the same controller, and both digests verify;
+ * - an owner of `previous` is absent from `next` only when exactly one fence, recorded against the
+ *   exact `previous` reference and verified by its digest, names it — a fence for an owner `next`
+ *   still names, or for an owner `previous` does not name, refuses the step;
+ * - every fence's `clearedProjections` names exactly the owners of `previous` this step keeps;
+ * - no owner in `retiredOwners` is named by `previous` or `next`, so a fenced owner never returns;
+ * - every pool of `previous` is kept unchanged and the prefixes of `next` cover those of `previous`;
+ *   a step that removes an owner also keeps every resolver of `previous` unchanged.
+ *
+ * Owners that join in the same step are admitted. With no fence this is the additive owner rule:
+ * nobody leaves. It verifies no fence evidence against live state and fences no record.
+ */
+export const bindRuntimeNetworkProtectedAuthorityRetirement = async (
+  previousValue: unknown, nextValue: unknown, fencesValue: unknown, retiredOwnersValue: unknown,
+): Promise<{
+  previous: IRuntimeNetworkProtectedAuthority;
+  next: IRuntimeNetworkProtectedAuthority;
+  fences: IRuntimeNetworkEgressRetirement[];
+}> => {
+  try {
+    const contract = runtimeNetworkEgressRetirementContract;
+    const previous = snapshotRuntimeNetworkProtectedAuthority(captureNetwork(previousValue));
+    const next = snapshotRuntimeNetworkProtectedAuthority(captureNetwork(nextValue));
+    const elements = readDataElements(fencesValue, contract.maximumFencesPerStep);
+    requireNetwork(elements);
+    const fences = networkSorted(elements.map(snapshotRuntimeNetworkEgressRetirement), ownerKey);
+    const retiredOwners = networkSorted(networkList(captureNetwork(retiredOwnersValue), contract.maximumRetiredOwners,
+      readOwner), ownerKey);
+    requireNetwork(previous.digest === await computeRuntimeNetworkProtectedAuthorityDigest(previous)
+      && next.digest === await computeRuntimeNetworkProtectedAuthorityDigest(next));
+    const reference = networkReferenceOf(previous);
+    requireNetwork(networkEqual(next.controller, previous.controller) && next.id === previous.id
+      && next.generation === previous.generation + 1 && networkEqual(next.previous, reference));
+
+    const previousOwners = new Set(previous.egressAuthorities.map(ownerKey));
+    const nextOwners = new Set(next.egressAuthorities.map(ownerKey));
+    const fenced = new Set(fences.map(ownerKey));
+    for (const fence of fences) {
+      requireNetwork(fence.digest === await computeRuntimeNetworkEgressRetirementDigest(fence)
+        && networkEqual(fence.controller, previous.controller) && networkEqual(fence.protectedAuthority, reference)
+        && previousOwners.has(ownerKey(fence)) && !nextOwners.has(ownerKey(fence)));
+    }
+    requireNetwork([...previousOwners].every(owner => nextOwners.has(owner) || fenced.has(owner)));
+    const kept = previous.egressAuthorities.filter(owner => !fenced.has(ownerKey(owner))).map(ownerKey);
+    for (const fence of fences) {
+      requireNetwork(networkEqual(fence.clearedProjections.map(ownerKey), kept));
+    }
+    requireNetwork(retiredOwners.every(owner => !previousOwners.has(ownerKey(owner)) && !nextOwners.has(ownerKey(owner))));
+
+    requireNetwork(previous.pools.every(pool => next.pools.some(candidate => networkEqual(candidate, pool)))
+      && previous.prefixes.every(prefix => networkCoveredBy(next.prefixes, prefix)));
+    if (fences.length > 0) {
+      requireNetwork(previous.resolvers.every(resolver => next.resolvers.some(candidate => networkEqual(candidate, resolver))));
+    }
+    return { previous, next, fences };
+  } catch { return failNetwork(); }
+};

package/ts/data/noderetirement.ts

@@ -5,11 +5,29 @@ const nodeRuntimeRetirementStates = ['retiring', 'retired'] as const;
 
 /**
  * How far a node's retirement has come: `retiring` while the producer still stops and removes the
- * node's slots, the compiler quarantines its handoff and both node credentials are revoked;
- * `retired` once all of that has settled and nothing but the node document is left to delete.
+ * node's slots, the compiler quarantines its handoff and leases, both node credentials are revoked
+ * and the node's egress fence (`IRuntimeNetworkEgressRetirement`) is not yet recorded; `retired`
+ * once the protected authority no longer names the node and nothing but the node document is left
+ * to delete.
  */
 export type TNodeRuntimeRetirementState = typeof nodeRuntimeRetirementStates[number];
 
+/** Every way a node can leave its runtime, in the order an escalation moves through them. */
+export const nodeRuntimeRetirementDispositions = Object.freeze(['withdrawn', 'lost'] as const);
+
+/**
+ * How the node leaves.
+ *
+ * `withdrawn`: the node still runs and takes part. Its slots are removed against its own removal
+ * receipts, and its Pallet withdraws its protection receipt before its credentials are revoked.
+ *
+ * `lost`: an administrator states that the node will never report again — its host is gone, wiped
+ * or unreachable for good. Its slots are abandoned without removal receipts, which is the one thing
+ * this statement authorizes. It authorizes nothing about packets: a lost node leaves the protected
+ * authority behind exactly the same controller-owned fence as a withdrawn one.
+ */
+export type TNodeRuntimeRetirementDisposition = typeof nodeRuntimeRetirementDispositions[number];
+
 /**
  * That one node leaves its cluster's runtime, stored beside the node document rather than inside
  * it, because a node update merges caller data and no caller may retire a node with it.
@@ -24,7 +42,9 @@ export interface INodeRuntimeRetirement {
   /** The cluster the node is retiring from, copied by Cloudly; never caller-chosen. */
   clusterId: string;
   state: TNodeRuntimeRetirementState;
-  /** The administrator who asked for the retirement. */
+  /** How the node leaves; a `withdrawn` retirement still `retiring` may be escalated to `lost`. */
+  disposition: TNodeRuntimeRetirementDisposition;
+  /** The administrator who asked for the retirement, or for its escalation. */
   actorId: string;
   /** Unix milliseconds on Cloudly's clock, when the row entered its current state. */
   since: number;
@@ -42,22 +62,38 @@ export const nodeRuntimeRetirementRefusals = Object.freeze([
    * `pallet`. Which of the two it is, `getClusterRuntime` says.
    */
   'cluster-runtime-not-pallet',
-  /** The node already carries a retirement row; neither of its states is left by retiring again. */
+  /**
+   * The node already carries a retirement row that this request cannot move: anything but a
+   * `withdrawn` row still `retiring`, asked again as `lost`.
+   */
   'node-already-retired',
   /** `expectedGeneration` is not the cluster runtime's current generation, so a cutover moved underneath the caller. */
   'conflict',
+  /**
+   * A `lost` retirement of a node whose last accepted report is younger than
+   * `clusterNodeObservationFreshnessMs`: a node that still reports is not lost, and it leaves as
+   * `withdrawn`.
+   */
+  'node-still-reporting',
 ] as const);
 
 /** One of the reasons Cloudly answers instead of a retirement row. */
 export type TNodeRuntimeRetirementRefusal = typeof nodeRuntimeRetirementRefusals[number];
 
+/** One disposition, exactly as `nodeRuntimeRetirementDispositions` spells it. */
+export const snapshotNodeRuntimeRetirementDisposition = (value: unknown): TNodeRuntimeRetirementDisposition => producerSafe(() => {
+  requireNetwork(isOneOf(nodeRuntimeRetirementDispositions, value));
+  return value;
+});
+
 /**
  * Structural snapshot for exact persistence; whether the node exists and whether its cluster admits
  * the retirement is Cloudly's.
  */
 export const snapshotNodeRuntimeRetirement = (value: unknown): INodeRuntimeRetirement => producerSafe(() => {
-  const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'actorId', 'since']);
+  const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'disposition', 'actorId', 'since']);
   requireNetwork(isOneOf(nodeRuntimeRetirementStates, item.state));
   return { id: networkNodeId(item.id), clusterId: networkId(item.clusterId), state: item.state,
+    disposition: snapshotNodeRuntimeRetirementDisposition(item.disposition),
     actorId: networkId(item.actorId), since: networkCounter(item.since) };
 });

package/ts/private/networkcontract.ts

@@ -244,3 +244,12 @@ export const networkContains = (outer: string, inner: string): boolean => {
 export const networkOverlaps = (left: string, right: string): boolean => {
   const [a, b] = networkPrefixBounds(left), [c, d] = networkPrefixBounds(right); return a <= d && c <= b;
 };
+/** Whether the union of `prefixes`, which never overlap one another, covers every address of `prefix`. */
+export const networkCoveredBy = (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;
+};

package/ts/requests/corestorecontrol.ts

@@ -0,0 +1,43 @@
+import * as plugins from '../plugins.js';
+import type * as userInterfaces from '../data/user.js';
+import type * as controlTokenInterfaces from '../data/corestorecontroltoken.js';
+
+/**
+ * Stores the Corestore control token for every cluster relay to read sealed, so an administrator
+ * sets it without an exec into Cloudly's process.
+ *
+ * One token for both Corestore provider configs, stored in one transaction: either both hold the
+ * new token or neither does. `expected` is the state `getCorestoreControlTokenState` answered, and
+ * Cloudly stores only while the token is still exactly there; a set that committed in between is
+ * refused, never overwritten. Only the verified credential of a freshly authenticated
+ * administrator is read, and Cloudly writes the `receipt` in the transaction that stores the token.
+ * The token is in this request and nowhere else: never in the answer, a log, a hook or a receipt.
+ * Cloudly refuses with one of `data.corestoreControlTokenSetRefusals`.
+ */
+export interface IReq_Admin_Cloudly_SetCorestoreControlToken
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_SetCorestoreControlToken
+> {
+  method: 'setCorestoreControlToken';
+  request: controlTokenInterfaces.ICorestoreControlTokenSetRequest & {
+    identity: userInterfaces.IIdentityCredential;
+  };
+  response: controlTokenInterfaces.ICorestoreControlTokenSetResult;
+}
+
+/**
+ * Whether Cloudly holds the Corestore control token, at which revision, and every receipt of a set,
+ * oldest first. Value-free: no token, no hash. Requires an administrator.
+ */
+export interface IReq_Admin_Cloudly_GetCorestoreControlTokenState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_GetCorestoreControlTokenState
+> {
+  method: 'getCorestoreControlTokenState';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+  };
+  response: controlTokenInterfaces.ICorestoreControlTokenStateRead;
+}

package/ts/requests/index.ts

@@ -12,6 +12,7 @@ import * as configRequests from './config.js';
 import * as coreMailRequests from './coremail.js';
 import * as coreMailAdminRequests from './coremail.admin.js';
 import * as corestoreRequests from './corestore.js';
+import * as corestoreControlRequests from './corestorecontrol.js';
 import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
@@ -52,6 +53,7 @@ export {
   coreMailRequests as coremail,
   coreMailAdminRequests as coremailAdmin,
   corestoreRequests as corestore,
+  corestoreControlRequests as corestorecontrol,
   deploymentRequests as deployment,
   dnsRequests as dns,
   domainRequests as domain,

package/ts/requests/node.ts

@@ -12,7 +12,7 @@ import type {
   INodeCredentialMutationResult,
   TNodeCredentialPurpose,
 } from '../data/nodecredential.js';
-import type { INodeRuntimeRetirement } from '../data/noderetirement.js';
+import type { INodeRuntimeRetirement, TNodeRuntimeRetirementDisposition } from '../data/noderetirement.js';
 import type { INodeRuntimeBindingRead, INodeRuntimeBindingRequest } from '../data/noderuntimebinding.js';
 import type {
   INodeEnrollmentRequest,
@@ -232,6 +232,13 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
  * `expectedGeneration` is the cluster runtime generation the caller read with `getClusterRuntime`:
  * retirement is a statement about a node of a Pallet cluster, so a cutover that moved the phase
  * meanwhile refuses the write instead of retiring a node out of a runtime it no longer runs in.
+ *
+ * `disposition` states how the node leaves (`data.TNodeRuntimeRetirementDisposition`). A request
+ * that states none asks for `withdrawn`, the retirement this request always described: the node
+ * takes part, and nothing is abandoned. `lost` is taken only when stated, is refused as
+ * `node-still-reporting` for a node that still reports, and escalates a `withdrawn` retirement that
+ * is still `retiring`. Neither disposition shortens the egress fence: the node leaves the protected
+ * authority only behind its `data.IRuntimeNetworkEgressRetirement`.
  * Every refusal is one of `data.nodeRuntimeRetirementRefusals` and takes nothing away.
  */
 export interface IReq_Any_Cloudly_RetireClusterNode extends plugins.typedrequestInterfaces.implementsTR<
@@ -243,6 +250,7 @@ export interface IReq_Any_Cloudly_RetireClusterNode extends plugins.typedrequest
     identity: IIdentity;
     nodeId: string;
     expectedGeneration: number;
+    disposition?: TNodeRuntimeRetirementDisposition;
   };
   response: {
     retirement: INodeRuntimeRetirement;