@serve.zone/interfaces 32.13.0 → 32.15.0

package/readme.md

@@ -1093,19 +1093,61 @@ current Spark bundle/unit/configuration and old-mode refusal evidence. This is a
 owner; it is never represented as a Pallet assignment. Downstream service holds and storage fences
 therefore depend on a live relay without requiring assignment authority that cannot exist yet.
 
-The storage bootstrap has two different authorities. `IFleetCutoverVolumeHandoffIntent` is
-Cloudly's accepted pre-switch statement of exact service, volume, source-lineage and storage-request
-identity. It also binds the exact persistent `mountIdentityDigest` and accepted source-node
-observation. It is not a ready `IRuntimeStorageClaim`. Pallet persists a root-local
-`TFleetCutoverVolumeFence` in `held` state while the cluster is draining. That state carries no
-claim, session, assignment, attachment, reservation, confirmation or execution authority, and the
-storage owner must block all those operations for the volume. After the cluster reaches `pallet`,
-Corestore performs its one-shot initial lineage/ReadWriteOnce CAS for the same mount identity under
-that held native fence and returns `IFleetCutoverCorestoreAdoptionReceipt`, which for the first time
-binds the real ready
-`IRuntimeStorageClaim` reference. Only that exact accepted receipt can consume the Pallet fence.
-This separation prevents a pre-switch fence from fabricating provider readiness merely to satisfy
-cutover ordering.
+The storage bootstrap separates desired identity, observed legacy identity and provider-proved
+physical lineage. `IFleetCutoverPreparedVolumeHandoffIntent` is Cloudly's accepted pre-switch
+statement. It carries the full sealed `IRuntimeStorageClaimIntent` and the exact persistent
+`observedMount`, including Docker source, target and combined identity digests. The Docker source
+digest commits only to Docker's exact source bytes; it is never physical lineage. The prepared
+handoff deliberately has no `sourceLineageDigest`. Corestore creates that independent commitment
+from its private device, inode and content proof while the native attachment fence is held.
+
+An administrator changes prepared handoffs through
+`prepareFleetCutoverVolumeHandoffs`. Each compare-and-swap mutation contains 1..32 combined upserts
+and explicit removals. An upsert supplies only `{ nodeId, serviceId, mountIdentityDigest, request }`,
+where `request` is the full canonical retained `ReadWriteOnce` filesystem request. Cloudly derives
+the volume, controller, organization, namespace, claim identity, evidence references and request
+digest from current owner rows. It re-derives the complete required set from the admitted manager
+task inventory and accepted local observations. The maximum possible physical set is
+`maximumTasks * maximumMountsPerOwner`, or `4096 * 32 = 131072`; node placement is already carried
+by each admitted task, so a service-count bound would undercount replicated placement.
+
+`IFleetCutoverPreparedVolumeHandoffAggregate` is a revisioned header with required/actual counts,
+state, page count and a complete set digest. It does not inline page references. Each immutable
+`IFleetCutoverPreparedVolumeHandoffPage` contains 1..32 sorted handoff references, with the owning
+`nodeId` committed beside every exact handoff revision, plus its content digest and the exact
+aggregate revision. Readers pin one aggregate, fetch every consecutive page and reject missing,
+duplicate, stale or mixed-revision pages. The set digest covers the ordered page-content digests. A
+32-entry mutation is therefore a wire bound, not a fleet volume ceiling.
+
+Spark reads one pinned page from
+`/spark/swarm-nodes/fleet-cutover-prepared-volume-handoffs`. The response carries the full immutable
+page and the authenticated node's complete full-handoff subset, including an explicit empty subset.
+Spark forwards held fences through the optional `fleetCutoverHeldVolumeFences` member available in
+every Swarm-observation state. The page's node-bearing references determine the exact subset; fetch
+responses and fence evidence must match every committed reference in page order, so omission is
+rejected and an empty report is valid only for a node with no entry on that page. The request binds
+the evidence node to the authenticated reporter. That evidence has a dedicated 128 KiB encoded
+budget and never displaces the existing census snapshots. One node's page report proves only that
+node's subset; Cloudly establishes global completeness across accepted reports for every page and
+node.
+
+Pallet persists `TFleetCutoverVolumeFence` in `held` state while draining. A hold grants no claim,
+session, assignment, attachment, reservation, confirmation or execution authority. After the real
+current runtime reaches `pallet`, Pallet obtains `IFleetCutoverStorageAdoptionGrant` through its live
+authenticated session. The grant binds the exact prepared handoff, held fence, current pallet
+runtime, session generation/epoch and observed mount. Pallet keeps its per-volume lane while it
+invokes the isolated Corestore one-shot. Corestore performs physical-lineage proof and the initial
+ready-claim CAS under its native attachment fence, without calling back into Pallet, and returns the
+full claim with `IFleetCutoverCorestoreAdoptionReceipt`. Pallet revalidates the live session, runtime
+phase and grant after that potentially long operation before consuming the durable hold. A stale
+grant leaves the hold intact.
+
+`bindFleetCutoverAdoptionToStorageClaim` joins the provider receipt and full ready claim to the
+prepared desired intent. `bindFleetCutoverStorageAdoptionBundle` additionally joins the current
+grant and consumed fence. Neither binder equates the provider physical-lineage digest with the
+observed Docker source digest or requires the provider's opaque `resourceRef` to equal Cloudly's
+volume ID. They are content checks; current owner dereferencing, peer authentication and native
+attachment fencing remain mandatory.
 
 `IFleetCutoverCoreflowRetirementEvidence` binds the real pre-switch Docker Coreflow32 relay by exact
 service ID, container ID, spec version/spec digest and image digest to accepted manager and local
@@ -1119,8 +1161,34 @@ erasure are not cutover requirements. Its exact owner generation is retained wit
 Retained recovery evidence is valid only while the released
 owner cannot consume it into live mode and the old credential remains revoked.
 
-The post-pallet order is represented without a second route or publication model. First Cloudly
-releases only the new ingress spec under an accepted empty published-port policy. It then accepts
+Before any post-pallet assignment exists, an administrator calls
+`requests.fleetcutover.prepareFleetCutoverIngress` with the exact server-created service ID,
+current `pallet` runtime, complete accepted scope and target set, held exact-cluster spec revision,
+and `expectedDesignation`. Null creates the first designation; an exact current designation
+reference permits only same-service credential rotation. Replacing the designated service is a
+different owner flow and is refused here. Cloudly's one owning transaction verifies the admin,
+same-organization live service, current references, held exact-cluster spec, zero configured and
+actual published/public ports, and absence of a conflicting designation. It generates the managed
+launcher-environment bearer privately, stores its active version and hash authority, advances the
+held spec if its secret input changed, and accepts `IFleetCutoverIngressDesignation`. The public
+designation exposes only credential ID/generation and the active `ISecretVersionReference`; neither
+it nor the response exposes the bearer, hash, private key, or any other secret value. Preparation
+requires no assignment, runtime session, ingress registration, legacy absence, publication,
+port-transfer, readback, or `IFleetCutoverIngressAuthority`.
+
+The preparation request is a closed compare-and-swap body. A replay requires the same mutation ID
+and exactly the original normalized request payload and returns the recorded designation/spec
+result; it does not renew generation, acceptance time, freshness, or authority. Every downstream
+authorization must dereference the current designation, held spec, runtime, scope, and target set.
+A historical replay response never grants current authority. `snapshotFleetCutoverIngressPreparationRequest`
+and `snapshotFleetCutoverIngressDesignation` check exact structure, reference relationships and the
+designation's canonical digest. They cannot establish admin identity, currentness, organization,
+service liveness, held state, zero ports, or absence of a conflicting designation; Cloudly owns all
+of those acceptance checks.
+
+The remaining post-pallet order is represented without a second route or publication model. First
+Cloudly releases only the designated new ingress spec under an accepted empty published-port
+policy. It then accepts
 the existing cluster-ingress registration and route-table revision, exact Spark evidence that the
 old ingress is absent, the current source and target publication records and owning port-transfer
 receipt, and a readback of the current route revision as `IFleetCutoverIngressAuthority`. Only an
@@ -1128,9 +1196,14 @@ application release may cite that authority. The legacy Docker Coretraffic insta
 remains through `switching`; the new ingress runs without public ports before exact port ownership
 moves, and applications remain held until the new authoritative route is read back.
 
-The owner methods live under `requests.fleetcutover`: administrator scope classification and
-forward phase CAS, root-local Pallet volume-fence hold/read/
-consume, one-shot Corestore adoption, ingress-authority read, and ingress/application spec release.
+The owner methods live under `requests.fleetcutover`: administrator scope classification, storage
+handoff preparation, ingress preparation and forward phase CAS; root-private prepared-fence hold,
+read and owner-triggered adoption; isolated Corestore prepared-volume adoption; ingress-authority
+read; and ingress/application spec release. Current-session adoption authorization, accepted bundle
+reporting and full claim readback live under `requests.runtimesession`. The published 32.x
+`holdFleetCutoverVolumeFence`, `consumeFleetCutoverVolumeFence` and `adoptFleetCutoverVolume`
+declarations remain for type compatibility only. Production owners do not register or adapt those
+incomplete operations; they are marked for removal at the next protocol major.
 Spark transports local and manager evidence through its existing authenticated Swarm-observation
 route, and Cloudly assembles census and Coreflow-retirement records from accepted owner state; there
 is no caller-supplied census or retirement proof endpoint.
@@ -1645,6 +1718,15 @@ or sender addresses itself.
 
 ### Runtime filesystem storage claims
 
+`data.IRuntimeStorageClaimIntent` is the non-ready Cloudly-owned precursor to a claim. It fixes the
+controller epoch, organization, cluster, node, runtime namespace, service, claim ID/generation and
+predecessor, plus `IRuntimeStorageClaimRequestedFilesystemBinding`. That requested binding fixes the
+service, full normalized retained `ReadWriteOnce` filesystem request and its canonical bare digest.
+It structurally cannot state a provider binding ID/generation, policy selection, status, observed
+generation, resource reference or granted capability. The intent is exact-schema and digest-bound
+under `serve.zone/runtime-storage-claim-intent`; it grants no assignment, session, execution or
+attachment authority.
+
 `data.IRuntimeStorageClaim` is the portable, Cloudly-issued authority for one
 ready, retained `ReadWriteOnce` filesystem binding on one cluster node. It
 names the organization, service, cluster, node, runtime namespace, controller
@@ -1669,6 +1751,14 @@ provider readiness and policy, durably admit the assignment, and obtain a
 fenced native attachment from the storage owner before a CRI mount. An absent
 claim or an unverified opaque resource reference never authorizes a mount.
 
+`data.bindRuntimeStorageClaimToIntent(claim, intent)` verifies both canonical digests and requires
+the ready claim to preserve every Cloudly-owned identity and requested filesystem fact: service,
+request ID/digest, mount path, access mode and reclaim policy. Only the full claim may add the
+storage provider's binding identity/generation, selected policy, matching observed generation,
+`ready` status, opaque resource reference and persistent single-node capabilities. This is a content
+join: callers still authenticate Cloudly and the provider, check current readiness and retain the
+native fence.
+
 `platform.storagemigration` defines the provider-neutral cutover contract for a
 named object-storage binding. Corestore atomically owns and fences the source
 binding after validating a distinct, unfenced active-object snapshot. Onebox

package/ts/00_commitinfo_data.ts

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

package/ts/data/clusternode.ts

@@ -1,11 +1,24 @@
 import * as plugins from '../plugins.js';
-import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
+import { isSha256Digest, type TSha256Digest, type TImmutableContainerPlatform } from './immutableimage.js';
 import type { ISparkNodeReportRecord } from './sparknodereport.js';
 import {
+  fleetCutoverContract,
+  snapshotFleetCutoverPreparedVolumeHandoffAggregate,
+  snapshotFleetCutoverPreparedVolumeHandoffPage,
+  snapshotFleetCutoverPreparedVolumeHandoffIntent,
+  validateFleetCutoverHeldVolumeFenceEvidencePage,
+  validateFleetCutoverPreparedVolumeHandoffAggregate,
+  validateFleetCutoverPreparedVolumeHandoffPage,
+  validateFleetCutoverPreparedVolumeHandoffIntent,
   validateFleetCutoverLocalNodeSnapshot,
   validateFleetCutoverManagerSnapshot,
+  type IFleetCutoverAcceptedEvidenceReference,
+  type IFleetCutoverHeldVolumeFenceEvidencePage,
   type IFleetCutoverLocalNodeSnapshot,
   type IFleetCutoverManagerSnapshot,
+  type IFleetCutoverPreparedVolumeHandoffAggregate,
+  type IFleetCutoverPreparedVolumeHandoffIntent,
+  type IFleetCutoverPreparedVolumeHandoffPage,
 } from './fleetcutover.js';
 import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
@@ -131,9 +144,15 @@ export const sparkSwarmNodeContracts = Object.freeze({
    */
   swarmObservation: Object.freeze({
     endpoint: '/spark/swarm-nodes/swarm-observation',
-    maxRequestBytes: 4_194_304,
+    maxRequestBytes: 4_325_376,
     maxResponseBytes: 2048,
   } as const),
+  /** Pinned immutable aggregate page plus at most 32 full handoffs for this authenticated node. */
+  fleetCutoverPreparedVolumeHandoffs: Object.freeze({
+    endpoint: '/spark/swarm-nodes/fleet-cutover-prepared-volume-handoffs',
+    maxRequestBytes: 4096,
+    maxResponseBytes: 262_144,
+  } as const),
   protocolRefusalStatus: protocolRefusalHttpStatus,
 } as const);
 
@@ -221,6 +240,8 @@ interface ISparkSwarmObservationBase {
   reporterSessionId: string;
   observationSequence: number;
   observedAt: number;
+  /** Available in every observation state; exact page membership proves an empty node subset. */
+  fleetCutoverHeldVolumeFences?: IFleetCutoverHeldVolumeFenceEvidencePage;
 }
 
 export type TSparkSwarmObservation =
@@ -288,6 +309,32 @@ export interface ISparkSwarmObservationRequest {
   observation: TSparkSwarmObservation;
 }
 
+/** First read may select current with null; all following page reads pin the exact aggregate. */
+export interface ISparkGetFleetCutoverPreparedVolumeHandoffsRequest {
+  nodeId: string;
+  nodeToken: string;
+  protocol: IProtocolOffer;
+  aggregate: IFleetCutoverAcceptedEvidenceReference | null;
+  pageIndex: number;
+}
+
+export type TSparkGetFleetCutoverPreparedVolumeHandoffsResponse =
+  | {
+      aggregate: null;
+      page: null;
+      nodeId: string;
+      nodeHandoffs: [];
+      protocol: IProtocolOffer;
+    }
+  | {
+      aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+      page: IFleetCutoverPreparedVolumeHandoffPage;
+      nodeId: string;
+      /** Exact complete authenticated-node subset committed by this page; may be empty. */
+      nodeHandoffs: IFleetCutoverPreparedVolumeHandoffIntent[];
+      protocol: IProtocolOffer;
+    };
+
 export interface ISparkSwarmObservationAcceptedReceipt {
   state: 'accepted';
   nodeId: string;
@@ -579,6 +626,8 @@ export const validateSparkSwarmObservation = async (
       'observationSequence',
       'observedAt',
       'state',
+      ...(observation.fleetCutoverHeldVolumeFences === undefined
+        ? [] : ['fleetCutoverHeldVolumeFences']),
     ];
     const expectedKeys = observation.state === 'unknown'
       ? [...commonKeys, 'reason']
@@ -619,6 +668,14 @@ export const validateSparkSwarmObservation = async (
         .includes(observation.reason as string)) {
       errors.push('Spark Swarm observation unknown reason must be canonical');
     }
+    if (observation.fleetCutoverHeldVolumeFences !== undefined) {
+      const evidenceErrors = await validateFleetCutoverHeldVolumeFenceEvidencePage(
+        observation.fleetCutoverHeldVolumeFences,
+      );
+      errors.push(...evidenceErrors.map(
+        errorArg => `Spark Swarm observation ${errorArg}`,
+      ));
+    }
     if (observation.state === 'member') {
       if (!isRuntimeIdentifier(observation.localSwarmNodeId)
         || typeof observation.controlAvailable !== 'boolean') {
@@ -694,6 +751,151 @@ const validateSparkReporterIdentity = (
   return errors;
 };
 
+const readFleetCutoverEvidenceReference = (
+  valueArg: unknown,
+): IFleetCutoverAcceptedEvidenceReference | null => {
+  if (valueArg === null) return null;
+  if (!isRuntimeRecord(valueArg)
+    || !hasExactKeys(valueArg, ['id', 'generation', 'digest'])
+    || !isRuntimeIdentifier(valueArg.id)
+    || !isPositiveSafeInteger(valueArg.generation)
+    || typeof valueArg.digest !== 'string'
+    || !isSha256Digest(valueArg.digest)) return null;
+  return {
+    id: valueArg.id,
+    generation: valueArg.generation,
+    digest: valueArg.digest,
+  };
+};
+
+export const validateSparkGetFleetCutoverPreparedVolumeHandoffsRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRuntimeRecord(requestArg)
+      || !hasExactKeys(requestArg, [
+        'nodeId', 'nodeToken', 'protocol', 'aggregate', 'pageIndex',
+      ])) {
+      return ['Spark prepared volume handoff request must use its exact schema'];
+    }
+    canonicalizeStrictJson(
+      requestArg,
+      failSparkSwarmObservationCanonicalization,
+      'Spark prepared volume handoff request',
+    );
+    const errors = validateProtocolOfferOn(
+      requestArg,
+      'Spark prepared volume handoff request protocol',
+    );
+    errors.push(...validateSparkReporterIdentity(
+      requestArg,
+      'Spark prepared volume handoff request',
+    ));
+    if ((requestArg.aggregate !== null
+      && readFleetCutoverEvidenceReference(requestArg.aggregate) === null)
+      || typeof requestArg.pageIndex !== 'number'
+      || !Number.isSafeInteger(requestArg.pageIndex)
+      || requestArg.pageIndex < 0
+      || requestArg.pageIndex >= fleetCutoverContract.maximumPreparedVolumeHandoffPages) {
+      errors.push('Spark prepared volume handoff request pin must be canonical');
+    }
+    return errors;
+  } catch {
+    return ['Spark prepared volume handoff request must be safely inspectable'];
+  }
+};
+
+export const validateSparkGetFleetCutoverPreparedVolumeHandoffsResponse = async (
+  responseArg: unknown,
+  requestArg: ISparkGetFleetCutoverPreparedVolumeHandoffsRequest,
+): Promise<string[]> => {
+  try {
+    if (validateSparkGetFleetCutoverPreparedVolumeHandoffsRequest(requestArg).length) {
+      return ['expected Spark prepared volume handoff request must be valid'];
+    }
+    if (!isRuntimeRecord(responseArg)
+      || !hasExactKeys(responseArg, [
+        'aggregate', 'page', 'nodeId', 'nodeHandoffs', 'protocol',
+      ])) {
+      return ['Spark prepared volume handoff response must use its exact schema'];
+    }
+    const canonical = canonicalizeStrictJson(
+      responseArg,
+      failSparkSwarmObservationCanonicalization,
+      'Spark prepared volume handoff response',
+    );
+    const errors = validateProtocolOfferOn(
+      responseArg,
+      'Spark prepared volume handoff response protocol',
+    );
+    if (new TextEncoder().encode(canonical).byteLength
+      > sparkSwarmNodeContracts.fleetCutoverPreparedVolumeHandoffs.maxResponseBytes) {
+      errors.push('Spark prepared volume handoff response exceeds its encoded byte bound');
+    }
+    if (responseArg.nodeId !== requestArg.nodeId) {
+      errors.push('Spark prepared volume handoff response must name the authenticated node');
+    }
+    if (responseArg.aggregate === null) {
+      if (requestArg.aggregate !== null || responseArg.page !== null
+        || !Array.isArray(responseArg.nodeHandoffs)
+        || responseArg.nodeHandoffs.length !== 0) {
+        errors.push('Spark empty prepared volume handoff response must be canonical');
+      }
+      return errors;
+    }
+    const aggregate = snapshotFleetCutoverPreparedVolumeHandoffAggregate(responseArg.aggregate);
+    const page = snapshotFleetCutoverPreparedVolumeHandoffPage(responseArg.page);
+    if ((await validateFleetCutoverPreparedVolumeHandoffAggregate(aggregate)).length
+      || aggregate.state !== 'complete') {
+      errors.push('Spark prepared volume handoff response aggregate must be complete and valid');
+    }
+    if ((await validateFleetCutoverPreparedVolumeHandoffPage(page)).length) {
+      errors.push('Spark prepared volume handoff response page must be valid');
+    }
+    if (requestArg.aggregate !== null
+      && (requestArg.aggregate.id !== aggregate.id
+        || requestArg.aggregate.generation !== aggregate.generation
+        || requestArg.aggregate.digest !== aggregate.digest)) {
+      errors.push('Spark prepared volume handoff response must preserve the aggregate pin');
+    }
+    if (page.aggregate.id !== aggregate.id
+      || page.aggregate.generation !== aggregate.generation
+      || page.aggregate.digest !== aggregate.digest
+      || page.pageIndex !== requestArg.pageIndex
+      || page.pageIndex >= aggregate.pageCount) {
+      errors.push('Spark prepared volume handoff response page must bind the requested aggregate page');
+    }
+    if (!Array.isArray(responseArg.nodeHandoffs)
+      || responseArg.nodeHandoffs.length
+        > fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries) {
+      errors.push('Spark prepared volume handoff response node subset must be bounded');
+      return errors;
+    }
+    const expectedNodeHandoffs = page.handoffs.filter(
+      referenceArg => referenceArg.nodeId === requestArg.nodeId,
+    );
+    if (responseArg.nodeHandoffs.length !== expectedNodeHandoffs.length) {
+      errors.push('Spark prepared volume handoff response must include the complete node subset');
+      return errors;
+    }
+    for (const [index, handoffArg] of responseArg.nodeHandoffs.entries()) {
+      const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+      const expected = expectedNodeHandoffs[index];
+      if ((await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+        || handoff.nodeId !== requestArg.nodeId
+        || handoff.id !== expected.id
+        || handoff.generation !== expected.generation
+        || handoff.digest !== expected.digest) {
+        errors.push('Spark prepared volume handoff response node subset must exactly match page order and authority');
+        break;
+      }
+    }
+    return errors;
+  } catch {
+    return ['Spark prepared volume handoff response must be safely inspectable'];
+  }
+};
+
 export const validateSparkSwarmObservationRequest = async (
   requestArg: unknown,
 ): Promise<string[]> => {
@@ -720,6 +922,11 @@ export const validateSparkSwarmObservationRequest = async (
       requestArg,
       'Spark Swarm observation request',
     ));
+    if (isRuntimeRecord(requestArg.observation)
+      && isRuntimeRecord(requestArg.observation.fleetCutoverHeldVolumeFences)
+      && requestArg.observation.fleetCutoverHeldVolumeFences.nodeId !== requestArg.nodeId) {
+      errors.push('Spark Swarm held volume fence evidence must name the authenticated node');
+    }
     return errors;
   } catch {
     return ['Spark Swarm observation request must be safely inspectable'];