@serve.zone/interfaces 32.14.0 → 32.15.0

package/ts/data/fleetcutover.ts

@@ -6,6 +6,16 @@ import type {
   IRuntimeAuthorityReference,
 } from './runtimeassignment.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
+import type { IRuntimeStorageClaim, IRuntimeStorageClaimIntent } from './runtimestorageclaim.js';
+import {
+  bindRuntimeStorageClaimToIntent,
+  snapshotRuntimeStorageClaim,
+  snapshotRuntimeStorageClaimIntent,
+  validateRuntimeStorageClaim,
+  validateRuntimeStorageClaimIntent,
+} from './runtimestorageclaim.js';
+import type { IAppStoreFilesystemStorageRequest } from '../appstore/types.js';
+import { normalizeStorageRequest } from '../platform/storage.js';
 import type { ISecretVersionReference } from './secret.js';
 import {
   canonicalizeStrictJson,
@@ -281,6 +291,101 @@ export interface IFleetCutoverVolumeHandoffIntent {
   digest: TSha256Digest;
 }
 
+export interface IFleetCutoverPersistentVolumeMountDescriptor
+extends IFleetCutoverMountDescriptor {
+  type: 'volume';
+  classification: 'persistent-volume';
+  readOnly: false;
+}
+
+/**
+ * Cloudly-owned desired handoff prepared from authenticated legacy observations. Observed Docker
+ * source identity is not physical storage lineage; Corestore proves lineage later under the held
+ * native attachment fence.
+ */
+export interface IFleetCutoverPreparedVolumeHandoffIntent {
+  id: string;
+  generation: number;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  observedMount: IFleetCutoverPersistentVolumeMountDescriptor;
+  claimIntent: IRuntimeStorageClaimIntent;
+  runtime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  legacyStorageEvidence: IFleetCutoverAcceptedEvidenceReference;
+  sourceNodeObservation: IFleetCutoverAcceptedEvidenceReference;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+export interface IFleetCutoverPreparedVolumeHandoffUpsert {
+  nodeId: string;
+  serviceId: string;
+  mountIdentityDigest: TSha256Digest;
+  request: IAppStoreFilesystemStorageRequest & {
+    accessMode: 'ReadWriteOnce';
+    reclaimPolicy: 'retain';
+  };
+}
+
+/** One bounded CAS mutation; the durable aggregate may contain many such 32-entry batches. */
+export interface IFleetCutoverPreparedVolumeHandoffMutation {
+  mutationId: string;
+  clusterId: string;
+  currentRuntime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  expectedAggregate: IFleetCutoverAcceptedEvidenceReference | null;
+  upserts: IFleetCutoverPreparedVolumeHandoffUpsert[];
+  removals: IFleetCutoverAcceptedEvidenceReference[];
+}
+
+/**
+ * Revisioned header for one complete expected set. It intentionally contains no page references:
+ * immutable pages bind back to this exact revision, avoiding an aggregate/page digest cycle.
+ */
+export interface IFleetCutoverPreparedVolumeHandoffAggregate {
+  id: string;
+  generation: number;
+  previous: IFleetCutoverAcceptedEvidenceReference | null;
+  clusterId: string;
+  runtime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  state: 'incomplete' | 'complete';
+  requiredHandoffCount: number;
+  handoffCount: number;
+  pageCount: number;
+  handoffSetDigest: TSha256Digest;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/** One immutable 1..32-entry page pinned to one aggregate revision. */
+export interface IFleetCutoverPreparedVolumeHandoffPage {
+  id: string;
+  generation: 1;
+  aggregate: IFleetCutoverAcceptedEvidenceReference;
+  pageIndex: number;
+  handoffs: IFleetCutoverPreparedVolumeHandoffPageReference[];
+  handoffSetPageDigest: TSha256Digest;
+  digest: TSha256Digest;
+}
+
+/** Immutable page membership commits both the handoff revision and its owning physical node. */
+export interface IFleetCutoverPreparedVolumeHandoffPageReference
+extends IFleetCutoverAcceptedEvidenceReference {
+  nodeId: string;
+}
+
+export interface IFleetCutoverPreparedVolumeHandoffPageSetEntry {
+  pageIndex: number;
+  handoffSetPageDigest: TSha256Digest;
+}
+
 interface IFleetCutoverVolumeFenceBase {
   id: string;
   generation: number;
@@ -328,6 +433,40 @@ export interface IFleetCutoverCorestoreAdoptionReceipt {
   digest: TSha256Digest;
 }
 
+/** Current-session Cloudly grant for one post-Pallet adoption attempt. */
+export interface IFleetCutoverStorageAdoptionGrant {
+  id: string;
+  generation: number;
+  previous: IFleetCutoverAcceptedEvidenceReference | null;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  observedMount: IFleetCutoverPersistentVolumeMountDescriptor;
+  runtime: IClusterRuntimeReference & { phase: 'pallet' };
+  session: IRuntimeSessionBinding;
+  handoffIntent: IFleetCutoverAcceptedEvidenceReference;
+  palletFence: IFleetCutoverAcceptedEvidenceReference;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/** Exact result Pallet persists only after revalidating the current grant following adoption. */
+export interface IFleetCutoverStorageAdoptionBundle {
+  grant: IFleetCutoverStorageAdoptionGrant;
+  fence: Extract<TFleetCutoverVolumeFence, { state: 'consumed' }>;
+  adoption: IFleetCutoverCorestoreAdoptionReceipt;
+  claim: IRuntimeStorageClaim;
+}
+
+/** One authenticated Spark reporter's complete bounded subset of a full immutable aggregate page. */
+export interface IFleetCutoverHeldVolumeFenceEvidencePage {
+  aggregate: IFleetCutoverAcceptedEvidenceReference;
+  page: IFleetCutoverPreparedVolumeHandoffPage;
+  nodeId: string;
+  fences: Extract<TFleetCutoverVolumeFence, { state: 'held' }>[];
+}
+
 export interface IFleetCutoverCoreflowRetirementEvidence {
   id: string;
   generation: number;
@@ -497,6 +636,11 @@ export const fleetCutoverContract = Object.freeze({
   maximumNodes: 1024,
   maximumContainersPerNode: 512,
   maximumMountsPerOwner: 32,
+  maximumPreparedVolumeHandoffMutationEntries: 32,
+  /** Every admitted task has one node placement and at most 32 mounts: 4096 * 32. */
+  maximumPreparedVolumeHandoffs: 4096 * 32,
+  maximumPreparedVolumeHandoffPages: (4096 * 32) / 32,
+  maximumHeldVolumeFenceEvidenceBytes: 131_072,
   maximumClassifications: 512,
   observationFreshnessMs: 300_000,
   mountSourceIdentityDigestDomain: 'serve.zone/fleet-cutover-mount-source-identity',
@@ -508,8 +652,16 @@ export const fleetCutoverContract = Object.freeze({
   censusDigestDomain: 'serve.zone/fleet-cutover-census',
   scopeDigestDomain: 'serve.zone/fleet-cutover-scope',
   volumeHandoffDigestDomain: 'serve.zone/fleet-cutover-volume-handoff',
+  preparedVolumeHandoffDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff',
+  preparedVolumeHandoffAggregateDigestDomain:
+    'serve.zone/fleet-cutover-prepared-volume-handoff-aggregate',
+  preparedVolumeHandoffPageContentDigestDomain:
+    'serve.zone/fleet-cutover-prepared-volume-handoff-page-content',
+  preparedVolumeHandoffPageDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff-page',
+  preparedVolumeHandoffSetDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff-set',
   volumeFenceDigestDomain: 'serve.zone/fleet-cutover-volume-fence',
   corestoreAdoptionDigestDomain: 'serve.zone/fleet-cutover-corestore-adoption',
+  storageAdoptionGrantDigestDomain: 'serve.zone/fleet-cutover-storage-adoption-grant',
   coreflowRetirementDigestDomain: 'serve.zone/fleet-cutover-coreflow-retirement',
   ingressDesignationDigestDomain: 'serve.zone/fleet-cutover-ingress-designation',
   ingressAuthorityDigestDomain: 'serve.zone/fleet-cutover-ingress-authority',
@@ -1053,6 +1205,13 @@ export const fleetCutoverEvidenceReferenceOf = (
   digest: valueArg.digest,
 });
 
+export const fleetCutoverPreparedVolumeHandoffPageReferenceOf = (
+  valueArg: { id: string; generation: number; digest: TSha256Digest; nodeId: string },
+): IFleetCutoverPreparedVolumeHandoffPageReference => ({
+  ...fleetCutoverEvidenceReferenceOf(valueArg),
+  nodeId: networkNodeId(valueArg.nodeId),
+});
+
 export const snapshotFleetCutoverAcceptedEvidenceReference = (
   valueArg: unknown,
 ): IFleetCutoverAcceptedEvidenceReference => safe(() => reference(captureNetwork(valueArg)));
@@ -1209,6 +1368,383 @@ export const computeFleetCutoverVolumeHandoffDigest = async (
   snapshotFleetCutoverVolumeHandoffIntent(valueArg),
 );
 
+const persistentVolumeMountDescriptor = (
+  valueArg: unknown,
+): IFleetCutoverPersistentVolumeMountDescriptor => {
+  const value = mountDescriptor(valueArg);
+  requireNetwork(value.type === 'volume'
+    && value.classification === 'persistent-volume'
+    && value.readOnly === false);
+  return value as IFleetCutoverPersistentVolumeMountDescriptor;
+};
+
+const preparedVolumeHandoff = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffIntent => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'clusterId', 'nodeId', 'serviceId', 'volumeId', 'observedMount',
+    'claimIntent', 'runtime', 'scope', 'targetSet', 'legacyStorageEvidence',
+    'sourceNodeObservation', 'acceptedAt', 'digest',
+  ]);
+  const clusterId = networkId(value.clusterId);
+  const nodeId = networkNodeId(value.nodeId);
+  const serviceId = networkId(value.serviceId);
+  const observedMount = persistentVolumeMountDescriptor(value.observedMount);
+  const claimIntent = snapshotRuntimeStorageClaimIntent(value.claimIntent);
+  const runtime = runtimeReference(value.runtime);
+  const targetSet = targetSetReference(value.targetSet);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId
+    && claimIntent.clusterId === clusterId
+    && claimIntent.nodeId === nodeId
+    && claimIntent.serviceId === serviceId);
+  return {
+    id: networkId(value.id),
+    generation: networkCounter(value.generation),
+    clusterId,
+    nodeId,
+    serviceId,
+    volumeId: networkId(value.volumeId),
+    observedMount,
+    claimIntent,
+    runtime: runtime as IFleetCutoverPreparedVolumeHandoffIntent['runtime'],
+    scope: reference(value.scope),
+    targetSet,
+    legacyStorageEvidence: reference(value.legacyStorageEvidence),
+    sourceNodeObservation: reference(value.sourceNodeObservation),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffIntent = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffIntent => safe(
+  () => preparedVolumeHandoff(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffIntent(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffIntent = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffIntent(valueArg);
+    if ((await validateRuntimeStorageClaimIntent(value.claimIntent)).length) {
+      return ['fleet cutover prepared volume handoff claim intent is invalid'];
+    }
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff must use its exact canonical schema'];
+  }
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffMutation = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffMutation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'mutationId', 'clusterId', 'currentRuntime', 'scope', 'targetSet', 'expectedAggregate',
+    'upserts', 'removals',
+  ]);
+  const clusterId = networkId(value.clusterId);
+  const currentRuntime = runtimeReference(value.currentRuntime);
+  const targetSet = targetSetReference(value.targetSet);
+  requireNetwork(currentRuntime.id === clusterId && currentRuntime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId);
+  const requestKeys = new Set<string>();
+  const placementKeys = new Set<string>();
+  const upserts = networkSorted(networkList(
+    value.upserts,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const item = networkRecord(itemArg, [
+        'nodeId', 'serviceId', 'mountIdentityDigest', 'request',
+      ]);
+      const nodeId = networkNodeId(item.nodeId);
+      const serviceId = networkId(item.serviceId);
+      const mountIdentityDigest = networkDigest(item.mountIdentityDigest);
+      const request = normalizeStorageRequest(item.request);
+      requireNetwork(request.kind === 'filesystem'
+        && request.accessMode === 'ReadWriteOnce'
+        && request.reclaimPolicy === 'retain');
+      const requestKey = `${nodeId}\u0000${serviceId}\u0000${request.id}`;
+      const placementKey = `${nodeId}\u0000${serviceId}\u0000${mountIdentityDigest}`;
+      requireNetwork(!requestKeys.has(requestKey) && !placementKeys.has(placementKey));
+      requestKeys.add(requestKey);
+      placementKeys.add(placementKey);
+      return {
+        nodeId,
+        serviceId,
+        mountIdentityDigest,
+        request: request as IFleetCutoverPreparedVolumeHandoffUpsert['request'],
+      };
+    },
+  ), itemArg => `${itemArg.nodeId}\u0000${itemArg.serviceId}\u0000${itemArg.mountIdentityDigest}`);
+  const removals = networkSorted(networkList(
+    value.removals,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    reference,
+  ), itemArg => `${itemArg.id}\u0000${String(itemArg.generation).padStart(16, '0')}\u0000${itemArg.digest}`);
+  requireNetwork(upserts.length + removals.length > 0
+    && upserts.length + removals.length
+      <= fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId,
+    currentRuntime: currentRuntime as IFleetCutoverPreparedVolumeHandoffMutation['currentRuntime'],
+    scope: reference(value.scope),
+    targetSet,
+    expectedAggregate: value.expectedAggregate === null ? null : reference(value.expectedAggregate),
+    upserts,
+    removals,
+  };
+});
+
+const preparedVolumeHandoffAggregate = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffAggregate => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'previous', 'clusterId', 'runtime', 'scope', 'targetSet', 'state',
+    'requiredHandoffCount', 'handoffCount', 'pageCount', 'handoffSetDigest', 'acceptedAt',
+    'digest',
+  ]);
+  const id = networkId(value.id);
+  const generation = networkCounter(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireNetwork(generation === 1
+    ? previous === null
+    : previous?.id === id && previous.generation === generation - 1);
+  const clusterId = networkId(value.clusterId);
+  const runtime = runtimeReference(value.runtime);
+  const targetSet = targetSetReference(value.targetSet);
+  const state = literal(['incomplete', 'complete'] as const, value.state);
+  const requiredHandoffCount = nonNegative(value.requiredHandoffCount);
+  const handoffCount = nonNegative(value.handoffCount);
+  const pageCount = nonNegative(value.pageCount);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId
+    && requiredHandoffCount <= fleetCutoverContract.maximumPreparedVolumeHandoffs
+    && handoffCount <= fleetCutoverContract.maximumPreparedVolumeHandoffs
+    && pageCount <= fleetCutoverContract.maximumPreparedVolumeHandoffPages
+    && pageCount === Math.ceil(handoffCount
+      / fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries)
+    && (state === 'complete') === (requiredHandoffCount === handoffCount));
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    runtime: runtime as IFleetCutoverPreparedVolumeHandoffAggregate['runtime'],
+    scope: reference(value.scope),
+    targetSet,
+    state,
+    requiredHandoffCount,
+    handoffCount,
+    pageCount,
+    handoffSetDigest: networkDigest(value.handoffSetDigest),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffAggregate = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffAggregate => safe(
+  () => preparedVolumeHandoffAggregate(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffAggregateDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffAggregateDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffAggregate(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffAggregate = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffAggregate(valueArg);
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffAggregateDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff aggregate digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff aggregate must use its exact canonical schema'];
+  }
+};
+
+const preparedVolumeHandoffPage = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffPage => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'aggregate', 'pageIndex', 'handoffs', 'handoffSetPageDigest', 'digest',
+  ]);
+  requireNetwork(value.generation === 1);
+  const handoffs = networkSorted(networkList(
+    value.handoffs,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const item = networkRecord(itemArg, ['id', 'generation', 'digest', 'nodeId']);
+      return fleetCutoverPreparedVolumeHandoffPageReferenceOf({
+        ...reference({ id: item.id, generation: item.generation, digest: item.digest }),
+        nodeId: networkNodeId(item.nodeId),
+      });
+    },
+  ), itemArg => `${itemArg.id}\u0000${String(itemArg.generation).padStart(16, '0')}\u0000${itemArg.digest}`);
+  const pageIndex = nonNegative(value.pageIndex);
+  requireNetwork(handoffs.length > 0
+    && pageIndex < fleetCutoverContract.maximumPreparedVolumeHandoffPages);
+  return {
+    id: networkId(value.id),
+    generation: 1,
+    aggregate: reference(value.aggregate),
+    pageIndex,
+    handoffs,
+    handoffSetPageDigest: networkDigest(value.handoffSetPageDigest),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffPage = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffPage => safe(
+  () => preparedVolumeHandoffPage(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffPageContentDigest = async (
+  pageIndexArg: unknown,
+  handoffsArg: unknown,
+): Promise<TSha256Digest> => {
+  const page = preparedVolumeHandoffPage({
+    id: 'FleetCutoverPreparedVolumeHandoffPage:content',
+    generation: 1,
+    aggregate: { id: 'FleetCutoverPreparedVolumeHandoffAggregate:content', generation: 1,
+      digest: `sha256:${'0'.repeat(64)}` },
+    pageIndex: pageIndexArg,
+    handoffs: handoffsArg,
+    handoffSetPageDigest: `sha256:${'0'.repeat(64)}`,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+  return canonicalDigest(fleetCutoverContract.preparedVolumeHandoffPageContentDigestDomain, {
+    pageIndex: page.pageIndex,
+    handoffs: page.handoffs,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+};
+
+export const computeFleetCutoverPreparedVolumeHandoffPageDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffPageDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffPage(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffPage = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffPage(valueArg);
+    if (value.handoffSetPageDigest
+      !== await computeFleetCutoverPreparedVolumeHandoffPageContentDigest(
+        value.pageIndex,
+        value.handoffs,
+      )) {
+      return ['fleet cutover prepared volume handoff page content digest does not match'];
+    }
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffPageDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff page digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff page must use its exact canonical schema'];
+  }
+};
+
+export const computeFleetCutoverPreparedVolumeHandoffSetDigest = async (
+  entriesArg: unknown,
+): Promise<TSha256Digest> => safe(async () => {
+  const entries = networkSorted(networkList(
+    captureNetwork(entriesArg),
+    fleetCutoverContract.maximumPreparedVolumeHandoffPages,
+    itemArg => {
+      const item = networkRecord(itemArg, ['pageIndex', 'handoffSetPageDigest']);
+      return {
+        pageIndex: nonNegative(item.pageIndex),
+        handoffSetPageDigest: networkDigest(item.handoffSetPageDigest),
+      };
+    },
+  ), itemArg => String(itemArg.pageIndex).padStart(8, '0'));
+  requireNetwork(entries.every((entryArg, indexArg) => entryArg.pageIndex === indexArg));
+  return canonicalDigest(fleetCutoverContract.preparedVolumeHandoffSetDigestDomain, {
+    entries,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+});
+
+/**
+ * Full pinned-set proof. The caller must supply every page for the exact aggregate revision; a
+ * node-local subset or a mixed revision can never satisfy this binder.
+ */
+export const bindFleetCutoverPreparedVolumeHandoffPages = async (
+  aggregateArg: unknown,
+  pagesArg: unknown,
+): Promise<{
+  aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+  pages: IFleetCutoverPreparedVolumeHandoffPage[];
+}> => {
+  const aggregate = snapshotFleetCutoverPreparedVolumeHandoffAggregate(aggregateArg);
+  if ((await validateFleetCutoverPreparedVolumeHandoffAggregate(aggregate)).length) fail();
+  const pages = safe(() => {
+    requireNetwork(Array.isArray(pagesArg)
+      && Object.getPrototypeOf(pagesArg) === Array.prototype
+      && pagesArg.length <= fleetCutoverContract.maximumPreparedVolumeHandoffPages);
+    const keys = Reflect.ownKeys(pagesArg);
+    requireNetwork(keys.length === pagesArg.length + 1);
+    const result: IFleetCutoverPreparedVolumeHandoffPage[] = [];
+    for (let index = 0; index < pagesArg.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(pagesArg, String(index));
+      requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+      result.push(snapshotFleetCutoverPreparedVolumeHandoffPage(descriptor.value));
+    }
+    return networkSorted(result, itemArg => String(itemArg.pageIndex).padStart(8, '0'));
+  });
+  requireNetwork(pages.length === aggregate.pageCount);
+  let handoffCount = 0;
+  const seen = new Set<string>();
+  let previousHandoffKey: string | null = null;
+  for (const [index, page] of pages.entries()) {
+    requireNetwork(page.pageIndex === index
+      && page.aggregate.id === aggregate.id
+      && page.aggregate.generation === aggregate.generation
+      && page.aggregate.digest === aggregate.digest
+      && !(await validateFleetCutoverPreparedVolumeHandoffPage(page)).length);
+    const expectedLength = index < pages.length - 1
+      ? fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries
+      : aggregate.handoffCount
+        % fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries
+          || fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries;
+    requireNetwork(page.handoffs.length === expectedLength);
+    handoffCount += page.handoffs.length;
+    for (const handoff of page.handoffs) {
+      const key = `${handoff.id}\u0000${handoff.generation}\u0000${handoff.digest}`;
+      requireNetwork(!seen.has(key) && (previousHandoffKey === null || previousHandoffKey < key));
+      seen.add(key);
+      previousHandoffKey = key;
+    }
+  }
+  const entries = pages.map(page => ({
+    pageIndex: page.pageIndex,
+    handoffSetPageDigest: page.handoffSetPageDigest,
+  }));
+  requireNetwork(handoffCount === aggregate.handoffCount
+    && aggregate.handoffSetDigest
+      === await computeFleetCutoverPreparedVolumeHandoffSetDigest(entries));
+  return { aggregate, pages };
+};
+
 const volumeFence = (valueArg: unknown): TFleetCutoverVolumeFence => {
   requireNetwork(valueArg !== null && typeof valueArg === 'object');
   const state = (valueArg as Record<string, unknown>).state;
@@ -1324,6 +1860,45 @@ export const bindFleetCutoverAdoptionToVolumeFence = (
   return { adoption, fence };
 });
 
+/**
+ * Joins the accepted adoption result to the full handoff and provider-ready claim content.
+ * Native attachment fencing and accepted-record dereferencing remain owner checks.
+ */
+export const bindFleetCutoverAdoptionToStorageClaim = async (
+  adoptionArg: unknown,
+  handoffArg: unknown,
+  claimArg: unknown,
+): Promise<{
+  adoption: IFleetCutoverCorestoreAdoptionReceipt;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+  claim: IRuntimeStorageClaim;
+}> => {
+  try {
+    const adoption = snapshotFleetCutoverCorestoreAdoptionReceipt(adoptionArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const claim = snapshotRuntimeStorageClaim(claimArg);
+    if ((await validateFleetCutoverCorestoreAdoptionReceipt(adoption)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateRuntimeStorageClaim(claim)).length) fail();
+    await bindRuntimeStorageClaimToIntent(claim, handoff.claimIntent);
+    requireNetwork(adoption.clusterId === handoff.clusterId
+      && adoption.nodeId === handoff.nodeId
+      && adoption.serviceId === handoff.serviceId
+      && adoption.volumeId === handoff.volumeId
+      && adoption.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && adoption.handoffIntent.id === handoff.id
+      && adoption.handoffIntent.generation === handoff.generation
+      && adoption.handoffIntent.digest === handoff.digest
+      && adoption.claim.id === claim.id
+      && adoption.claim.generation === claim.generation
+      && adoption.claim.digest === claim.digest
+      && adoption.acceptedAt >= handoff.acceptedAt);
+    return { adoption, handoff, claim };
+  } catch {
+    return fail();
+  }
+};
+
 export const validateFleetCutoverVolumeHandoffIntent = async (valueArg: unknown): Promise<string[]> => {
   try {
     const value = snapshotFleetCutoverVolumeHandoffIntent(valueArg);
@@ -1373,6 +1948,273 @@ const runtimeSession = (valueArg: unknown): IRuntimeSessionBinding => {
   };
 };
 
+const storageAdoptionGrant = (valueArg: unknown): IFleetCutoverStorageAdoptionGrant => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'previous', 'clusterId', 'nodeId', 'serviceId', 'volumeId',
+    'observedMount', 'runtime', 'session', 'handoffIntent', 'palletFence', 'acceptedAt',
+    'digest',
+  ]);
+  const id = networkId(value.id);
+  const generation = networkCounter(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireNetwork(generation === 1
+    ? previous === null
+    : previous?.id === id && previous.generation === generation - 1);
+  const clusterId = networkId(value.clusterId);
+  const nodeId = networkNodeId(value.nodeId);
+  const runtime = runtimeReference(value.runtime);
+  const session = runtimeSession(value.session);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'pallet'
+    && session.clusterId === clusterId
+    && session.nodeId === nodeId
+    && session.controller.kind === 'cloudly');
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    nodeId,
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    observedMount: persistentVolumeMountDescriptor(value.observedMount),
+    runtime: runtime as IFleetCutoverStorageAdoptionGrant['runtime'],
+    session,
+    handoffIntent: reference(value.handoffIntent),
+    palletFence: reference(value.palletFence),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverStorageAdoptionGrant = (
+  valueArg: unknown,
+): IFleetCutoverStorageAdoptionGrant => safe(
+  () => storageAdoptionGrant(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverStorageAdoptionGrantDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.storageAdoptionGrantDigestDomain,
+  snapshotFleetCutoverStorageAdoptionGrant(valueArg),
+);
+
+export const validateFleetCutoverStorageAdoptionGrant = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverStorageAdoptionGrant(valueArg);
+    return value.digest === await computeFleetCutoverStorageAdoptionGrantDigest(value)
+      ? [] : ['fleet cutover storage adoption grant digest does not match'];
+  } catch {
+    return ['fleet cutover storage adoption grant must use its exact canonical schema'];
+  }
+};
+
+/** Content join only; the controller must still prove this is the live current session and phase. */
+export const bindFleetCutoverStorageAdoptionGrant = async (
+  grantArg: unknown,
+  handoffArg: unknown,
+  heldFenceArg: unknown,
+): Promise<{
+  grant: IFleetCutoverStorageAdoptionGrant;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+  fence: Extract<TFleetCutoverVolumeFence, { state: 'held' }>;
+}> => {
+  try {
+    const grant = snapshotFleetCutoverStorageAdoptionGrant(grantArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const fence = snapshotFleetCutoverVolumeFence(heldFenceArg);
+    if ((await validateFleetCutoverStorageAdoptionGrant(grant)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateFleetCutoverVolumeFence(fence)).length) fail();
+    requireNetwork(fence.state === 'held'
+      && grant.clusterId === handoff.clusterId
+      && grant.nodeId === handoff.nodeId
+      && grant.serviceId === handoff.serviceId
+      && grant.volumeId === handoff.volumeId
+      && grant.observedMount.type === handoff.observedMount.type
+      && grant.observedMount.classification === handoff.observedMount.classification
+      && grant.observedMount.sourceIdentityDigest === handoff.observedMount.sourceIdentityDigest
+      && grant.observedMount.targetIdentityDigest === handoff.observedMount.targetIdentityDigest
+      && grant.observedMount.readOnly === handoff.observedMount.readOnly
+      && grant.observedMount.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && grant.handoffIntent.id === handoff.id
+      && grant.handoffIntent.generation === handoff.generation
+      && grant.handoffIntent.digest === handoff.digest
+      && grant.palletFence.id === fence.id
+      && grant.palletFence.generation === fence.generation
+      && grant.palletFence.digest === fence.digest
+      && fence.clusterId === handoff.clusterId
+      && fence.nodeId === handoff.nodeId
+      && fence.serviceId === handoff.serviceId
+      && fence.volumeId === handoff.volumeId
+      && fence.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && fence.handoffIntent.id === handoff.id
+      && fence.handoffIntent.generation === handoff.generation
+      && fence.handoffIntent.digest === handoff.digest
+      && fence.heldRuntime.id === handoff.runtime.id
+      && fence.heldRuntime.phase === handoff.runtime.phase
+      && fence.heldRuntime.generation === handoff.runtime.generation
+      && grant.session.controller.id === handoff.claimIntent.controller.id
+      && grant.session.controller.epoch === handoff.claimIntent.controller.epoch
+      && grant.session.runtimeNamespace === handoff.claimIntent.runtimeNamespace
+      && grant.acceptedAt >= fence.heldAt);
+    return { grant, handoff, fence };
+  } catch {
+    return fail();
+  }
+};
+
+export const snapshotFleetCutoverStorageAdoptionBundle = (
+  valueArg: unknown,
+): IFleetCutoverStorageAdoptionBundle => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'grant', 'fence', 'adoption', 'claim',
+  ]);
+  const fence = snapshotFleetCutoverVolumeFence(value.fence);
+  requireNetwork(fence.state === 'consumed');
+  return {
+    grant: snapshotFleetCutoverStorageAdoptionGrant(value.grant),
+    fence,
+    adoption: snapshotFleetCutoverCorestoreAdoptionReceipt(value.adoption),
+    claim: snapshotRuntimeStorageClaim(value.claim),
+  };
+});
+
+/**
+ * Binds the complete post-adoption content. Physical lineage remains the provider-produced
+ * adoption digest and is deliberately never equated to the observed Docker source identity.
+ */
+export const bindFleetCutoverStorageAdoptionBundle = async (
+  valueArg: unknown,
+  handoffArg: unknown,
+): Promise<{
+  bundle: IFleetCutoverStorageAdoptionBundle;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+}> => {
+  try {
+    const bundle = snapshotFleetCutoverStorageAdoptionBundle(valueArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const { grant, fence, adoption, claim } = bundle;
+    if ((await validateFleetCutoverStorageAdoptionGrant(grant)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateFleetCutoverVolumeFence(fence)).length
+      || (await validateFleetCutoverCorestoreAdoptionReceipt(adoption)).length
+      || (await validateRuntimeStorageClaim(claim)).length) fail();
+    await bindRuntimeStorageClaimToIntent(claim, handoff.claimIntent);
+    requireNetwork(grant.clusterId === handoff.clusterId
+      && grant.nodeId === handoff.nodeId
+      && grant.serviceId === handoff.serviceId
+      && grant.volumeId === handoff.volumeId
+      && grant.observedMount.type === handoff.observedMount.type
+      && grant.observedMount.classification === handoff.observedMount.classification
+      && grant.observedMount.sourceIdentityDigest === handoff.observedMount.sourceIdentityDigest
+      && grant.observedMount.targetIdentityDigest === handoff.observedMount.targetIdentityDigest
+      && grant.observedMount.readOnly === handoff.observedMount.readOnly
+      && grant.observedMount.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && grant.session.controller.id === handoff.claimIntent.controller.id
+      && grant.session.controller.epoch === handoff.claimIntent.controller.epoch
+      && grant.session.runtimeNamespace === handoff.claimIntent.runtimeNamespace
+      && grant.handoffIntent.id === handoff.id
+      && grant.handoffIntent.generation === handoff.generation
+      && grant.handoffIntent.digest === handoff.digest
+      && fence.clusterId === grant.clusterId
+      && fence.nodeId === grant.nodeId
+      && fence.serviceId === grant.serviceId
+      && fence.volumeId === grant.volumeId
+      && fence.mountIdentityDigest === grant.observedMount.mountIdentityDigest
+      && fence.handoffIntent.id === handoff.id
+      && fence.handoffIntent.generation === handoff.generation
+      && fence.handoffIntent.digest === handoff.digest
+      && fence.previous !== null
+      && fence.previous.id === grant.palletFence.id
+      && fence.previous.generation === grant.palletFence.generation
+      && fence.previous.digest === grant.palletFence.digest
+      && fence.consumedRuntime.id === grant.runtime.id
+      && fence.consumedRuntime.phase === grant.runtime.phase
+      && fence.consumedRuntime.generation === grant.runtime.generation
+      && adoption.clusterId === handoff.clusterId
+      && adoption.nodeId === handoff.nodeId
+      && adoption.serviceId === handoff.serviceId
+      && adoption.volumeId === handoff.volumeId
+      && adoption.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && adoption.handoffIntent.id === handoff.id
+      && adoption.handoffIntent.generation === handoff.generation
+      && adoption.handoffIntent.digest === handoff.digest
+      && adoption.palletFence.id === grant.palletFence.id
+      && adoption.palletFence.generation === grant.palletFence.generation
+      && adoption.palletFence.digest === grant.palletFence.digest
+      && adoption.claim.id === claim.id
+      && adoption.claim.generation === claim.generation
+      && adoption.claim.digest === claim.digest
+      && fence.adoptionReceipt.id === adoption.id
+      && fence.adoptionReceipt.generation === adoption.generation
+      && fence.adoptionReceipt.digest === adoption.digest
+      && fence.claim.id === claim.id
+      && fence.claim.generation === claim.generation
+      && fence.claim.digest === claim.digest
+      && adoption.acceptedAt >= grant.acceptedAt
+      && fence.consumedAt >= adoption.acceptedAt);
+    return { bundle, handoff };
+  } catch {
+    return fail();
+  }
+};
+
+export const snapshotFleetCutoverHeldVolumeFenceEvidencePage = (
+  valueArg: unknown,
+): IFleetCutoverHeldVolumeFenceEvidencePage => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['aggregate', 'page', 'nodeId', 'fences']);
+  const aggregate = reference(value.aggregate);
+  const page = preparedVolumeHandoffPage(value.page);
+  const nodeId = networkNodeId(value.nodeId);
+  requireNetwork(page.aggregate.id === aggregate.id
+    && page.aggregate.generation === aggregate.generation
+    && page.aggregate.digest === aggregate.digest);
+  const pageHandoffs = page.handoffs.filter(itemArg => itemArg.nodeId === nodeId);
+  const fences = networkSorted(networkList(
+    value.fences,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const fence = volumeFence(itemArg);
+      requireNetwork(fence.state === 'held' && fence.nodeId === nodeId);
+      return fence;
+    },
+  ), itemArg => `${itemArg.handoffIntent.id}\u0000${itemArg.handoffIntent.generation}\u0000${itemArg.handoffIntent.digest}`);
+  requireNetwork(fences.length === pageHandoffs.length
+    && fences.every((fenceArg, indexArg) => {
+      const handoff = pageHandoffs[indexArg];
+      return fenceArg.handoffIntent.id === handoff.id
+        && fenceArg.handoffIntent.generation === handoff.generation
+        && fenceArg.handoffIntent.digest === handoff.digest;
+    }));
+  return { aggregate, page, nodeId, fences };
+});
+
+export const validateFleetCutoverHeldVolumeFenceEvidencePage = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverHeldVolumeFenceEvidencePage(valueArg);
+    if (new TextEncoder().encode(canonicalizeStrictJson(value, fail)).byteLength
+      > fleetCutoverContract.maximumHeldVolumeFenceEvidenceBytes) {
+      return ['fleet cutover held volume fence evidence page exceeds its encoded byte bound'];
+    }
+    if ((await validateFleetCutoverPreparedVolumeHandoffPage(value.page)).length) {
+      return ['fleet cutover held volume fence evidence page is not a valid immutable page'];
+    }
+    for (const fence of value.fences) {
+      if ((await validateFleetCutoverVolumeFence(fence)).length) {
+        return ['fleet cutover held volume fence evidence contains an invalid held fence'];
+      }
+    }
+    return [];
+  } catch {
+    return ['fleet cutover held volume fence evidence page must use its exact canonical schema'];
+  }
+};
+
 export const snapshotFleetCutoverCoreflowRetirementEvidence = (
   valueArg: unknown,
 ): IFleetCutoverCoreflowRetirementEvidence => safe(() => {