@serve.zone/interfaces 32.11.0 → 32.13.0

package/dist_ts/data/fleetcutover.d.ts

@@ -0,0 +1,453 @@
+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';
+/**
+ * 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.
+ */
+export type IFleetCutoverAcceptedEvidenceReference = IRuntimeAuthorityReference;
+export type TFleetCutoverPlatformOwner = 'application' | 'coreflow' | 'corestore' | 'coretraffic';
+export type TFleetCutoverMountClass = 'docker-socket' | 'cgroup' | 'persistent-volume' | 'bind' | 'tmpfs' | 'other' | 'unknown';
+export type TFleetCutoverMountType = 'volume' | 'bind' | 'tmpfs' | 'unknown';
+/**
+ * Value-free mount identity. The three digests are derived from exact Docker Engine bytes by the
+ * helpers below; no path, volume-name, case, separator, or alias normalization is permitted.
+ */
+export interface IFleetCutoverMountDescriptor {
+    type: TFleetCutoverMountType;
+    classification: TFleetCutoverMountClass;
+    sourceIdentityDigest: TSha256Digest;
+    targetIdentityDigest: TSha256Digest;
+    readOnly: boolean;
+    mountIdentityDigest: TSha256Digest;
+}
+export interface IFleetCutoverMountSourceIdentityInput {
+    /** Docker Engine Mount.Type exactly as returned; unsupported values are represented as unknown. */
+    type: TFleetCutoverMountType;
+    /** Docker Engine Mount.Source exact UTF-8 bytes, including the empty string; never normalize. */
+    source: string;
+}
+export interface IFleetCutoverMountTargetIdentityInput {
+    /** Docker Engine Mount.Destination exact UTF-8 bytes; never normalize. */
+    target: string;
+}
+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 = {
+    kind: 'global';
+} | {
+    kind: 'replicated';
+    replicas: number;
+};
+/** Only the ownership labels used by cutover policy are transported. */
+export interface IFleetCutoverDockerOwnershipLabels {
+    serviceId: string | null;
+    platformOwner: Exclude<TFleetCutoverPlatformOwner, 'application'> | null;
+}
+/** Value-free immutable identity of one Docker service specification. */
+export interface IFleetCutoverDockerService {
+    dockerServiceId: string;
+    dockerServiceName: string;
+    specVersion: number;
+    specDigest: TSha256Digest;
+    imageDigest: TSha256Digest;
+    mode: TFleetCutoverDockerServiceMode;
+    desiredTaskCount: number;
+    constraintCount: number;
+    constraintSetDigest: TSha256Digest;
+    mounts: IFleetCutoverMountDescriptor[];
+    ownershipLabels: IFleetCutoverDockerOwnershipLabels;
+}
+/** Value-free physical task/container evidence from the same Docker census. */
+export interface IFleetCutoverDockerTask {
+    dockerTaskId: string;
+    dockerServiceId: string;
+    /** Null exactly when Docker Task.NodeID is absent and the task remains unassigned. */
+    swarmNodeId: string | null;
+    /** Resolved from the same manager census as swarmNodeId; null iff swarmNodeId is null. */
+    nodeName: string | null;
+    desiredState: TFleetCutoverDockerDesiredState;
+    state: TFleetCutoverDockerTaskState;
+    container: null | {
+        dockerContainerId: string;
+    };
+}
+export interface IFleetCutoverPhysicalContainer {
+    dockerContainerId: string;
+    dockerServiceId: string | null;
+    dockerTaskId: string | null;
+    imageId: TSha256Digest;
+    serviceIdLabel: string | null;
+    mounts: IFleetCutoverMountDescriptor[];
+}
+export interface IFleetCutoverContainerSetIdentity {
+    containerCount: number;
+    containerIdsDigest: TSha256Digest;
+}
+/**
+ * One node's local Docker daemon snapshot. `before` and `after` are independently read bounded
+ * container-ID sets around all inspect calls and must equal the transported container list.
+ */
+export interface IFleetCutoverLocalNodeSnapshot {
+    swarmNodeId: string;
+    before: IFleetCutoverContainerSetIdentity;
+    containers: IFleetCutoverPhysicalContainer[];
+    after: IFleetCutoverContainerSetIdentity;
+    snapshotDigest: TSha256Digest;
+}
+/** Manager-visible Swarm state only; physical containers come from each node's own observation. */
+export interface IFleetCutoverDockerInventory {
+    swarmClusterId: string;
+    managerSwarmNodeId: string;
+    services: IFleetCutoverDockerService[];
+    tasks: IFleetCutoverDockerTask[];
+}
+export interface IFleetCutoverManagerSnapshot {
+    inventory: IFleetCutoverDockerInventory;
+    inventoryDigest: TSha256Digest;
+}
+/** Cloudly-owned reference to one already authenticated and accepted Spark observation. */
+export interface IFleetCutoverSparkObservationReference {
+    observation: IFleetCutoverAcceptedEvidenceReference;
+    nodeId: string;
+    swarmNodeId: string;
+    credentialGeneration: number;
+    reporterSessionId: string;
+    observationSequence: number;
+    observedAt: number;
+    acceptedAt: number;
+    freshUntil: number;
+    observationDigest: TSha256Digest;
+    snapshotDigest: TSha256Digest;
+}
+export interface IFleetCutoverManagerCensusRead extends IFleetCutoverSparkObservationReference {
+    swarmSnapshotDigest: TSha256Digest;
+    inventoryDigest: TSha256Digest;
+}
+export interface IFleetCutoverTargetSetReference {
+    cloudlyClusterId: string;
+    generation: number;
+    targetSetDigest: TSha256Digest;
+}
+/** Cloudly-assembled candidate over accepted Spark observations; Spark never submits this shape. */
+export interface IFleetCutoverCensusCandidate {
+    clusterId: string;
+    runtime: IClusterRuntimeReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    inventory: IFleetCutoverDockerInventory;
+    /** Exactly two consecutive accepted reads by the same current manager session. */
+    managerReads: [IFleetCutoverManagerCensusRead, IFleetCutoverManagerCensusRead];
+    /** Exactly one accepted local physical-container observation per current target node. */
+    nodeObservations: IFleetCutoverSparkObservationReference[];
+    /** Fixed by the oldest referenced observation; reassembly cannot extend it. */
+    freshUntil: number;
+}
+/** Cloudly-owned accepted census. Acceptance freshness and authentication are owner policy. */
+export interface IFleetCutoverCensus extends IFleetCutoverCensusCandidate {
+    id: string;
+    generation: number;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+export interface IFleetCutoverScopeEntry {
+    dockerServiceId: string;
+    serviceId: string | null;
+    owner: TFleetCutoverPlatformOwner | 'unknown';
+    serviceAuthority: IFleetCutoverAcceptedEvidenceReference | null;
+    classificationAuthority: IFleetCutoverAcceptedEvidenceReference | null;
+}
+/**
+ * Authoritative cutover scope. `complete` is a Cloudly policy verdict over current service
+ * authority and a fresh accepted census; structural validation only checks its closed content.
+ */
+export interface IFleetCutoverScope {
+    id: string;
+    generation: number;
+    previous: IFleetCutoverAcceptedEvidenceReference | null;
+    state: 'incomplete' | 'complete';
+    clusterId: string;
+    census: IFleetCutoverAcceptedEvidenceReference;
+    runtime: IClusterRuntimeReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    entries: IFleetCutoverScopeEntry[];
+    actorId: string;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+/** Legitimate administrator classification bound to one current accepted census. */
+export interface IFleetCutoverClassification {
+    dockerServiceId: string;
+    serviceId: string;
+    owner: TFleetCutoverPlatformOwner;
+}
+export interface IFleetCutoverScopeClassificationRequest {
+    mutationId: string;
+    clusterId: string;
+    expectedScopeGeneration: number;
+    census: IFleetCutoverAcceptedEvidenceReference;
+    classifications: IFleetCutoverClassification[];
+}
+/** Server-owned pre-switch intent. It is not a ready storage claim or mount authority. */
+export interface IFleetCutoverVolumeHandoffIntent {
+    id: string;
+    generation: number;
+    clusterId: string;
+    nodeId: string;
+    serviceId: string;
+    volumeId: string;
+    mountIdentityDigest: TSha256Digest;
+    sourceLineageDigest: TSha256Digest;
+    storageRequestDigest: TSha256Digest;
+    runtime: IClusterRuntimeReference & {
+        phase: 'draining';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    legacyStorageEvidence: IFleetCutoverAcceptedEvidenceReference;
+    sourceNodeObservation: IFleetCutoverAcceptedEvidenceReference;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+interface IFleetCutoverVolumeFenceBase {
+    id: string;
+    generation: number;
+    previous: IFleetCutoverAcceptedEvidenceReference | null;
+    clusterId: string;
+    nodeId: string;
+    serviceId: string;
+    volumeId: string;
+    mountIdentityDigest: TSha256Digest;
+    handoffIntent: IFleetCutoverAcceptedEvidenceReference;
+    heldRuntime: IClusterRuntimeReference & {
+        phase: 'draining';
+    };
+    heldAt: number;
+    digest: TSha256Digest;
+}
+/**
+ * Pallet root-local durable negative authority. `held` grants no runtime session, assignment,
+ * attachment, reservation, confirmation, or execution authority.
+ */
+export type TFleetCutoverVolumeFence = (IFleetCutoverVolumeFenceBase & {
+    state: 'held';
+}) | (IFleetCutoverVolumeFenceBase & {
+    state: 'consumed';
+    consumedRuntime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    adoptionReceipt: IFleetCutoverAcceptedEvidenceReference;
+    claim: IRuntimeAuthorityReference;
+    consumedAt: number;
+});
+/** Corestore's one-shot accepted result around the initial lineage/RWO CAS. */
+export interface IFleetCutoverCorestoreAdoptionReceipt {
+    id: string;
+    generation: 1;
+    clusterId: string;
+    nodeId: string;
+    serviceId: string;
+    volumeId: string;
+    mountIdentityDigest: TSha256Digest;
+    handoffIntent: IFleetCutoverAcceptedEvidenceReference;
+    palletFence: IFleetCutoverAcceptedEvidenceReference;
+    sourceLineageDigest: TSha256Digest;
+    claim: IRuntimeAuthorityReference;
+    accessMode: 'ReadWriteOnce';
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+export interface IFleetCutoverCoreflowRetirementEvidence {
+    id: string;
+    generation: number;
+    clusterId: string;
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    runtime: IClusterRuntimeReference;
+    relay: {
+        serviceId: string;
+        nodeId: string;
+        dockerServiceId: string;
+        dockerContainerId: string;
+        specVersion: number;
+        specDigest: TSha256Digest;
+        imageDigest: TSha256Digest;
+        managerObservation: IFleetCutoverAcceptedEvidenceReference;
+        nodeObservation: IFleetCutoverAcceptedEvidenceReference;
+        credential: IRuntimeAuthorityReference;
+        acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
+        version: string;
+    };
+    spark: {
+        nodeId: string;
+        credentialGeneration: number;
+        reporterSessionId: string;
+        observationSequence: number;
+        observation: IFleetCutoverAcceptedEvidenceReference;
+        bundleVersion: string;
+        bundleSourceCommit: string;
+        bundleManifestSha256: string;
+        unitName: string;
+        unitDigest: TSha256Digest;
+    };
+    legacy: {
+        credential: IRuntimeAuthorityReference;
+        invalidation: IFleetCutoverAcceptedEvidenceReference;
+        oldModeRefusal: IFleetCutoverAcceptedEvidenceReference;
+        configurationCas: IFleetCutoverAcceptedEvidenceReference;
+        sourceOwnerGeneration: number;
+        sourceSha256: string;
+        sourceDisposition: 'retained-inert' | 'removed';
+    };
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+export interface IFleetCutoverIngressAuthority {
+    id: string;
+    generation: number;
+    clusterId: string;
+    runtime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+    ingressServiceId: string;
+    assignment: IRuntimeAssignmentReference;
+    session: IRuntimeSessionBinding;
+    ingressRegistration: IFleetCutoverAcceptedEvidenceReference;
+    registrationRouteRevision: number | null;
+    legacyIngressAbsence: IFleetCutoverAcceptedEvidenceReference;
+    sourcePublication: IFleetCutoverAcceptedEvidenceReference;
+    targetPublication: IFleetCutoverAcceptedEvidenceReference;
+    portTransfer: IFleetCutoverAcceptedEvidenceReference;
+    routeTableRevision: number;
+    routeTableReadback: IFleetCutoverAcceptedEvidenceReference;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+interface IFleetCutoverPhaseAdvanceBase {
+    mutationId: string;
+    clusterId: string;
+    currentRuntime: IClusterRuntimeReference;
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    targetSet: IFleetCutoverTargetSetReference;
+}
+/** Caller intent only. Cloudly dereferences every receipt and applies the transition atomically. */
+export type TFleetCutoverPhaseAdvance = (IFleetCutoverPhaseAdvanceBase & {
+    from: 'swarm';
+    to: 'draining';
+    coreflowRetirement: IFleetCutoverAcceptedEvidenceReference;
+}) | (IFleetCutoverPhaseAdvanceBase & {
+    from: 'draining';
+    to: 'switching';
+    swarmQuiescence: IFleetCutoverAcceptedEvidenceReference;
+    heldRuntimeSpecs: IFleetCutoverAcceptedEvidenceReference;
+    heldVolumeFences: IFleetCutoverAcceptedEvidenceReference;
+}) | (IFleetCutoverPhaseAdvanceBase & {
+    from: 'switching';
+    to: 'pallet';
+    heldRuntimeSpecs: IFleetCutoverAcceptedEvidenceReference;
+    heldVolumeFences: IFleetCutoverAcceptedEvidenceReference;
+    palletPreparation: IFleetCutoverAcceptedEvidenceReference;
+});
+export type TFleetCutoverRuntimeSpecRelease = {
+    kind: 'ingress';
+    mutationId: string;
+    clusterId: string;
+    serviceId: string;
+    expectedSpecRevision: number;
+    runtime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    emptyPublishedPortsPolicy: IFleetCutoverAcceptedEvidenceReference;
+} | {
+    kind: 'application';
+    mutationId: string;
+    clusterId: string;
+    serviceId: string;
+    expectedSpecRevision: number;
+    runtime: IClusterRuntimeReference & {
+        phase: 'pallet';
+    };
+    scope: IFleetCutoverAcceptedEvidenceReference;
+    ingressAuthority: IFleetCutoverAcceptedEvidenceReference;
+};
+export declare const fleetCutoverContract: Readonly<{
+    readonly maximumServices: 512;
+    readonly maximumTasks: 4096;
+    readonly maximumNodes: 1024;
+    readonly maximumContainersPerNode: 512;
+    readonly maximumMountsPerOwner: 32;
+    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 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 volumeFenceDigestDomain: "serve.zone/fleet-cutover-volume-fence";
+    readonly corestoreAdoptionDigestDomain: "serve.zone/fleet-cutover-corestore-adoption";
+    readonly coreflowRetirementDigestDomain: "serve.zone/fleet-cutover-coreflow-retirement";
+    readonly ingressAuthorityDigestDomain: "serve.zone/fleet-cutover-ingress-authority";
+    readonly legalPhaseTransitions: Readonly<{
+        swarm: "draining";
+        draining: "switching";
+        switching: "pallet";
+        pallet: null;
+    }>;
+}>;
+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 computeFleetCutoverContainerSetIdentityDigest: (containerIdsArg: string[]) => Promise<TSha256Digest>;
+export declare const snapshotFleetCutoverLocalNodeSnapshot: (valueArg: unknown) => IFleetCutoverLocalNodeSnapshot;
+export declare const computeFleetCutoverLocalNodeSnapshotDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverLocalNodeSnapshot: (valueArg: unknown) => Promise<string[]>;
+export declare const computeFleetCutoverInventoryDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const snapshotFleetCutoverManagerSnapshot: (valueArg: unknown) => Promise<IFleetCutoverManagerSnapshot>;
+export declare const computeFleetCutoverManagerSnapshotDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverManagerSnapshot: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverCensusCandidate: (valueArg: unknown) => Promise<IFleetCutoverCensusCandidate>;
+export declare const snapshotFleetCutoverCensus: (valueArg: unknown) => Promise<IFleetCutoverCensus>;
+export declare const computeFleetCutoverCensusDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverCensus: (valueArg: unknown) => Promise<string[]>;
+export declare const fleetCutoverEvidenceReferenceOf: (valueArg: {
+    id: string;
+    generation: number;
+    digest: TSha256Digest;
+}) => IFleetCutoverAcceptedEvidenceReference;
+export declare const snapshotFleetCutoverAcceptedEvidenceReference: (valueArg: unknown) => IFleetCutoverAcceptedEvidenceReference;
+export declare const snapshotFleetCutoverScope: (valueArg: unknown) => IFleetCutoverScope;
+export declare const computeFleetCutoverScopeDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverScope: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotFleetCutoverScopeClassificationRequest: (valueArg: unknown) => IFleetCutoverScopeClassificationRequest;
+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 snapshotFleetCutoverVolumeFence: (valueArg: unknown) => TFleetCutoverVolumeFence;
+export declare const computeFleetCutoverVolumeFenceDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const snapshotFleetCutoverCorestoreAdoptionReceipt: (valueArg: unknown) => IFleetCutoverCorestoreAdoptionReceipt;
+export declare const computeFleetCutoverCorestoreAdoptionDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+/** Content join only. The Pallet owner must dereference both accepted records while holding its CAS. */
+export declare const bindFleetCutoverAdoptionToVolumeFence: (adoptionArg: unknown, fenceArg: unknown) => {
+    adoption: IFleetCutoverCorestoreAdoptionReceipt;
+    fence: TFleetCutoverVolumeFence;
+};
+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 snapshotFleetCutoverCoreflowRetirementEvidence: (valueArg: unknown) => IFleetCutoverCoreflowRetirementEvidence;
+export declare const computeFleetCutoverCoreflowRetirementDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateFleetCutoverCoreflowRetirementEvidence: (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[]>;
+export declare const isLegalFleetCutoverPhaseTransition: (fromArg: TClusterRuntimePhase, toArg: TClusterRuntimePhase) => boolean;
+export declare const snapshotFleetCutoverPhaseAdvance: (valueArg: unknown) => TFleetCutoverPhaseAdvance;
+export declare const snapshotFleetCutoverRuntimeSpecRelease: (valueArg: unknown) => TFleetCutoverRuntimeSpecRelease;
+export {};