@serve.zone/interfaces 32.13.0 → 32.15.0

package/dist_ts/data/fleetcutover.d.ts

@@ -2,6 +2,9 @@ import type { TSha256Digest } from './immutableimage.js';
 import type { IClusterRuntimeReference, TClusterRuntimePhase } from './clusterruntime.js';
 import type { IRuntimeAssignmentReference, IRuntimeAuthorityReference } from './runtimeassignment.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
+import type { IRuntimeStorageClaim, IRuntimeStorageClaimIntent } from './runtimestorageclaim.js';
+import type { IAppStoreFilesystemStorageRequest } from '../appstore/types.js';
+import type { ISecretVersionReference } from './secret.js';
 /**
  * A server-owned accepted record reference. It contains no bearer, secret, or proof boolean.
  * Consumers dereference it against the current owner record before applying policy.
@@ -209,6 +212,97 @@ export interface IFleetCutoverVolumeHandoffIntent {
     acceptedAt: number;
     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;
@@ -257,6 +351,43 @@ export interface IFleetCutoverCorestoreAdoptionReceipt {
     acceptedAt: number;
     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;
@@ -302,6 +433,50 @@ export interface IFleetCutoverCoreflowRetirementEvidence {
     acceptedAt: number;
     digest: TSha256Digest;
 }
+/**
+ * Administrator intent to prepare the one explicitly designated ingress service. The caller
+ * supplies only compare-and-swap inputs; Cloudly owns credential generation and acceptance.
+ */
+export interface IFleetCutoverIngressPreparationRequest {
+    mutationId: string;
+    clusterId: string;
+    ingressServiceId: string;
+    currentRuntime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    expectedSpecRevision: number;
+    /** Null for creation; the exact current designation for same-service credential rotation. */
+    expectedDesignation: IFleetCutoverAcceptedEvidenceReference | null;
+}
+/** Public identity of the active ingress credential generation; it contains no credential value. */
+export interface IFleetCutoverIngressCredentialReference {
+    credentialId: string;
+    generation: number;
+    secretVersion: ISecretVersionReference;
+}
+/**
+ * Cloudly's accepted pre-assignment designation. This grants no assignment, session,
+ * registration, publication, port-transfer, or post-registration ingress authority.
+ */
+export interface IFleetCutoverIngressDesignation {
+    id: string;
+    generation: number;
+    previous: IFleetCutoverAcceptedEvidenceReference | null;
+    clusterId: string;
+    runtime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    ingressServiceId: string;
+    preparedSpecRevision: number;
+    credential: IFleetCutoverIngressCredentialReference;
+    actorId: string;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
 export interface IFleetCutoverIngressAuthority {
     id: string;
     generation: number;
@@ -379,6 +554,11 @@ export declare const fleetCutoverContract: Readonly<{
     readonly maximumNodes: 1024;
     readonly maximumContainersPerNode: 512;
     readonly maximumMountsPerOwner: 32;
+    readonly maximumPreparedVolumeHandoffMutationEntries: 32;
+    /** Every admitted task has one node placement and at most 32 mounts: 4096 * 32. */
+    readonly maximumPreparedVolumeHandoffs: number;
+    readonly maximumPreparedVolumeHandoffPages: number;
+    readonly maximumHeldVolumeFenceEvidenceBytes: 131072;
     readonly maximumClassifications: 512;
     readonly observationFreshnessMs: 300000;
     readonly mountSourceIdentityDigestDomain: "serve.zone/fleet-cutover-mount-source-identity";
@@ -390,9 +570,16 @@ export declare const fleetCutoverContract: Readonly<{
     readonly censusDigestDomain: "serve.zone/fleet-cutover-census";
     readonly scopeDigestDomain: "serve.zone/fleet-cutover-scope";
     readonly volumeHandoffDigestDomain: "serve.zone/fleet-cutover-volume-handoff";
+    readonly preparedVolumeHandoffDigestDomain: "serve.zone/fleet-cutover-prepared-volume-handoff";
+    readonly preparedVolumeHandoffAggregateDigestDomain: "serve.zone/fleet-cutover-prepared-volume-handoff-aggregate";
+    readonly preparedVolumeHandoffPageContentDigestDomain: "serve.zone/fleet-cutover-prepared-volume-handoff-page-content";
+    readonly preparedVolumeHandoffPageDigestDomain: "serve.zone/fleet-cutover-prepared-volume-handoff-page";
+    readonly preparedVolumeHandoffSetDigestDomain: "serve.zone/fleet-cutover-prepared-volume-handoff-set";
     readonly volumeFenceDigestDomain: "serve.zone/fleet-cutover-volume-fence";
     readonly corestoreAdoptionDigestDomain: "serve.zone/fleet-cutover-corestore-adoption";
+    readonly storageAdoptionGrantDigestDomain: "serve.zone/fleet-cutover-storage-adoption-grant";
     readonly coreflowRetirementDigestDomain: "serve.zone/fleet-cutover-coreflow-retirement";
+    readonly ingressDesignationDigestDomain: "serve.zone/fleet-cutover-ingress-designation";
     readonly ingressAuthorityDigestDomain: "serve.zone/fleet-cutover-ingress-authority";
     readonly legalPhaseTransitions: Readonly<{
         swarm: "draining";
@@ -421,6 +608,12 @@ export declare const fleetCutoverEvidenceReferenceOf: (valueArg: {
     generation: number;
     digest: TSha256Digest;
 }) => IFleetCutoverAcceptedEvidenceReference;
+export declare const fleetCutoverPreparedVolumeHandoffPageReferenceOf: (valueArg: {
+    id: string;
+    generation: number;
+    digest: TSha256Digest;
+    nodeId: string;
+}) => IFleetCutoverPreparedVolumeHandoffPageReference;
 export declare const snapshotFleetCutoverAcceptedEvidenceReference: (valueArg: unknown) => IFleetCutoverAcceptedEvidenceReference;
 export declare const snapshotFleetCutoverScope: (valueArg: unknown) => IFleetCutoverScope;
 export declare const computeFleetCutoverScopeDigest: (valueArg: unknown) => Promise<TSha256Digest>;
@@ -429,6 +622,26 @@ export declare const snapshotFleetCutoverScopeClassificationRequest: (valueArg:
 export declare const snapshotFleetCutoverTargetSetReference: (valueArg: unknown) => IFleetCutoverTargetSetReference;
 export declare const snapshotFleetCutoverVolumeHandoffIntent: (valueArg: unknown) => IFleetCutoverVolumeHandoffIntent;
 export declare const computeFleetCutoverVolumeHandoffDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const snapshotFleetCutoverPreparedVolumeHandoffIntent: (valueArg: unknown) => IFleetCutoverPreparedVolumeHandoffIntent;
+export declare const computeFleetCutoverPreparedVolumeHandoffDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverPreparedVolumeHandoffIntent: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverPreparedVolumeHandoffMutation: (valueArg: unknown) => IFleetCutoverPreparedVolumeHandoffMutation;
+export declare const snapshotFleetCutoverPreparedVolumeHandoffAggregate: (valueArg: unknown) => IFleetCutoverPreparedVolumeHandoffAggregate;
+export declare const computeFleetCutoverPreparedVolumeHandoffAggregateDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverPreparedVolumeHandoffAggregate: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverPreparedVolumeHandoffPage: (valueArg: unknown) => IFleetCutoverPreparedVolumeHandoffPage;
+export declare const computeFleetCutoverPreparedVolumeHandoffPageContentDigest: (pageIndexArg: unknown, handoffsArg: unknown) => Promise<TSha256Digest>;
+export declare const computeFleetCutoverPreparedVolumeHandoffPageDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverPreparedVolumeHandoffPage: (valueArg: unknown) => Promise<string[]>;
+export declare const computeFleetCutoverPreparedVolumeHandoffSetDigest: (entriesArg: unknown) => Promise<TSha256Digest>;
+/**
+ * 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 declare const bindFleetCutoverPreparedVolumeHandoffPages: (aggregateArg: unknown, pagesArg: unknown) => Promise<{
+    aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+    pages: IFleetCutoverPreparedVolumeHandoffPage[];
+}>;
 export declare const snapshotFleetCutoverVolumeFence: (valueArg: unknown) => TFleetCutoverVolumeFence;
 export declare const computeFleetCutoverVolumeFenceDigest: (valueArg: unknown) => Promise<TSha256Digest>;
 export declare const snapshotFleetCutoverCorestoreAdoptionReceipt: (valueArg: unknown) => IFleetCutoverCorestoreAdoptionReceipt;
@@ -438,12 +651,47 @@ export declare const bindFleetCutoverAdoptionToVolumeFence: (adoptionArg: unknow
     adoption: IFleetCutoverCorestoreAdoptionReceipt;
     fence: TFleetCutoverVolumeFence;
 };
+/**
+ * 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 declare const bindFleetCutoverAdoptionToStorageClaim: (adoptionArg: unknown, handoffArg: unknown, claimArg: unknown) => Promise<{
+    adoption: IFleetCutoverCorestoreAdoptionReceipt;
+    handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+    claim: IRuntimeStorageClaim;
+}>;
 export declare const validateFleetCutoverVolumeHandoffIntent: (valueArg: unknown) => Promise<string[]>;
 export declare const validateFleetCutoverVolumeFence: (valueArg: unknown) => Promise<string[]>;
 export declare const validateFleetCutoverCorestoreAdoptionReceipt: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverStorageAdoptionGrant: (valueArg: unknown) => IFleetCutoverStorageAdoptionGrant;
+export declare const computeFleetCutoverStorageAdoptionGrantDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverStorageAdoptionGrant: (valueArg: unknown) => Promise<string[]>;
+/** Content join only; the controller must still prove this is the live current session and phase. */
+export declare const bindFleetCutoverStorageAdoptionGrant: (grantArg: unknown, handoffArg: unknown, heldFenceArg: unknown) => Promise<{
+    grant: IFleetCutoverStorageAdoptionGrant;
+    handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+    fence: Extract<TFleetCutoverVolumeFence, {
+        state: "held";
+    }>;
+}>;
+export declare const snapshotFleetCutoverStorageAdoptionBundle: (valueArg: unknown) => IFleetCutoverStorageAdoptionBundle;
+/**
+ * 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 declare const bindFleetCutoverStorageAdoptionBundle: (valueArg: unknown, handoffArg: unknown) => Promise<{
+    bundle: IFleetCutoverStorageAdoptionBundle;
+    handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+}>;
+export declare const snapshotFleetCutoverHeldVolumeFenceEvidencePage: (valueArg: unknown) => IFleetCutoverHeldVolumeFenceEvidencePage;
+export declare const validateFleetCutoverHeldVolumeFenceEvidencePage: (valueArg: unknown) => Promise<string[]>;
 export declare const snapshotFleetCutoverCoreflowRetirementEvidence: (valueArg: unknown) => IFleetCutoverCoreflowRetirementEvidence;
 export declare const computeFleetCutoverCoreflowRetirementDigest: (valueArg: unknown) => Promise<TSha256Digest>;
 export declare const validateFleetCutoverCoreflowRetirementEvidence: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverIngressPreparationRequest: (valueArg: unknown) => IFleetCutoverIngressPreparationRequest;
+export declare const snapshotFleetCutoverIngressDesignation: (valueArg: unknown) => IFleetCutoverIngressDesignation;
+export declare const computeFleetCutoverIngressDesignationDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverIngressDesignation: (valueArg: unknown) => Promise<string[]>;
 export declare const snapshotFleetCutoverIngressAuthority: (valueArg: unknown) => IFleetCutoverIngressAuthority;
 export declare const computeFleetCutoverIngressAuthorityDigest: (valueArg: unknown) => Promise<TSha256Digest>;
 export declare const validateFleetCutoverIngressAuthority: (valueArg: unknown) => Promise<string[]>;