@serve.zone/interfaces 32.17.0 → 32.19.0

package/ts/data/sparklegacyretirement.ts

@@ -1,6 +1,6 @@
 import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
 import type { TSha256Digest } from './immutableimage.js';
-import { isReleaseVersion } from '../private/releaseversion.js';
+import { isReleaseVersion } from './releaseversion.js';
 import {
   captureNetwork,
   networkCounter,
@@ -50,6 +50,18 @@ export interface ISparkNodeBundleIdentity {
   unitDigest: TSha256Digest;
 }
 
+/**
+ * What became of the released configuration source once this node stopped reading it.
+ *
+ * A tuple beside the union, exactly like `sparkLegacyRuntimeModes`: a reader that has to name the
+ * two states — a form, a migration, a refusal message — reads them from the contract instead of
+ * restating two string literals the contract could later disagree with.
+ */
+export const sparkLegacyConfigurationDispositions = ['retained-inert', 'removed'] as const;
+
+export type TSparkLegacyConfigurationDisposition =
+  typeof sparkLegacyConfigurationDispositions[number];
+
 /**
  * The released key-value configuration source, by digest and disposition only.
  *
@@ -63,7 +75,7 @@ export interface ISparkLegacyConfigurationState {
   /** SHA-256 of the exact source bytes this node imported, once, under its fenced read. */
   sourceSha256: string;
   /** On disk and read by nothing, or unlinked. Erasure is not a cutover requirement. */
-  disposition: 'retained-inert' | 'removed';
+  disposition: TSparkLegacyConfigurationDisposition;
 }
 
 /**
@@ -138,6 +150,46 @@ export const sparkLegacyRetirementRefusals = Object.freeze([
 
 export type TSparkLegacyRetirementRefusal = typeof sparkLegacyRetirementRefusals[number];
 
+/**
+ * What the server did with the statement one observation carried, answered on that observation's
+ * own accepted receipt.
+ *
+ * The statement is judged against records, not against the message: a malformed one is already
+ * refused by `validateSparkLegacyRuntimeRetirement` before any of this, so everything left is a
+ * fact about this node's history. That is why a refusal here does not reject the observation —
+ * the node's liveness and census are true whatever its released runtime states — and why an
+ * accepted observation is the only place this outcome appears.
+ *
+ * `generation` is the revision both node-owned records stand at once the observation is accepted:
+ * `accepted` advanced it, `restated` is the replay that renewed nothing and left it where it was.
+ * A refusal carries no generation, because the counter a refused node has to reconcile with is
+ * its own `ownerGeneration`, which it already holds.
+ */
+export type TSparkLegacyRetirementOutcome =
+  | {
+      state: 'accepted';
+      /** The revision this observation advanced both records to. */
+      generation: number;
+    }
+  | {
+      state: 'restated';
+      /** The revision that stands; this observation added nothing to it. */
+      generation: number;
+    }
+  | {
+      state: 'refused';
+      refusal: TSparkLegacyRetirementRefusal;
+      /**
+       * Always false, and stated anyway.
+       *
+       * Every refusal of this family answers one exact statement, so resending it cannot change
+       * the answer; a server-side race is refused one level up, as the observation's own
+       * `acceptance-race`. It travels on the wire for the reason the rejected receipt carries its
+       * own flag: a node that meets a refusal name a later minor added still learns it must stop.
+       */
+      retryable: false;
+    };
+
 const fail = (): never => { throw new Error('Spark legacy retirement contract rejected.'); };
 const safe = <T>(operationArg: () => T): T => {
   try { return operationArg(); } catch { return fail(); }
@@ -165,9 +217,16 @@ const legacyRuntimeMode = (valueArg: unknown): TSparkLegacyRuntimeMode => {
 
 const configurationDisposition = (
   valueArg: unknown,
-): ISparkLegacyConfigurationState['disposition'] => {
-  requireNetwork(valueArg === 'retained-inert' || valueArg === 'removed');
-  return valueArg;
+): TSparkLegacyConfigurationDisposition => {
+  requireNetwork(sparkLegacyConfigurationDispositions
+    .includes(valueArg as TSparkLegacyConfigurationDisposition));
+  return valueArg as TSparkLegacyConfigurationDisposition;
+};
+
+const retirementRefusal = (valueArg: unknown): TSparkLegacyRetirementRefusal => {
+  requireNetwork(sparkLegacyRetirementRefusals
+    .includes(valueArg as TSparkLegacyRetirementRefusal));
+  return valueArg as TSparkLegacyRetirementRefusal;
 };
 
 /** Structural copy only; whether the tree it describes is installed is the node's to observe. */
@@ -223,6 +282,31 @@ export const validateSparkLegacyRuntimeRetirement = (valueArg: unknown): string[
   } catch { return ['Spark legacy runtime retirement must use its exact canonical schema']; }
 };
 
+/** Exact-key per state, like every other shape here: an outcome states one answer and no other. */
+export const snapshotSparkLegacyRetirementOutcome = (
+  valueArg: unknown,
+): TSparkLegacyRetirementOutcome => safe(() => {
+  const captured = captureNetwork(valueArg);
+  requireNetwork(captured !== null && typeof captured === 'object');
+  const state = (captured as Record<string, unknown>).state;
+  requireNetwork(state === 'accepted' || state === 'restated' || state === 'refused');
+  if (state === 'refused') {
+    const value = networkRecord(captured, ['state', 'refusal', 'retryable']);
+    requireNetwork(value.retryable === false);
+    return { state, refusal: retirementRefusal(value.refusal), retryable: false };
+  }
+  const value = networkRecord(captured, ['state', 'generation']);
+  return { state, generation: networkCounter(value.generation) };
+});
+
+/** Synchronous for the same reason: the receipt that carries it is what a reader binds. */
+export const validateSparkLegacyRetirementOutcome = (valueArg: unknown): string[] => {
+  try {
+    snapshotSparkLegacyRetirementOutcome(valueArg);
+    return [];
+  } catch { return ['Spark legacy retirement outcome 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: unknown,

package/ts/data/sparknodereport.ts

@@ -1,4 +1,4 @@
-import { isReleaseVersion } from '../private/releaseversion.js';
+import { isReleaseVersion } from './releaseversion.js';
 import { readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';

package/ts/protocol.ts

@@ -8,7 +8,7 @@ import {
   maximumReleaseVersionLength,
   parseReleaseVersion,
   type IReleaseVersion,
-} from './private/releaseversion.js';
+} from './data/releaseversion.js';
 
 /**
  * The contract this build speaks: the installed `@serve.zone/interfaces` release.