@serve.zone/interfaces 32.16.0 → 32.17.0

package/dist_ts/data/sparklegacyretirement.js

@@ -0,0 +1,206 @@
+import { isReleaseVersion } from '../private/releaseversion.js';
+import { captureNetwork, networkCounter, networkDigest, networkEqual, networkHash, networkId, networkNodeId, networkRecord, networkReference, networkRevision, requireNetwork, } from '../private/networkcontract.js';
+/** The two runtimes a released Spark could be put into by its `mode` configuration key. */
+export const sparkLegacyRuntimeModes = ['cloudly', 'coreflow-node'];
+/**
+ * Which Docker services a released mode owns, sorted, so a refusal names a mode instead of
+ * restating a set. A record over the mode union: a mode cannot be added without naming its
+ * services, and a reader can never meet a mode whose services it does not know.
+ */
+export const sparkLegacyRuntimeModeServices = Object.freeze({
+    'cloudly': Object.freeze(['cloudly']),
+    'coreflow-node': Object.freeze(['coreflow', 'corestore', 'coretraffic']),
+});
+export const sparkLegacyRetirementContract = Object.freeze({
+    modeRefusalDigestDomain: 'serve.zone/spark-legacy-mode-refusal',
+    configurationRetirementDigestDomain: 'serve.zone/spark-legacy-configuration-retirement',
+});
+/** Every reason Cloudly answers instead of advancing a node's legacy retirement state. */
+export const sparkLegacyRetirementRefusals = Object.freeze([
+    /** The observed owner generation is below the accepted one. */
+    'legacy-retirement-generation-stale',
+    /** The observed owner generation equals the accepted one and states something else. */
+    'legacy-retirement-generation-conflict',
+    /** A node imported one source once; another source digest describes another host. */
+    'legacy-retirement-source-changed',
+    /** A removed source cannot become a retained one. */
+    'legacy-retirement-disposition-reversed',
+    /** The stated bundle is below the release whose refusal this server accepts as real. */
+    'legacy-retirement-bundle-below-minimum',
+]);
+const fail = () => { throw new Error('Spark legacy retirement contract rejected.'); };
+const safe = (operationArg) => {
+    try {
+        return operationArg();
+    }
+    catch {
+        return fail();
+    }
+};
+const sha256Hex = (valueArg) => {
+    requireNetwork(typeof valueArg === 'string' && /^[a-f0-9]{64}$/.test(valueArg));
+    return valueArg;
+};
+const sourceCommit = (valueArg) => {
+    requireNetwork(typeof valueArg === 'string' && /^[a-f0-9]{40}$/.test(valueArg));
+    return valueArg;
+};
+const releaseVersion = (valueArg) => {
+    requireNetwork(isReleaseVersion(valueArg));
+    return valueArg;
+};
+const legacyRuntimeMode = (valueArg) => {
+    requireNetwork(sparkLegacyRuntimeModes.includes(valueArg));
+    return valueArg;
+};
+const configurationDisposition = (valueArg) => {
+    requireNetwork(valueArg === 'retained-inert' || valueArg === 'removed');
+    return valueArg;
+};
+/** Structural copy only; whether the tree it describes is installed is the node's to observe. */
+export const snapshotSparkNodeBundleIdentity = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'version', 'sourceCommit', 'manifestSha256', 'unitName', 'unitDigest',
+    ]);
+    return {
+        version: releaseVersion(value.version),
+        sourceCommit: sourceCommit(value.sourceCommit),
+        manifestSha256: sha256Hex(value.manifestSha256),
+        unitName: networkId(value.unitName),
+        unitDigest: networkDigest(value.unitDigest),
+    };
+});
+export const snapshotSparkLegacyConfigurationState = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'ownerGeneration', 'sourceSha256', 'disposition',
+    ]);
+    return {
+        ownerGeneration: networkCounter(value.ownerGeneration),
+        sourceSha256: sha256Hex(value.sourceSha256),
+        disposition: configurationDisposition(value.disposition),
+    };
+});
+export const snapshotSparkLegacyRuntimeRetirement = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'refusedMode', 'bundle', 'configuration',
+    ]);
+    return {
+        refusedMode: legacyRuntimeMode(value.refusedMode),
+        bundle: snapshotSparkNodeBundleIdentity(value.bundle),
+        configuration: snapshotSparkLegacyConfigurationState(value.configuration),
+    };
+});
+/**
+ * Synchronous because the member carries no digest: the observation that transports it is
+ * digested as a whole, so a second domain here would only be a second thing to keep in step.
+ */
+export const validateSparkLegacyRuntimeRetirement = (valueArg) => {
+    try {
+        snapshotSparkLegacyRuntimeRetirement(valueArg);
+        return [];
+    }
+    catch {
+        return ['Spark legacy runtime retirement must use its exact canonical schema'];
+    }
+};
+/** The revision rule every accepted receipt of this contract obeys, read once for both of them. */
+const retirementReceiptBase = (valueArg, ownKeysArg) => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'id', 'generation', 'previous', 'clusterId', 'nodeId', 'observation', 'reporterSessionId',
+        'observationSequence', 'acceptedAt', 'digest',
+        ...ownKeysArg,
+    ]);
+    const { id, generation, previous } = networkRevision(value);
+    return {
+        base: {
+            id,
+            generation,
+            previous,
+            clusterId: networkId(value.clusterId),
+            nodeId: networkNodeId(value.nodeId),
+            observation: networkReference(value.observation),
+            reporterSessionId: networkId(value.reporterSessionId),
+            observationSequence: networkCounter(value.observationSequence),
+            acceptedAt: networkCounter(value.acceptedAt),
+            digest: networkDigest(value.digest),
+        },
+        record: value,
+    };
+};
+export const snapshotSparkLegacyModeRefusal = (valueArg) => safe(() => {
+    const { base, record } = retirementReceiptBase(valueArg, ['refusedMode', 'bundle']);
+    return {
+        ...base,
+        refusedMode: legacyRuntimeMode(record.refusedMode),
+        bundle: snapshotSparkNodeBundleIdentity(record.bundle),
+    };
+});
+export const computeSparkLegacyModeRefusalDigest = async (valueArg) => networkHash(sparkLegacyRetirementContract.modeRefusalDigestDomain, snapshotSparkLegacyModeRefusal(valueArg));
+export const validateSparkLegacyModeRefusal = async (valueArg) => {
+    try {
+        const value = snapshotSparkLegacyModeRefusal(valueArg);
+        return value.digest === await computeSparkLegacyModeRefusalDigest(value)
+            ? [] : ['Spark legacy mode refusal digest does not match'];
+    }
+    catch {
+        return ['Spark legacy mode refusal must use its exact canonical schema'];
+    }
+};
+export const snapshotSparkLegacyConfigurationRetirement = (valueArg) => safe(() => {
+    const { base, record } = retirementReceiptBase(valueArg, ['configuration']);
+    return { ...base, configuration: snapshotSparkLegacyConfigurationState(record.configuration) };
+});
+export const computeSparkLegacyConfigurationRetirementDigest = async (valueArg) => networkHash(sparkLegacyRetirementContract.configurationRetirementDigestDomain, snapshotSparkLegacyConfigurationRetirement(valueArg));
+export const validateSparkLegacyConfigurationRetirement = async (valueArg) => {
+    try {
+        const value = snapshotSparkLegacyConfigurationRetirement(valueArg);
+        return value.digest === await computeSparkLegacyConfigurationRetirementDigest(value)
+            ? [] : ['Spark legacy configuration retirement digest does not match'];
+    }
+    catch {
+        return ['Spark legacy configuration retirement must use its exact canonical schema'];
+    }
+};
+/**
+ * Whether one observed configuration state is a legal successor of the accepted one.
+ *
+ * `null` is a node's first accepted state. A replay states the accepted generation again and is
+ * therefore not an advance: it renews nothing, which is what keeps `acceptedAt` and the named
+ * observation from aging forward on a node that has stopped changing.
+ */
+export const advancesSparkLegacyConfigurationState = (currentArg, nextArg) => {
+    const next = snapshotSparkLegacyConfigurationState(nextArg);
+    if (currentArg === null)
+        return true;
+    if (next.sourceSha256 !== currentArg.sourceSha256)
+        return false;
+    if (next.ownerGeneration <= currentArg.ownerGeneration)
+        return false;
+    return !(currentArg.disposition === 'removed' && next.disposition !== 'removed');
+};
+/**
+ * Joins the two accepted receipts a Coreflow retirement cites to the one observation they were
+ * derived from.
+ *
+ * Content join only. Whether each receipt is its node's current revision, and whether the
+ * observation it names is still fresh, remain Cloudly's to decide against its own records.
+ */
+export const bindSparkLegacyRetirement = async (modeRefusalArg, configurationRetirementArg) => {
+    try {
+        const modeRefusal = snapshotSparkLegacyModeRefusal(modeRefusalArg);
+        const configurationRetirement = snapshotSparkLegacyConfigurationRetirement(configurationRetirementArg);
+        if ((await validateSparkLegacyModeRefusal(modeRefusal)).length
+            || (await validateSparkLegacyConfigurationRetirement(configurationRetirement)).length)
+            fail();
+        requireNetwork(modeRefusal.clusterId === configurationRetirement.clusterId
+            && modeRefusal.nodeId === configurationRetirement.nodeId
+            && modeRefusal.reporterSessionId === configurationRetirement.reporterSessionId
+            && modeRefusal.observationSequence === configurationRetirement.observationSequence
+            && networkEqual(modeRefusal.observation, configurationRetirement.observation));
+        return { modeRefusal, configurationRetirement };
+    }
+    catch {
+        return fail();
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3BhcmtsZWdhY3lyZXRpcmVtZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zcGFya2xlZ2FjeXJldGlyZW1lbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDaEUsT0FBTyxFQUNMLGNBQWMsRUFDZCxjQUFjLEVBQ2QsYUFBYSxFQUNiLFlBQVksRUFDWixXQUFXLEVBQ1gsU0FBUyxFQUNULGFBQWEsRUFDYixhQUFhLEVBQ2IsZ0JBQWdCLEVBQ2hCLGVBQWUsRUFDZixjQUFjLEdBQ2YsTUFBTSwrQkFBK0IsQ0FBQztBQUV2QywyRkFBMkY7QUFDM0YsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsQ0FBQyxTQUFTLEVBQUUsZUFBZSxDQUFVLENBQUM7QUFJN0U7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsU0FBUyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUNyQyxlQUFlLEVBQUUsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLFVBQVUsRUFBRSxXQUFXLEVBQUUsYUFBYSxDQUFDLENBQUM7Q0FDWixDQUFDLENBQUM7QUF5RmhFLE1BQU0sQ0FBQyxNQUFNLDZCQUE2QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDekQsdUJBQXVCLEVBQUUsc0NBQXNDO0lBQy9ELG1DQUFtQyxFQUFFLGtEQUFrRDtDQUMvRSxDQUFDLENBQUM7QUFFWiwwRkFBMEY7QUFDMUYsTUFBTSxDQUFDLE1BQU0sNkJBQTZCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN6RCwrREFBK0Q7SUFDL0Qsb0NBQW9DO0lBQ3BDLHVGQUF1RjtJQUN2Rix1Q0FBdUM7SUFDdkMscUZBQXFGO0lBQ3JGLGtDQUFrQztJQUNsQyxxREFBcUQ7SUFDckQs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

package/dist_ts/requests/cluster.d.ts

@@ -1,5 +1,6 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type * as relayCredentialInterfaces from '../data/clusterrelaycredential.js';
 import type * as clusterVpnInterfaces from '../data/clustervpn.js';
 import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
 import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
@@ -116,6 +117,59 @@ export interface IReq_Relay_Cloudly_RegisterClusterRelay extends plugins.typedre
     request: clusterInterfaces.IRegisterClusterRelayRequest;
     response: clusterInterfaces.IRegisterClusterRelayResponse;
 }
+/**
+ * Mints a cluster's relay credential, or rotates it at its exact current generation.
+ *
+ * Only the verified credential is read from the caller: a credential mutation trusts no identity
+ * member a caller states about itself. The bearer is never in the answer; it is delivered as the
+ * encrypted secret version `credential.delivery` names. The first mint also records the shared
+ * authority the cluster still carries, so a replacement never exists without a named predecessor.
+ * Cloudly refuses with one of `data.clusterRelayCredentialRefusals`.
+ */
+export interface IReq_Admin_Cloudly_MutateClusterRelayCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_MutateClusterRelayCredential> {
+    method: 'mutateClusterRelayCredential';
+    request: {
+        identity: userInterfaces.IIdentityCredential;
+        mutation: relayCredentialInterfaces.TClusterRelayCredentialMutation;
+    };
+    response: relayCredentialInterfaces.IClusterRelayCredentialMutationResult;
+}
+/**
+ * One cluster's relay authority chain as Cloudly records it: the relay credential, the shared
+ * authority it replaces and the current accepted registration, each `null` while no record exists.
+ *
+ * Liveness is not here. It is a fact of a socket, which `getClusterRelayRegistrations` answers and
+ * which Cloudly checks for itself before it accepts a retirement.
+ */
+export interface IReq_Any_Cloudly_GetClusterRelayCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetClusterRelayCredential> {
+    method: 'getClusterRelayCredential';
+    request: {
+        identity: userInterfaces.IIdentityCredential;
+        clusterId: string;
+    };
+    response: {
+        credential: relayCredentialInterfaces.IClusterRelayCredential | null;
+        legacy: relayCredentialInterfaces.IClusterLegacyRelayCredential | null;
+        registration: clusterInterfaces.IClusterRelayAcceptedRegistration | null;
+    };
+}
+/**
+ * Revokes a cluster's shared pre-relay authority, which is the last step of replacing it.
+ *
+ * Its own request rather than a mutation of the relay credential, because it is the one step that
+ * removes authority: Cloudly accepts it only while the named replacement is the current relay
+ * credential, the named registration is current and was made under that replacement, and a
+ * verified socket carries that registration. Every other answer is one of
+ * `data.clusterRelayCredentialRefusals`.
+ */
+export interface IReq_Admin_Cloudly_RetireLegacyClusterRelayCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_RetireLegacyClusterRelayCredential> {
+    method: 'retireLegacyClusterRelayCredential';
+    request: {
+        identity: userInterfaces.IIdentityCredential;
+        retirement: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementRequest;
+    };
+    response: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementResult;
+}
 /**
  * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
  *

package/dist_ts/requests/cluster.js

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

package/package.json

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

package/readme.md

@@ -1198,6 +1198,10 @@ source is identified by SHA-256 and may be `retained-inert` or `removed`; deleti
 erasure are not cutover requirements. Its exact owner generation is retained with that disposition.
 Retained recovery evidence is valid only while the released
 owner cannot consume it into live mode and the old credential remains revoked.
+`relay.credential`, `relay.acceptedRegistration`, `legacy.credential` and `legacy.invalidation`
+reference the records of [Cluster Relay Credential](#cluster-relay-credential). The old-mode
+refusal, the configuration CAS and the Spark bundle and unit identity are Spark-owned and come
+from [Spark Legacy Runtime Retirement](#spark-legacy-runtime-retirement).
 
 Before any post-pallet assignment exists, an administrator calls
 `requests.fleetcutover.prepareFleetCutoverIngress` with the exact server-created service ID,
@@ -2027,12 +2031,13 @@ with `clusterRelayCertificateDomainName(relay)`, which returns the origin's host
 Cloudly issues the certificate for and owns the A record for. An origin naming an address literal
 therefore has no issuable certificate.
 
-`data.clusterRelayUndispatchedRefusals` names the three registration refusals that end a relay's
-custody — `relay-cluster-not-enabled`, `relay-node-foreign` and `relay-sequence-not-advancing` —
-with `data.TClusterRelayUndispatchedRefusal` as their union. Each is Cloudly reading its own
-records and stating that it does not dispatch to this relay, so a relay that hears one drops what
-it holds for its nodes instead of waiting. A refusal that only says Cloudly could not verify the
-relay states nothing about dispatch and is deliberately not in the list.
+`data.clusterRelayUndispatchedRefusals` names the four registration refusals that end a relay's
+custody — `relay-cluster-not-enabled`, `relay-node-foreign`, `relay-sequence-not-advancing` and
+`relay-credential-generation-stale` — with `data.TClusterRelayUndispatchedRefusal` as their union.
+Each is Cloudly reading its own records and stating that it does not dispatch to this relay, so a
+relay that hears one drops what it holds for its nodes instead of waiting. A refusal that only
+says Cloudly could not verify the relay states nothing about dispatch and is deliberately not in
+the list.
 
 ```typescript
 const relay: data.IClusterRelay = {
@@ -2109,6 +2114,133 @@ const registrationReasons = data.validateRegisterClusterRelayRequest(registratio
 How the relay reaches each node's Corestore is part of the same document: see
 [Corestore Through The Relay](#corestore-through-the-relay).
 
+### Cluster Relay Credential
+
+A cluster's relay authenticates with its own generation-bearing credential instead of the shared
+cluster authority every cluster-side component used before it. `IClusterRelayCredential` is public
+metadata: the cluster, a `generation` that advances by one per accepted mint or rotation, the
+machine `userId` it authenticates as, and `delivery`, the `ISecretVersionReference` of the
+immutable encrypted version the bearer was delivered as. No record, receipt, request or response
+of this contract carries a bearer, a hash or key material, and every reader is exact-keyed, so a
+peer that adds a secret-looking member is refused rather than copied.
+
+The credential authenticates the cluster's whole control-plane session, exactly what the shared
+authority authenticated, so a relay changes one credential and keeps every call it makes. The gain
+is a generation Cloudly fences each socket against and an authority it can rotate and retire on
+its own; the scope is not narrower. One cluster has one relay and therefore one credential record,
+and it never expires by itself: rotation is its lifecycle.
+
+`mutateClusterRelayCredential { identity, mutation }` takes `TClusterRelayCredentialMutation`.
+`ensure` requires `expectedGeneration: null` and an absent record; `rotate` requires the exact
+current generation, never a minimum. The caller retains the complete request and its `mutationId`
+across retries: the identical body answers with the original result and `replayed: true` without
+renewing delivery, generation or authority, and a changed body fails closed. The first mint also
+records the shared authority the cluster still carries as `IClusterLegacyRelayCredential`, so a
+replacement never exists without a named predecessor. Rotation has no overlap: the previous
+generation stops authenticating at commit, and a relay still holding it hears
+`relay-credential-generation-stale`, drops what it holds for its nodes, reads the delivered version
+and reconnects. There is no revocation of the relay credential, because a rotation already covers
+a compromised one without a state in which the cluster has no relay authority at all.
+
+An accepted `registerClusterRelay` answers with two references beside the origin and the offer:
+`credential`, the generation Cloudly authenticated the socket as, and `acceptedRegistration`, the
+record that acceptance wrote. The relay states no generation of its own — the registration request
+is unchanged — because a relay naming its own generation would be asserting its own rank.
+`IClusterRelayAcceptedRegistration` is that record: the registration facts the served read shape
+also carries, its own `id`, a `generation` that advances once per acceptance, the `credential`
+reference and a `digest`. Liveness is not part of it. `IClusterRelayRegistration` keeps exactly its
+published members, the facts plus `live`.
+
+`retireLegacyClusterRelayCredential { identity, retirement }` revokes the shared authority, and is
+the last step of replacing it. `IClusterLegacyRelayCredentialRetirementRequest` carries
+compare-and-swap inputs only: the exact `expectedLegacyGeneration`, the `replacement` credential
+reference and the `acceptedRegistration` reference the caller observed. Cloudly dereferences both
+against its own current records, requires the registration to have been made under that
+replacement, and requires a verified live socket carrying it; a caller can state no liveness or
+proof of its own. Acceptance writes the one-shot `IClusterLegacyRelayCredentialInvalidation`
+(`generation: 1`) and advances the legacy record to `state: 'revoked'` naming it. The invalidation
+names the legacy record at the generation before the revocation and the record names the
+invalidation after it, so neither digest covers the other's.
+`data.clusterRelayCredentialRefusals` names every other answer, with
+`data.TClusterRelayCredentialRefusal` as their union. `getClusterRelayCredential { identity,
+clusterId }` reads the chain: the credential, the legacy record and the current accepted
+registration, each `null` while no record exists.
+
+Each digest-bearing record has a `snapshot…`, `compute…Digest` and `validate…` function under its
+own digest domain in `data.clusterRelayCredentialContract` and `data.clusterRelayContract`.
+`bindClusterLegacyRelayCredentialInvalidation(invalidation, legacyCredential,
+acceptedRegistration)` joins an invalidation to the legacy record it revoked — the active record
+it names or that record's revoked successor — and to a registration whose `credential` equals the
+invalidation's `replacement`. It is a content check; dereferencing each record as current and
+requiring the live socket remain Cloudly's.
+
+All three requests read only the verified `IIdentityCredential`, never an identity member a caller
+states about itself.
+
+### Spark Legacy Runtime Retirement
+
+The Spark-owned half of `IFleetCutoverCoreflowRetirementEvidence` — the refused old mode, the
+configuration compare-and-swap, and the bundle and unit identity — is transported on the Swarm
+observation a node already posts. There is no route, request or endpoint for it. That is forced
+rather than preferred: the evidence requires `relay.nodeObservation` and `spark.observation` to be
+the identical accepted reference, so these facts must reach Cloudly on the very observation that
+carries the node's Docker census.
+
+`data.ISparkLegacyRuntimeRetirement` is the optional observation member, available in every
+observation state because it describes the host and not its Docker daemon. It is
+`{ refusedMode, bundle, configuration }` and nothing else. It names no node: Cloudly binds it to
+the reporter it already authenticated, so there is no node identity on it to disagree with. It
+carries no digest of its own either — `computeSparkSwarmObservationDigest` canonicalizes the whole
+observation, so a second domain here would only be a second thing to keep in step.
+
+`refusedMode` is one of `data.sparkLegacyRuntimeModes`, the two runtimes a released Spark could be
+put into by its `mode` configuration key. `data.sparkLegacyRuntimeModeServices` is the record over
+that union naming the Docker services each mode owns, so a refusal states a mode and a reader
+derives the set. `data.ISparkNodeBundleIdentity { version, sourceCommit, manifestSha256, unitName,
+unitDigest }` is read back from the installed tree and the installed unit file, never from the
+running process's own build constants: a build can state its own version, it cannot state that the
+host will start that same code again. `data.ISparkLegacyConfigurationState { ownerGeneration,
+sourceSha256, disposition }` names the released key-value source by digest alone. No decoded member
+of that file is representable in any shape here, because it carries the node's released bearer and
+its jump code; `sourceSha256` covers the whole file, whose smallest unguessable part is a 256-bit
+token. `disposition` is `retained-inert` or `removed`; erasure is not a cutover requirement.
+
+Cloudly accepts an observation first and then advances two of its own records, which is what the
+evidence's two references point at. `data.ISparkLegacyModeRefusal` and
+`data.ISparkLegacyConfigurationRetirement` are revisions, not one-shot receipts: a node restates
+both on every observation, a bundle upgrade changes what the boot path is, and a disposition
+changes once. Both carry the accepted observation they were derived from, its reporter session and
+its sequence, and both obey the revision rule every record of this package obeys — a first
+generation has no predecessor and a later one names exactly the generation before it. The
+configuration record carries two counters on purpose: its own `generation` is contiguous because it
+is this record's revision, while `configuration.ownerGeneration` is the node's own and may skip,
+since an observation that never arrived must not look like a skipped revision.
+
+`advancesSparkLegacyConfigurationState(current, next)` is the compare-and-swap rule, `null` for a
+node's first accepted state: the same `sourceSha256`, a strictly higher `ownerGeneration`, and no
+return from `removed` to `retained-inert`. Restating the accepted generation is a replay and
+therefore not an advance, which is what keeps `acceptedAt` and the named observation from aging
+forward on a node that has stopped changing. `data.sparkLegacyRetirementRefusals` names every other
+answer, with `data.TSparkLegacyRetirementRefusal` as their union.
+`bindSparkLegacyRetirement(modeRefusal, configurationRetirement)` joins the two receipts a
+retirement cites, requiring the same cluster, node, reporter session, sequence and accepted
+observation. It is a content check; whether each receipt is its node's current revision remains
+Cloudly's.
+
+An omitted member is not a refusal and advances nothing, so the existence of these records is not
+what makes a retirement honest — the freshness of the observation they name is. Assembly must
+require that observation to still be inside `fleetCutoverContract.observationFreshnessMs`, exactly
+as `IFleetCutoverSparkObservationReference` already does, or a node that stopped refusing would go
+on looking retired.
+
+Cloudly reads this member before Spark writes it. Every observation validator in this package is
+exact-key, so a server built against an earlier minor refuses the whole observation rather than
+ignoring a member it does not know — the peers of a session kind are upgraded before the side that
+starts depending on the later minor, and the `minimumPeerVersion` of that session kind is raised in
+the same commit that starts depending on it. A Spark that begins stating this member therefore
+raises its `sparkSwarmNode` minimum alone, which requires one minimum per session kind rather than
+one shared across a deployable's offers.
+
 ### Cluster VPN Hub And Network
 
 A cluster's relay is also that cluster's managed VPN hub: every node of the cluster dials it, and

package/ts/00_commitinfo_data.ts

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