@serve.zone/interfaces 32.14.0 → 32.16.0

package/dist_ts/data/fleetcutover.d.ts

@@ -2,6 +2,8 @@ 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.
@@ -33,6 +35,33 @@ export interface IFleetCutoverMountTargetIdentityInput {
     /** Docker Engine Mount.Destination exact UTF-8 bytes; never normalize. */
     target: string;
 }
+export interface IFleetCutoverDockerMountInput {
+    /** Raw Docker mount type. Unsupported values produce an explicit unknown descriptor. */
+    type: string;
+    /** Exact source bytes from the Docker object being described; never substitute another field. */
+    source: string;
+    /** Exact container target bytes from the Docker object being described. */
+    target: string;
+    readOnly: boolean;
+}
+/**
+ * Value-free correlation between one local physical mount and its service-spec mount identity.
+ * The two identities stay distinct: a Docker volume's local Source is a host path while its
+ * service Source and local Name are the logical volume name.
+ */
+export interface IFleetCutoverPhysicalMountCorrelation {
+    physicalMountIdentityDigest: TSha256Digest;
+    serviceMountIdentityDigest: TSha256Digest;
+    correlationIdentityDigest: TSha256Digest;
+}
+export interface IFleetCutoverPhysicalMountEvidence {
+    mount: IFleetCutoverMountDescriptor;
+    correlation: IFleetCutoverPhysicalMountCorrelation;
+}
+export interface IFleetCutoverDockerConstraintSetIdentity {
+    constraintCount: number;
+    constraintSetDigest: TSha256Digest;
+}
 export type TFleetCutoverDockerTaskState = 'new' | 'allocated' | 'pending' | 'assigned' | 'accepted' | 'preparing' | 'ready' | 'starting' | 'running' | 'complete' | 'shutdown' | 'failed' | 'rejected' | 'remove' | 'orphaned';
 export type TFleetCutoverDockerDesiredState = TFleetCutoverDockerTaskState;
 export type TFleetCutoverDockerServiceMode = {
@@ -81,6 +110,11 @@ export interface IFleetCutoverPhysicalContainer {
     imageId: TSha256Digest;
     serviceIdLabel: string | null;
     mounts: IFleetCutoverMountDescriptor[];
+    /**
+     * Optional only for compatibility with observations predating correlation evidence. When
+     * present it is a complete one-to-one mapping of mounts. Absence establishes no mount join.
+     */
+    mountCorrelations?: IFleetCutoverPhysicalMountCorrelation[];
 }
 export interface IFleetCutoverContainerSetIdentity {
     containerCount: number;
@@ -210,6 +244,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;
@@ -258,6 +383,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;
@@ -424,19 +586,36 @@ export declare const fleetCutoverContract: Readonly<{
     readonly maximumNodes: 1024;
     readonly maximumContainersPerNode: 512;
     readonly maximumMountsPerOwner: 32;
+    readonly maximumConstraintsPerService: 256;
+    readonly maximumDockerTextBytes: 4096;
+    readonly maximumDockerServiceSpecCanonicalBytes: 1048576;
+    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";
     readonly mountTargetIdentityDigestDomain: "serve.zone/fleet-cutover-mount-target-identity";
     readonly mountIdentityDigestDomain: "serve.zone/fleet-cutover-mount-identity";
+    readonly mountCorrelationIdentityDigestDomain: "serve.zone/fleet-cutover-mount-correlation-identity";
+    readonly dockerServiceSpecDigestDomain: "serve.zone/fleet-cutover-docker-service-spec";
+    readonly dockerConstraintSetDigestDomain: "serve.zone/fleet-cutover-docker-constraint-set";
     readonly containerSetIdentityDigestDomain: "serve.zone/fleet-cutover-container-set-identity";
     readonly localNodeSnapshotDigestDomain: "serve.zone/fleet-cutover-local-node-snapshot";
     readonly managerSnapshotDigestDomain: "serve.zone/fleet-cutover-manager-snapshot";
     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";
@@ -447,9 +626,36 @@ export declare const fleetCutoverContract: Readonly<{
         pallet: null;
     }>;
 }>;
+/** Docker labels with established historical producer semantics. */
+export declare const fleetCutoverDockerLabelNames: Readonly<{
+    readonly serviceId: "serve.zone.serviceId";
+}>;
+/**
+ * Hash the complete open-schema Docker Service.Spec object. Unknown response properties are
+ * intentionally included: this helper returns only the digest and never a retained projection.
+ */
+export declare const computeFleetCutoverDockerServiceSpecDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+/** Sort exact constraint strings while preserving duplicate entries, then return value-free identity. */
+export declare const computeFleetCutoverDockerConstraintSetIdentity: (valueArg: unknown) => Promise<IFleetCutoverDockerConstraintSetIdentity>;
+export declare const snapshotFleetCutoverDockerDesiredTaskCount: (valueArg: unknown) => number;
+export declare const validateFleetCutoverDockerDesiredTaskCount: (valueArg: unknown) => string[];
+/** Apply only the documented exact cutover mount classifications; no path normalization occurs. */
+export declare const classifyFleetCutoverDockerMount: (valueArg: IFleetCutoverDockerMountInput) => Pick<IFleetCutoverMountDescriptor, "type" | "classification">;
+export declare const createFleetCutoverMountDescriptor: (valueArg: IFleetCutoverDockerMountInput) => Promise<IFleetCutoverMountDescriptor>;
+/** Read only consumed Service.Spec Mount fields; future Docker response properties are ignored. */
+export declare const createFleetCutoverDockerServiceMountDescriptor: (valueArg: unknown) => Promise<IFleetCutoverMountDescriptor>;
+/** Read only consumed local MountPoint fields and retain the exact physical Source identity. */
+export declare const createFleetCutoverDockerLocalMountDescriptor: (valueArg: unknown) => Promise<IFleetCutoverMountDescriptor>;
 export declare const computeFleetCutoverMountSourceIdentityDigest: (valueArg: IFleetCutoverMountSourceIdentityInput) => Promise<TSha256Digest>;
 export declare const computeFleetCutoverMountTargetIdentityDigest: (valueArg: IFleetCutoverMountTargetIdentityInput) => Promise<TSha256Digest>;
 export declare const computeFleetCutoverMountIdentityDigest: (valueArg: Omit<IFleetCutoverMountDescriptor, "mountIdentityDigest">) => Promise<TSha256Digest>;
+export declare const computeFleetCutoverMountCorrelationIdentityDigest: (valueArg: Omit<IFleetCutoverPhysicalMountCorrelation, "correlationIdentityDigest">) => Promise<TSha256Digest>;
+/**
+ * Produce both the exact local physical descriptor and its logical service-mount correlation.
+ * For a volume only MountPoint.Name supplies the logical source. Unknown types and a missing or
+ * empty volume Name are refused because they cannot establish a truthful service join.
+ */
+export declare const createFleetCutoverDockerPhysicalMountEvidence: (valueArg: unknown) => Promise<IFleetCutoverPhysicalMountEvidence>;
 export declare const computeFleetCutoverContainerSetIdentityDigest: (containerIdsArg: string[]) => Promise<TSha256Digest>;
 export declare const snapshotFleetCutoverLocalNodeSnapshot: (valueArg: unknown) => IFleetCutoverLocalNodeSnapshot;
 export declare const computeFleetCutoverLocalNodeSnapshotDigest: (valueArg: unknown) => Promise<TSha256Digest>;
@@ -467,6 +673,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>;
@@ -475,6 +687,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;
@@ -484,9 +716,40 @@ 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[]>;