@serve.zone/interfaces 32.41.0 → 32.43.0

package/ts/data/corestorecontroltoken.ts

@@ -0,0 +1,195 @@
+import { isCorestoreControlToken } from '../runtime.corestore.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkId,
+  networkList,
+  networkRecord,
+  requireNetwork,
+} from '../private/networkcontract.js';
+
+/**
+ * Whether Cloudly holds the Corestore control token, and at which revision. Value-free.
+ *
+ * There is one token for both Corestore provider configs, so this is one state rather than one per
+ * provider. `revision` is 1 for the first token ever stored and advances by exactly one with every
+ * accepted set, whichever path set it. No request removes a token, so a present token never turns
+ * absent again.
+ */
+export type TCorestoreControlTokenState =
+  | { state: 'absent' }
+  | { state: 'present'; revision: number };
+
+/**
+ * What an administrator names to store the Corestore control token: the token, and the state the
+ * administrator last read. Never a minimum: a set that committed after that read is refused rather
+ * than overwritten.
+ *
+ * `token` is the secret itself, the only member of this contract that carries it. A sender never
+ * logs, hooks or persists the request; Cloudly never answers or records the token.
+ */
+export interface ICorestoreControlTokenSetRequest {
+  token: string;
+  expected: TCorestoreControlTokenState;
+}
+
+/**
+ * Which path stored a token: an administrator's typed request, or the `secrets
+ * set-corestore-control-token` command run inside Cloudly's container.
+ */
+export type TCorestoreControlTokenSetPath = 'admin-request' | 'container-cli';
+
+/**
+ * The audit record of one accepted set, which Cloudly writes in the transaction that stores the
+ * token. Append-only and value-free: it names which revision was stored, by whom, how and when,
+ * never the token or a hash of it.
+ */
+export interface ICorestoreControlTokenSetReceipt {
+  id: string;
+  /** The revision this set stored. */
+  revision: number;
+  via: TCorestoreControlTokenSetPath;
+  /** The administrator read from the verified credential, or `operator:secrets-cli`. */
+  actorId: string;
+  setAt: number;
+}
+
+/** What Cloudly answers to an accepted set: the state it produced and its receipt. Value-free. */
+export interface ICorestoreControlTokenSetResult {
+  state: { state: 'present'; revision: number };
+  receipt: ICorestoreControlTokenSetReceipt;
+}
+
+/**
+ * The token's state and its most recent receipts, oldest first: every receipt while the token has
+ * been set at most `corestoreControlTokenMaximumReceipts` times, the latest that many after. Value-free.
+ */
+export interface ICorestoreControlTokenStateRead {
+  state: TCorestoreControlTokenState;
+  receipts: ICorestoreControlTokenSetReceipt[];
+}
+
+/** Every reason Cloudly answers instead of storing a Corestore control token. */
+export const corestoreControlTokenSetRefusals = Object.freeze([
+  /** The token is outside the contract: its length, encoding or whitespace (`isCorestoreControlToken`). */
+  'token-invalid',
+  /** `expected` said absent, and a token is stored. */
+  'token-present',
+  /** `expected` named a revision, and no token is stored. */
+  'token-absent',
+  /** `expected` named a revision, and the stored token is at another one. */
+  'token-revision-mismatch',
+  /** A Corestore provider config is missing or disabled, so there is nothing to store it under. */
+  'provider-unavailable',
+] as const);
+
+export type TCorestoreControlTokenSetRefusal = typeof corestoreControlTokenSetRefusals[number];
+
+/** The actor a receipt names when the in-container command stored the token. */
+export const corestoreControlTokenContainerCliActorId = 'operator:secrets-cli' as const;
+
+/** The most receipts one state read answers: the latest ones, once a token has been set more often. */
+export const corestoreControlTokenMaximumReceipts = 4096;
+
+const fail = (): never => { throw new Error('Corestore control token contract rejected.'); };
+const safe = <T>(operationArg: () => T): T => {
+  try { return operationArg(); } catch { return fail(); }
+};
+
+const readState = (valueArg: unknown): TCorestoreControlTokenState => {
+  const value = networkRecord(valueArg, ['state'], ['revision']);
+  if (value.state === 'absent') {
+    networkRecord(value, ['state']);
+    return { state: 'absent' };
+  }
+  requireNetwork(value.state === 'present');
+  return { state: 'present', revision: networkCounter(networkRecord(value, ['state', 'revision']).revision) };
+};
+
+export const snapshotCorestoreControlTokenState = (
+  valueArg: unknown,
+): TCorestoreControlTokenState => safe(() => readState(captureNetwork(valueArg)));
+
+/**
+ * Structural copy of a set request. A refusal never quotes the request, because it carries the
+ * token: every failure is the contract's one value-free message.
+ */
+export const snapshotCorestoreControlTokenSetRequest = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['token', 'expected']);
+  requireNetwork(isCorestoreControlToken(value.token));
+  return { token: value.token, expected: readState(value.expected) };
+});
+
+const readReceipt = (valueArg: unknown): ICorestoreControlTokenSetReceipt => {
+  const value = networkRecord(valueArg, ['id', 'revision', 'via', 'actorId', 'setAt']);
+  requireNetwork(value.via === 'admin-request' || value.via === 'container-cli');
+  const actorId = networkId(value.actorId);
+  requireNetwork(value.via === 'admin-request'
+    ? actorId !== corestoreControlTokenContainerCliActorId
+    : actorId === corestoreControlTokenContainerCliActorId);
+  return {
+    id: networkId(value.id),
+    revision: networkCounter(value.revision),
+    via: value.via,
+    actorId,
+    setAt: networkCounter(value.setAt),
+  };
+};
+
+export const snapshotCorestoreControlTokenSetReceipt = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetReceipt => safe(() => readReceipt(captureNetwork(valueArg)));
+
+export const snapshotCorestoreControlTokenSetResult = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetResult => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['state', 'receipt']);
+  const state = readState(value.state);
+  requireNetwork(state.state === 'present');
+  return { state, receipt: readReceipt(value.receipt) };
+});
+
+/**
+ * Structural copy of a state read. No token stored means no receipt. A stored token's receipts are
+ * contiguous and end at its revision, and they start at revision 1 -- or at 2, because only a token
+ * stored before receipts existed reaches revision 1 without one -- unless the read is a full window
+ * of `corestoreControlTokenMaximumReceipts`, whose oldest receipt may name any later revision.
+ */
+export const snapshotCorestoreControlTokenStateRead = (
+  valueArg: unknown,
+): ICorestoreControlTokenStateRead => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['state', 'receipts']);
+  const state = readState(value.state);
+  const receipts = networkList(value.receipts, corestoreControlTokenMaximumReceipts, readReceipt);
+  if (state.state === 'absent') {
+    requireNetwork(receipts.length === 0);
+    return { state, receipts };
+  }
+  const first = state.revision - receipts.length + 1;
+  requireNetwork(first >= 1
+    && (first <= 2 || receipts.length === corestoreControlTokenMaximumReceipts)
+    && receipts.every((receipt, index) => receipt.revision === first + index));
+  return { state, receipts };
+});
+
+/**
+ * Joins a set answer to the request it answers. The answered state is the one the request
+ * produces -- revision 1 when no token was stored, the expected revision plus one otherwise -- and
+ * the receipt is an administrator's receipt for exactly that revision. Content join only: whether
+ * the token was stored is Cloudly's to prove, and the answer never carries it.
+ */
+export const bindCorestoreControlTokenSet = (
+  resultArg: unknown,
+  requestArg: unknown,
+): ICorestoreControlTokenSetResult => safe(() => {
+  const request = snapshotCorestoreControlTokenSetRequest(requestArg);
+  const result = snapshotCorestoreControlTokenSetResult(resultArg);
+  const produced = request.expected.state === 'absent' ? 1 : request.expected.revision + 1;
+  requireNetwork(Number.isSafeInteger(produced)
+    && result.state.revision === produced
+    && result.receipt.revision === produced
+    && result.receipt.via === 'admin-request');
+  return result;
+});

package/ts/data/index.ts

@@ -7,6 +7,7 @@ export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
+export * from './corestorecontroltoken.js';
 export * from './corestorelegacyadoption.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
@@ -38,6 +39,7 @@ export * from './networkaddressplan.js';
 export * from './networkauthority.js';
 export * from './networkcredential.js';
 export * from './networkdelivery.js';
+export * from './networkegressretirement.js';
 export * from './networklease.js';
 export * from './networknode.js';
 export * from './networkprojection.js';

package/ts/data/networkaddressplan.ts

@@ -2,8 +2,8 @@ import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import { computeRuntimeNetworkProtectedAuthorityDigest, runtimeNetworkAuthorityContract,
   snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
-import { captureNetwork, failNetwork, networkContains, networkCounter, networkEqual, networkId, networkIpv4, networkList,
-  networkOverlaps, networkPrefix, networkPrefixBounds, networkPrivatePrefix, networkRecord, networkSafe,
+import { captureNetwork, failNetwork, networkContains, networkCounter, networkCoveredBy, networkEqual, networkId, networkIpv4, networkList,
+  networkOverlaps, networkPrefix, networkPrivatePrefix, networkRecord, networkSafe,
   requireNetwork, RuntimeNetworkAddressPlanStructureError, type TRuntimeNetworkAddressPlanOrderedField,
 } from '../private/networkcontract.js';
 
@@ -279,16 +279,6 @@ export const composeRuntimeNetworkProtectedAuthority = async (
   } 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.
@@ -314,7 +304,7 @@ export const admitRuntimeNetworkAddressPlanChange = (previousValue: unknown | nu
     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' };
+    if (!previous.prefixes.every(prefix => networkCoveredBy(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

@@ -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,231 @@
+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`). An owner whose own `lost` fence is recorded
+ *    against the same authority is not a remaining owner here: it never acknowledges anything again,
+ *    so it can never clear another owner's endpoints, and it leaves behind its own fence.
+ *
+ * `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` whose own `lost` fence is not recorded
+   * against that authority, 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,
+  /**
+   * Lost fences one step may hold as exemptions: owners it keeps that no consumed fence's clearance
+   * has to name. At least one owner is kept, so this is one fewer than the owners an authority has.
+   */
+  maximumExemptionsPerStep: runtimeNetworkAuthorityContract.maximumEgressAuthorities - 1,
+  /**
+   * Retired owners one step may be given: the caller's history restricted to owners `previous` or
+   * `next` names, which is at most every owner of both.
+   */
+  maximumRetiredOwners: 2 * runtimeNetworkAuthorityContract.maximumEgressAuthorities,
+  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. `exemptions` are
+ * `lost` fences of owners this step keeps, recorded against the same `previous`: such an owner never
+ * acknowledges another projection head, so no consumed fence's clearance can wait for it. They are
+ * read, not consumed, and default to none. `retiredOwners` is the caller's durable history of
+ * fenced owners restricted to the owners `previous` or `next` names, 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 exemption verifies by its digest, is `lost`, is recorded under the same controller against
+ *   the exact `previous` reference, and names an owner both `previous` and `next` name, no fence
+ *   names and no other exemption names; at most `maximumExemptionsPerStep`, in canonical owner order;
+ * - every fence's `clearedProjections` names exactly the owners of `previous` this step keeps, less
+ *   the exempt owners; an exemption's own clearance is not judged here, only when its owner leaves;
+ * - `retiredOwners` is empty: any entry is either an owner a side names that was fenced before, or
+ *   not part of the restriction at all, 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, and exemptions relax nothing. It verifies no fence evidence against live state and
+ * fences no record: the caller fences every fence and exemption it read together with the authority
+ * it stages.
+ */
+export const bindRuntimeNetworkProtectedAuthorityRetirement = async (
+  previousValue: unknown, nextValue: unknown, fencesValue: unknown, retiredOwnersValue: unknown,
+  exemptionsValue: unknown = [],
+): Promise<{
+  previous: IRuntimeNetworkProtectedAuthority;
+  next: IRuntimeNetworkProtectedAuthority;
+  fences: IRuntimeNetworkEgressRetirement[];
+  exemptions: 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 exemptionElements = readDataElements(exemptionsValue, contract.maximumExemptionsPerStep);
+    requireNetwork(exemptionElements);
+    const exemptions = networkSorted(exemptionElements.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)));
+    for (const exemption of exemptions) {
+      requireNetwork(exemption.digest === await computeRuntimeNetworkEgressRetirementDigest(exemption)
+        && exemption.disposition === 'lost' && networkEqual(exemption.controller, previous.controller)
+        && networkEqual(exemption.protectedAuthority, reference) && previousOwners.has(ownerKey(exemption))
+        && nextOwners.has(ownerKey(exemption)));
+    }
+    // A fence's owner is never named by `next`, so no exemption names an owner a fence names.
+    const exempt = new Set(exemptions.map(ownerKey));
+    const cleared = previous.egressAuthorities.map(ownerKey).filter(owner => !fenced.has(owner) && !exempt.has(owner));
+    for (const fence of fences) {
+      requireNetwork(networkEqual(fence.clearedProjections.map(ownerKey), cleared));
+    }
+    requireNetwork(retiredOwners.length === 0);
+
+    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, exemptions };
+  } catch { return failNetwork(); }
+};