@serve.zone/interfaces 32.42.0 → 32.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.42.0",
+  "version": "32.44.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -27,10 +27,10 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.1",
+    "@git.zone/tsbuild": "^5.1.2",
     "@git.zone/tsdoc": "^3.0.1",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "6.3.2",
+    "@git.zone/tstest": "6.3.4",
     "@types/node": "26.6.2"
   },
   "files": [

package/readme.md

@@ -409,7 +409,17 @@ authorities and their digests are validated, and either that does not validate i
 protection journal separately from projection admission. It binds a complete
 protected-authority reference, node/controller scope, authenticated reporter,
 boot identity and exact native journal reference to a monotonic receipt chain.
-A null `nativeBarrier` explicitly removes allocation eligibility. A boot or
+A null `nativeBarrier` explicitly removes allocation eligibility. A node sends one
+only in answer to the `retirement` request of a signed projection (see
+[Projection Retirement Requests](#projection-retirement-requests)): its egress
+ownership is being retired with the `withdrawn` disposition, and it mints no
+positive receipt for the chain afterwards
+(`runtimeNetworkProtectionContract.withdrawal`). Nothing else withdraws. The
+node's allocation-pool guard is retained in the kernel when the node process
+ends, and its boot unit restores it before networking starts, so a clean stop, a
+crash, a reboot or being offline leaves the last receipt current. A reconnect
+binds a new reporter session, which the old receipt no longer matches, and the
+node's first positive receipt under that session restores eligibility. A boot or
 protection change requires new native journal evidence. These portable values
 do not inspect a kernel or authenticate their own producer.
 
@@ -682,6 +692,59 @@ reaches only the endpoints it selects. The platform endpoint contract itself
 (`{ id, address, protocol, port }`) names no node, which is why this statement is
 per projection.
 
+#### Projection Retirement Requests
+
+The optional `IRuntimeNetworkProjection.retirement`
+(`IRuntimeNetworkProjectionRetirement { disposition: 'withdrawn', protectedAuthority }`)
+is Cloudly's request that a running node withdraw its allocation protection,
+because its egress ownership is being retired with the `withdrawn` disposition.
+It travels in the projection because that is the one authenticated, monotonic
+channel the node already admits, journals and reads on every pass, and whose
+acknowledged head Cloudly already tracks: the controller's signature covers it, so
+a node cannot invent it; the projection chain is bound to the controller epoch,
+node and runtime namespace, so it cannot be carried elsewhere; and a node's
+acknowledged head proves the node admitted it. A retired node never returns
+(`runtimeNetworkEgressRetirementContract.reentry`), so no later chain of the same
+node can meet a stale request.
+
+`protectedAuthority` is the authority current when Cloudly first signed the
+request; its `id` names the receipt chain's authority chain.
+`validateRuntimeNetworkProjection` accepts it only on a `cloudly` projection and
+only naming the projection's own authority chain at a generation the projection
+has reached (the current authority itself at the same generation).
+`admitRuntimeNetworkProjection` latches it: it may first appear on any projection,
+including the first, and that first appearance names exactly the projection's
+current `protectedAuthority` (an older generation is refused, because the node's
+positive receipt under the current authority would then be newer than the request
+and the withdrawal could never complete). Afterwards every successor carries it
+unchanged, never dropped and never rewritten, so it stays fixed while the
+authority chain moves on. Omitted, it keeps the canonical bytes and asks for
+nothing; it grants and withdraws no packet flow. Consumers on interfaces earlier
+than 32.44.0 read projections with exact keys and refuse one that carries
+`retirement`, so Cloudly sends the request only to nodes that report a compatible
+interfaces version.
+`snapshotRuntimeNetworkProjectionRetirement` is the exact-key reader and
+`runtimeNetworkProjectionRetirementContract` states the rules.
+
+The node answers with the null-barrier successor of its protection receipt chain
+and mints no positive receipt for that chain again. Its allocation-pool guard
+stays enforced: the answer withdraws eligibility, not protection.
+
+`bindRuntimeNetworkProtectionReceiptRetirement(receipt, previous, retirement)` is
+the receiver's gate for every report from a node whose projections carry the
+request, beside `admitRuntimeNetworkProtectionReceipt` with the same `previous`
+(the receiver's current receipt for the node, or null). The receipt must belong to
+the retiring authority chain and `previous`, when given, must be the same chain's
+exact predecessor or the receipt itself. The null answer always passes. A positive
+receipt passes only while it can predate the node's admission of the request, so a
+receipt the node minted before it saw the request still drains from its outbox
+and the withdrawal behind it is never wedged: it names no authority newer than the
+request's (a newer one could only come from a projection already carrying the
+request), and its predecessor is not a null withdrawal (once the receiver holds
+the answer, no positive receipt follows). A positive receipt minted after the
+request against the same authority cannot be told apart from one minted before;
+the node's obligation is never to mint one.
+
 `admitRuntimeNetworkProjection` checks exact predecessor/replay identity and
 rejects changed same-generation content, regressed membership/readiness evidence,
 changed immutable address/DNS keys, and omitted packet grants without explicit
@@ -796,11 +859,15 @@ exact protected authority the owner is about to leave, once all five hold:
    (`quarantinedHandoffs`, at most 256, and `quarantinedWorkloads`, at most 512,
    both in canonical order) and is never handed out again;
 5. every remaining owner of that authority acknowledged a projection head that
-   carries no endpoint of the node (`clearedProjections`, one per remaining owner
-   in canonical owner order, never the node itself).
+   carries no endpoint of the node (`clearedProjections`, in canonical owner order,
+   never the node itself). A remaining owner whose own `lost` fence is recorded
+   against the same authority is left out: it never acknowledges anything again, so
+   waiting for it would freeze every other owner's retirement, and it leaves behind
+   its own fence. Every other remaining owner has exactly one entry.
 
 `lastReceipt` is the node's last accepted protection receipt. A `withdrawn` node
-took part in its own retirement, so it always has one (its null withdrawal); a
+took part in its own retirement, so it always has one (its null withdrawal, the
+answer to its projection's `retirement` request); a
 `lost` node may have none. Neither disposition shortens the fence: a lost node
 leaves behind exactly the same controller-owned evidence as a withdrawn one.
 `snapshotRuntimeNetworkEgressRetirement` is the exact-key reader and
@@ -810,19 +877,40 @@ evidence; the controller fences the rows it read together with the authority it
 stages.
 
 `bindRuntimeNetworkProtectedAuthorityRetirement(previous, next, fences,
-retiredOwners)` is the pure successor rule for the egress owners and the address
-space of any step. `next` must be the exact successor of `previous` under the same
+retiredOwners, exemptions = [])` is the pure successor rule for the egress owners
+and the address space of any step, and answers `{ previous, next, fences,
+exemptions }`. `next` must be the exact successor of `previous` under the same
 controller, with both digests verified. An owner of `previous` may be absent from
 `next` only when exactly one fence recorded against the exact `previous` reference,
 verified by its digest, names it; a fence for an owner `next` still names, or one
-`previous` never named, refuses the step, and every fence's `clearedProjections`
-must name exactly the owners the step keeps. `retiredOwners` is the complete,
-canonically ordered list of owners earlier steps fenced, which the caller's
-durable history supplies; neither side may name any of them, so a fenced owner
-never returns. Every pool of `previous` stays unchanged and the prefixes of `next`
-cover those of `previous`; a step that removes an owner also keeps every resolver.
-Owners may join in the same step, and a step without fences is the additive rule.
-One step consumes at most 16 fences (`runtimeNetworkEgressRetirementContract`).
+`previous` never named, refuses the step.
+
+`exemptions` are the `lost` fences of owners the step keeps, recorded against the
+same `previous`. They are read and returned, not consumed: each verifies by its
+digest, is recorded under the same controller against the exact `previous`
+reference, and names an owner both `previous` and `next` name that no fence and no
+other exemption names, in canonical owner order and at most 255 per step. A
+withdrawn or stale exemption refuses the step. Every consumed fence's
+`clearedProjections` must name exactly the owners the step keeps less the exempt
+owners, in both directions: a clearance that names an exempt owner or misses a kept
+one refuses the step. An exemption's own clearance is judged only in the step that
+consumes it as a fence. Lost owners can therefore be fenced in parallel against one
+authority and leave 16 per step: each step consumes up to 16 of their fences and
+holds the rest as exemptions, and every later step re-records the remaining fences
+against its own `previous`.
+
+`retiredOwners` is the caller's durable history of fenced owners restricted to the
+owners `previous` or `next` names, in canonical order and at most 512 entries. Any
+entry refuses the step, so a fenced owner never returns, and the caller looks up
+only the owners of the two authorities instead of supplying a lifetime list. The
+caller must look up every owner that `previous` and `next` name: the binder cannot
+tell a missed lookup from an empty history, so an omitted entry silently drops the
+guarantee. Every
+pool of `previous` stays unchanged and the prefixes of `next` cover those of
+`previous`; a step that removes an owner also keeps every resolver. Owners may join
+in the same step, and a step without fences is the additive rule, which exemptions
+do not change. One step consumes at most 16 fences
+(`runtimeNetworkEgressRetirementContract`).
 
 A retirement step is a new protected authority: every remaining owner reports a
 receipt citing it before anything new is allocated, while existing leases keep
@@ -1903,8 +1991,10 @@ document. `snapshotNodeRuntimeRetirement` checks the record.
 
 `TNodeRuntimeRetirementDisposition` (`nodeRuntimeRetirementDispositions`,
 `snapshotNodeRuntimeRetirementDisposition`) says 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
+runs and takes part — its slots are removed against its own removal receipts, Cloudly asks it
+through its projection's `retirement` request (see
+[Projection Retirement Requests](#projection-retirement-requests)), and its Pallet answers by
+withdrawing its protection receipt before its credentials are revoked. `lost`: an administrator
 states the node will never report again, which authorizes abandoning its slots without removal
 receipts and nothing else; its egress fence is the same as a withdrawn node's.
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/index.ts

@@ -49,6 +49,8 @@ export { runtimeNetworkHostContract } from './networkhost.js';
 export type { IRuntimeNetworkWorkloadIngress, IRuntimeNetworkWorkloadIngressPacketGrant,
   IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
 export { runtimeNetworkWorkloadIngressContract } from './networkworkloadingress.js';
+export type { IRuntimeNetworkProjectionRetirement } from './networkprojectionretirement.js';
+export { runtimeNetworkProjectionRetirementContract, snapshotRuntimeNetworkProjectionRetirement } from './networkprojectionretirement.js';
 export * from './networkprotection.js';
 export * from './networksigning.js';
 export * from './privatenetwork.js';

package/ts/data/networkegressretirement.ts

@@ -39,10 +39,13 @@ export interface IRuntimeNetworkEgressRetirementClearance extends IRuntimeNetwor
  * 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`).
+ *    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.
+ * retirement, so it always has one — its null withdrawal, the answer to its projection's
+ * `retirement` request; 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.
@@ -67,7 +70,10 @@ export interface IRuntimeNetworkEgressRetirement extends IRuntimeNetworkNodeScop
   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. */
+  /**
+   * 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;
 }
@@ -79,8 +85,16 @@ export const runtimeNetworkEgressRetirementContract = Object.freeze({
   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,
+  /**
+   * 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);
@@ -132,28 +146,40 @@ export const computeRuntimeNetworkEgressRetirementDigest = (value: IRuntimeNetwo
 /**
  * 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:
+ * 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 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 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. It verifies no fence evidence against live state and fences no record.
+ * 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;
@@ -162,6 +188,9 @@ export const bindRuntimeNetworkProtectedAuthorityRetirement = async (
     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)
@@ -179,17 +208,25 @@ export const bindRuntimeNetworkProtectedAuthorityRetirement = async (
         && 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 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), kept));
+      requireNetwork(networkEqual(fence.clearedProjections.map(ownerKey), cleared));
     }
-    requireNetwork(retiredOwners.every(owner => !previousOwners.has(ownerKey(owner)) && !nextOwners.has(ownerKey(owner))));
+    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 };
+    return { previous, next, fences, exemptions };
   } catch { return failNetwork(); }
 };

package/ts/data/networkprojection.ts

@@ -11,6 +11,8 @@ import { hostPacketGrantsOf, snapshotHostProjection,
   type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
 import { snapshotWorkloadIngressProjection, workloadIngressPacketGrantsOf,
   type IRuntimeNetworkWorkloadIngressPacketGrant, type IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
+import { requireFirstProjectionRetirement, requireProjectionRetirement, snapshotRuntimeNetworkProjectionRetirement,
+  type IRuntimeNetworkProjectionRetirement } from './networkprojectionretirement.js';
 import { buildPrivateNetworkFqdn, composeServicePrivateNetworkDnsPolicy,
   snapshotPrivateNetwork, snapshotServicePrivateNetworks } from './privatenetwork.js';
 import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkDigest,
@@ -299,6 +301,15 @@ export interface IRuntimeNetworkProjection extends IRuntimeNetworkNodeScope {
    * It grants nothing: a workload still reaches only the endpoints it selects.
    */
   hostPlatformEndpointIds?: string[];
+  /**
+   * Present once Cloudly retires this node's egress ownership with the `withdrawn` disposition:
+   * the node withdraws its allocation protection with the null-barrier successor of its receipt
+   * chain and mints no positive receipt for it again (`IRuntimeNetworkProjectionRetirement`). Only
+   * a `cloudly` projection may carry it; it first appears naming exactly the projection's current
+   * `protectedAuthority`, and every successor carries it unchanged. Omitted, it keeps the canonical
+   * bytes and asks for nothing.
+   */
+  retirement?: IRuntimeNetworkProjectionRetirement;
   digest: TSha256Digest;
 }
 
@@ -566,10 +577,11 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
   const hasWorkloadIngress = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'workloadIngress');
   const hasHostPlatformEndpoints = captured !== null && typeof captured === 'object'
     && Object.hasOwn(captured, 'hostPlatformEndpointIds');
+  const hasRetirement = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'retirement');
   const item = networkRecord(captured, ['id', 'generation', 'previous', 'controller', 'nodeId', 'runtimeNamespace',
     'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest',
     ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : []), ...(hasWorkloadIngress ? ['workloadIngress'] : []),
-    ...(hasHostPlatformEndpoints ? ['hostPlatformEndpointIds'] : [])]);
+    ...(hasHostPlatformEndpoints ? ['hostPlatformEndpointIds'] : []), ...(hasRetirement ? ['retirement'] : [])]);
   const hostPlatformEndpointIds = hasHostPlatformEndpoints
     ? networkSorted(networkList(item.hostPlatformEndpointIds, 64, networkId), value => value) : [];
   requireNetwork(!hasHostPlatformEndpoints || hostPlatformEndpointIds.length > 0);
@@ -585,6 +597,7 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
     ...(hasHost ? { host: snapshotHostProjection(item.host) } : {}),
     ...(hasWorkloadIngress ? { workloadIngress: snapshotWorkloadIngressProjection(item.workloadIngress) } : {}),
     ...(hasHostPlatformEndpoints ? { hostPlatformEndpointIds } : {}),
+    ...(hasRetirement ? { retirement: snapshotRuntimeNetworkProjectionRetirement(item.retirement) } : {}),
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
 });
 
@@ -690,6 +703,7 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
       requireNetwork(previous.node !== current.node || previous.last < current.first);
     }
     for (const id of projection.hostPlatformEndpointIds ?? []) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
+    if (projection.retirement) requireProjectionRetirement(projection.retirement, projection.controller.kind, current);
     for (let index = 0; index < projection.endpoints.length; index++) for (let previous = 0; previous < index; previous++) {
       requireNetwork(!networkOverlaps(projection.endpoints[index].lease.ipv4.linkSubnet, projection.endpoints[previous].lease.ipv4.linkSubnet));
     }
@@ -792,6 +806,7 @@ export const admitRuntimeNetworkProjection = async (
         && (projection.router?.withdrawals.length ?? 0) === 0 && (projection.host?.withdrawals.length ?? 0) === 0
         && (projection.workloadIngress?.withdrawals.length ?? 0) === 0
         && projection.retiredLeases.length === 0 && projection.retiredHandoffs.length === 0);
+      if (projection.retirement) requireFirstProjectionRetirement(projection.retirement, projection.protectedAuthority);
       return { status: 'accepted', projection };
     }
     const previous = await validateRuntimeNetworkProjection(previousInput);
@@ -881,6 +896,10 @@ export const admitRuntimeNetworkProjection = async (
     }
     if (previous.handoff && !networkEqual(previous.handoff, projection.handoff)) requireNetwork(projection.retiredHandoffs.some(item =>
       networkEqual(item, networkReferenceOf(previous.handoff!))));
+    // A retirement request first names the current authority, then is never taken back or
+    // rewritten: every successor carries it unchanged.
+    if (previous.retirement) requireNetwork(networkEqual(projection.retirement ?? null, previous.retirement));
+    else if (projection.retirement) requireFirstProjectionRetirement(projection.retirement, projection.protectedAuthority);
     const protection = projection.protectedAuthority, oldProtection = previous.protectedAuthority;
     requireNetwork(networkEqual(protection, oldProtection) || (protection.id === oldProtection.id
       && networkEqual(protection.previous, networkReferenceOf(oldProtection))));

package/ts/data/networkprojectionretirement.ts

@@ -0,0 +1,72 @@
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
+import { captureNetwork, networkEqual, networkRecord, networkReference, networkReferenceOf, networkSafe,
+  requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * Cloudly's request that a running node withdraw its allocation protection, because its egress
+ * ownership is being retired with the `withdrawn` disposition (`INodeRuntimeRetirement`).
+ *
+ * It travels as `IRuntimeNetworkProjection.retirement`: the one authenticated, monotonic channel a
+ * node already admits and journals on every pass. The controller's signature covers it, so a node
+ * cannot invent it; the projection chain is bound to the controller epoch, node and runtime
+ * namespace, so it cannot be carried to another node or controller; and once a projection carries
+ * it, every successor carries it unchanged, so it is never taken back. A retired node never
+ * returns (`runtimeNetworkEgressRetirementContract.reentry`): no later chain of the same node can
+ * meet a stale signal.
+ *
+ * The node answers with the null-barrier successor of its protection receipt chain
+ * (`IRuntimeNetworkProtectionReceipt.nativeBarrier: null`) and mints no positive receipt for that
+ * chain again. Its native allocation-pool guard stays enforced; the answer withdraws eligibility,
+ * not protection. Nothing else withdraws: a clean stop, a crash, a reboot or being offline keeps the
+ * node's last receipt current.
+ */
+export interface IRuntimeNetworkProjectionRetirement {
+  /** The retirement row's disposition. A `lost` node never reports again, so it is never asked. */
+  disposition: 'withdrawn';
+  /**
+   * The protected authority current when Cloudly first signed the request: the projection that
+   * first carries it names exactly its own `protectedAuthority`. Its `id` names the authority chain
+   * the node's receipts belong to; the value then stays fixed while later projections carry a newer
+   * authority of the same chain, never an older one.
+   */
+  protectedAuthority: IRuntimeAuthorityReference;
+}
+
+export const runtimeNetworkProjectionRetirementContract = Object.freeze({
+  controllerKind: 'cloudly',
+  disposition: 'withdrawn',
+  firstAppearance: 'names-the-current-protected-authority',
+  latch: 'every-successor-carries-it-unchanged',
+  answer: 'null-native-barrier-receipt-successor',
+  positive: 'never-again-for-the-retiring-receipt-chain',
+} as const);
+
+/** Exact-key structural snapshot, detached from its input. */
+export const snapshotRuntimeNetworkProjectionRetirement = (value: unknown): IRuntimeNetworkProjectionRetirement => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['disposition', 'protectedAuthority']);
+  requireNetwork(item.disposition === runtimeNetworkProjectionRetirementContract.disposition);
+  return { disposition: item.disposition, protectedAuthority: networkReference(item.protectedAuthority) };
+});
+
+/**
+ * The request belongs to a `cloudly` projection and names the projection's own authority chain at
+ * a generation the projection has reached: the current authority itself, or one of its predecessors.
+ */
+export const requireProjectionRetirement = (
+  retirement: IRuntimeNetworkProjectionRetirement, controllerKind: string, current: IRuntimeNetworkProtectedAuthority,
+): void => {
+  const named = retirement.protectedAuthority;
+  requireNetwork(controllerKind === runtimeNetworkProjectionRetirementContract.controllerKind
+    && named.id === current.id && named.generation <= current.generation);
+  if (named.generation === current.generation) requireNetwork(networkEqual(named, networkReferenceOf(current)));
+};
+
+/**
+ * The request's first appearance names exactly the projection's current authority. An older
+ * generation would make the node's positive receipt under the current authority newer than the
+ * request, so the receipt gate refuses it and the withdrawal could never complete.
+ */
+export const requireFirstProjectionRetirement = (
+  retirement: IRuntimeNetworkProjectionRetirement, current: IRuntimeNetworkProtectedAuthority,
+): void => requireNetwork(networkEqual(retirement.protectedAuthority, networkReferenceOf(current)));

package/ts/data/networkprotection.ts

@@ -3,6 +3,7 @@ import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
 import type { IRuntimeNetworkNodeScope } from './networkprojection.js';
 import { snapshotRuntimeNetworkNodeScope } from './networkprojection.js';
+import { snapshotRuntimeNetworkProjectionRetirement } from './networkprojectionretirement.js';
 import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import { computeRuntimeNetworkProtectedAuthorityDigest, snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
@@ -16,7 +17,14 @@ import { captureNetwork, failNetwork, networkCanonical, networkDigest, networkEq
  * The producer owns a joined native journal covering ALL affected local egress
  * paths. nativeBarrier identifies that complete journal, never an admission ACK,
  * a single table inspection, a boot event or a caller-selected success flag.
- * A null nativeBarrier explicitly withdraws this node's allocation eligibility.
+ *
+ * A null nativeBarrier withdraws this node's allocation eligibility. A node sends it
+ * only in answer to a signed projection's `retirement` request
+ * (`IRuntimeNetworkProjectionRetirement`), and mints no positive receipt for the chain
+ * afterwards. The retained native guard outlives the node process, and the boot unit
+ * restores it before networking starts, so a clean stop, a crash, a reboot or being
+ * offline withdraws nothing: the last receipt stays current until a reconnect binds
+ * a new reporter session, whose own first positive receipt restores eligibility.
  */
 export interface IRuntimeNetworkProtectionReceipt extends IRuntimeNetworkNodeScope {
   id: string;
@@ -67,6 +75,7 @@ export const runtimeNetworkProtectionContract = Object.freeze({
   allocation: 'all-current-affected-egress-receipts-before-reserving-any-lease',
   receiptSource: 'joined-complete-native-protection-journal',
   unavailable: 'null-native-barrier-removes-allocation-eligibility',
+  withdrawal: 'only-in-answer-to-a-signed-projection-retirement',
   historical: 'retain-for-outbox-replay-never-current-allocation-eligibility',
   quarantine: 'no-release-authority',
   maximumHostAddresses: 32,
@@ -223,3 +232,45 @@ export const bindRuntimeNetworkAllocationProtection = async (
     return { protection, receipts };
   } catch { return failNetwork(); }
 };
+
+/**
+ * Receiver gate for a protection report from a node whose projection chain carries a retirement
+ * request, applied beside `admitRuntimeNetworkProtectionReceipt` with the same `previous`: the
+ * receiver's exact current receipt for the node, or null while it holds none. `retirement` is the
+ * request the receiver signed into that node's projections.
+ *
+ * The receipt must belong to the retiring authority chain. A null-barrier receipt is the answer
+ * and always passes. A positive receipt passes only while it can predate the node's admission of
+ * the request, so a receipt the node minted before it saw the request still drains from its
+ * outbox and the withdrawal behind it is never wedged:
+ *
+ * - it names an authority no newer than the one the request names; a newer one could only come
+ *   from a projection that already carried the request, since every successor carries it;
+ * - its predecessor is not a null withdrawal: once the receiver holds the node's answer, no
+ *   positive receipt follows it.
+ *
+ * A positive receipt the node minted after admitting the request against the same authority is
+ * indistinguishable from one minted before it; the node's obligation is never to mint one.
+ */
+export const bindRuntimeNetworkProtectionReceiptRetirement = async (
+  receiptValue: unknown, previousValue: unknown | null, retirementValue: unknown,
+): Promise<IRuntimeNetworkProtectionReceipt> => {
+  try {
+    const receipt = snapshotRuntimeNetworkProtectionReceipt(receiptValue);
+    const previous = previousValue === null ? null : snapshotRuntimeNetworkProtectionReceipt(previousValue);
+    const retirement = snapshotRuntimeNetworkProjectionRetirement(retirementValue);
+    requireNetwork(receipt.digest === await computeRuntimeNetworkProtectionReceiptDigest(receipt)
+      && receipt.protectedAuthority.id === retirement.protectedAuthority.id);
+    if (previous) {
+      requireNetwork(previous.digest === await computeRuntimeNetworkProtectionReceiptDigest(previous)
+        && scopeKey(previous) === scopeKey(receipt) && networkEqual(previous.controller, receipt.controller)
+        && previous.id === receipt.id && (networkEqual(receipt, previous)
+          || networkEqual(receipt.previous, networkReferenceOf(previous))));
+    }
+    if (receipt.nativeBarrier !== null) {
+      requireNetwork(receipt.protectedAuthority.generation <= retirement.protectedAuthority.generation
+        && (previous === null || previous.nativeBarrier !== null));
+    }
+    return receipt;
+  } catch { return failNetwork(); }
+};

package/ts/data/noderetirement.ts

@@ -19,7 +19,9 @@ export const nodeRuntimeRetirementDispositions = Object.freeze(['withdrawn', 'lo
  * 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.
+ * receipts, Cloudly asks it through its projection's `retirement` request
+ * (`IRuntimeNetworkProjectionRetirement`), and its Pallet answers by withdrawing 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