@serve.zone/interfaces 32.15.0 → 32.17.0

package/dist_ts/data/clusterrelaycredential.d.ts

@@ -0,0 +1,141 @@
+import type { IClusterRelayAcceptedRegistration } from './cluster.js';
+import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { ISecretVersionReference } from './secret.js';
+/**
+ * The relay authority Cloudly mints for one cluster. Public metadata only: never a bearer or hash.
+ *
+ * It authenticates the cluster's whole control-plane session, exactly what the shared cluster
+ * authority authenticated before it, so the relay changes one credential and keeps every call it
+ * makes. What it adds is a generation Cloudly fences each socket against and an authority it can
+ * rotate without touching the shared one; its scope is not narrower. One cluster has one relay and
+ * therefore one such record, and rotation is its whole lifecycle: it never expires by itself.
+ */
+export interface IClusterRelayCredential {
+    id: string;
+    clusterId: string;
+    /** Monotonic state: one accepted mint or rotation advances it by exactly one. */
+    generation: number;
+    /** The machine identity this credential authenticates as; Cloudly's own, never caller-chosen. */
+    userId: string;
+    /** The immutable encrypted version the bearer was delivered as. */
+    delivery: ISecretVersionReference;
+    actorId: string;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+interface IClusterRelayCredentialMutationBase {
+    clusterId: string;
+    /** Retain the complete request and this ID across retries; a changed body with it fails closed. */
+    mutationId: string;
+}
+/**
+ * Creation is absent-only; rotation requires the exact current generation, never a minimum.
+ *
+ * There is no revocation: a rotation already ends the previous generation at commit, so it covers a
+ * compromised credential without a state in which the cluster has no relay authority at all.
+ */
+export type TClusterRelayCredentialMutation = IClusterRelayCredentialMutationBase & ({
+    operation: 'ensure';
+    expectedGeneration: null;
+} | {
+    operation: 'rotate';
+    expectedGeneration: number;
+});
+export interface IClusterRelayCredentialMutationResult {
+    credential: IClusterRelayCredential;
+    /** The shared pre-relay authority this cluster still carries; null when no record names one. */
+    legacy: IClusterLegacyRelayCredential | null;
+    /** A replay returns the original result without renewing delivery, generation or authority. */
+    replayed: boolean;
+}
+/**
+ * Cloudly's record of the shared cluster authority that predates the relay credential, so it can
+ * be named and retired. It is the machine identity every cluster-side component authenticated as;
+ * like the relay credential it carries no bearer and no hash.
+ */
+export interface IClusterLegacyRelayCredential {
+    id: string;
+    clusterId: string;
+    userId: string;
+    generation: number;
+    state: 'active' | 'revoked';
+    /**
+     * The accepted invalidation that revoked it; null exactly while it is still accepted.
+     *
+     * The invalidation names this record at the generation before the revocation and this record
+     * names the invalidation at the generation after it, so neither digest covers the other's.
+     */
+    invalidation: IFleetCutoverAcceptedEvidenceReference | null;
+    recordedAt: number;
+    digest: TSha256Digest;
+}
+/**
+ * Caller intent only. Both references are compare-and-swap inputs: Cloudly dereferences them
+ * against its own current records and checks the relay's live socket itself.
+ */
+export interface IClusterLegacyRelayCredentialRetirementRequest {
+    /** Retain the complete request and this ID across retries; a changed body with it fails closed. */
+    mutationId: string;
+    clusterId: string;
+    expectedLegacyGeneration: number;
+    /** The exact replacement relay credential generation the caller observed as current. */
+    replacement: IRuntimeAuthorityReference;
+    /** The exact accepted registration the caller observed as current. */
+    acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
+}
+/** The accepted receipt that one shared cluster authority stopped being accepted; written once. */
+export interface IClusterLegacyRelayCredentialInvalidation {
+    id: string;
+    generation: 1;
+    clusterId: string;
+    /** The exact legacy generation this invalidated, read before the record advanced. */
+    credential: IRuntimeAuthorityReference;
+    /** The relay credential generation that was current when this was accepted. */
+    replacement: IRuntimeAuthorityReference;
+    /** The registration that was current, made under `replacement`, and live when this was accepted. */
+    acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
+    actorId: string;
+    acceptedAt: number;
+    digest: TSha256Digest;
+}
+export interface IClusterLegacyRelayCredentialRetirementResult {
+    credential: IClusterLegacyRelayCredential;
+    invalidation: IClusterLegacyRelayCredentialInvalidation;
+    /** A replay returns the recorded invalidation; nothing is revoked twice. */
+    replayed: boolean;
+}
+export declare const clusterRelayCredentialContract: Readonly<{
+    readonly credentialDigestDomain: "serve.zone/cluster-relay-credential";
+    readonly legacyCredentialDigestDomain: "serve.zone/cluster-relay-legacy-credential";
+    readonly legacyInvalidationDigestDomain: "serve.zone/cluster-relay-legacy-credential-invalidation";
+}>;
+/** Every reason Cloudly answers instead of mutating or retiring a cluster relay authority. */
+export declare const clusterRelayCredentialRefusals: readonly ["relay-credential-absent", "legacy-credential-absent", "legacy-credential-already-retired", "legacy-retirement-replacement-not-current", "legacy-retirement-registration-not-current", "legacy-retirement-relay-not-live", "conflict"];
+export type TClusterRelayCredentialRefusal = typeof clusterRelayCredentialRefusals[number];
+/** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
+export declare const snapshotClusterRelayCredential: (valueArg: unknown) => IClusterRelayCredential;
+export declare const computeClusterRelayCredentialDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateClusterRelayCredential: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotClusterRelayCredentialMutation: (valueArg: unknown) => TClusterRelayCredentialMutation;
+export declare const snapshotClusterLegacyRelayCredential: (valueArg: unknown) => IClusterLegacyRelayCredential;
+export declare const computeClusterLegacyRelayCredentialDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateClusterLegacyRelayCredential: (valueArg: unknown) => Promise<string[]>;
+export declare const snapshotClusterLegacyRelayCredentialRetirementRequest: (valueArg: unknown) => IClusterLegacyRelayCredentialRetirementRequest;
+export declare const snapshotClusterLegacyRelayCredentialInvalidation: (valueArg: unknown) => IClusterLegacyRelayCredentialInvalidation;
+export declare const computeClusterLegacyRelayCredentialInvalidationDigest: (valueArg: unknown) => Promise<TSha256Digest>;
+export declare const validateClusterLegacyRelayCredentialInvalidation: (valueArg: unknown) => Promise<string[]>;
+/**
+ * Joins an invalidation to the shared authority it revoked and to the registration that justified
+ * it, which must have been made under the very replacement the invalidation names.
+ *
+ * Content join only. Cloudly must still dereference each record as its cluster's current one and
+ * require a live verified socket for the registration while holding its compare-and-swap.
+ */
+export declare const bindClusterLegacyRelayCredentialInvalidation: (invalidationArg: unknown, legacyCredentialArg: unknown, acceptedRegistrationArg: unknown) => Promise<{
+    invalidation: IClusterLegacyRelayCredentialInvalidation;
+    legacyCredential: IClusterLegacyRelayCredential;
+    acceptedRegistration: IClusterRelayAcceptedRegistration;
+}>;
+export {};

package/dist_ts/data/clusterrelaycredential.js

@@ -0,0 +1,192 @@
+import { snapshotClusterRelayAcceptedRegistration, validateClusterRelayAcceptedRegistration, } from './cluster.js';
+import { captureNetwork, networkCounter, networkDigest, networkEqual, networkHash, networkId, networkRecord, networkReference, networkReferenceOf, requireNetwork, } from '../private/networkcontract.js';
+export const clusterRelayCredentialContract = Object.freeze({
+    credentialDigestDomain: 'serve.zone/cluster-relay-credential',
+    legacyCredentialDigestDomain: 'serve.zone/cluster-relay-legacy-credential',
+    legacyInvalidationDigestDomain: 'serve.zone/cluster-relay-legacy-credential-invalidation',
+});
+/** Every reason Cloudly answers instead of mutating or retiring a cluster relay authority. */
+export const clusterRelayCredentialRefusals = Object.freeze([
+    /** A rotation named a cluster that has no relay credential yet. */
+    'relay-credential-absent',
+    /** A retirement named a cluster whose shared authority no record names. */
+    'legacy-credential-absent',
+    /** The shared authority is already revoked; its invalidation is written once. */
+    'legacy-credential-already-retired',
+    /** The named replacement is not the cluster's relay credential at its current generation. */
+    'legacy-retirement-replacement-not-current',
+    /** The named registration is not current, or it was made under another credential generation. */
+    'legacy-retirement-registration-not-current',
+    /** No verified socket carries the named registration at the instant of acceptance. */
+    'legacy-retirement-relay-not-live',
+    /** An expected generation was not the exact current one, or a mutation ID met a changed body. */
+    'conflict',
+]);
+const fail = () => { throw new Error('Cluster relay credential contract rejected.'); };
+const safe = (operationArg) => {
+    try {
+        return operationArg();
+    }
+    catch {
+        return fail();
+    }
+};
+const secretVersionReference = (valueArg) => {
+    const value = networkRecord(valueArg, ['secretId', 'secretVersionId']);
+    return {
+        secretId: networkId(value.secretId),
+        secretVersionId: networkId(value.secretVersionId),
+    };
+};
+/** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
+export const snapshotClusterRelayCredential = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'id', 'clusterId', 'generation', 'userId', 'delivery', 'actorId', 'acceptedAt', 'digest',
+    ]);
+    return {
+        id: networkId(value.id),
+        clusterId: networkId(value.clusterId),
+        generation: networkCounter(value.generation),
+        userId: networkId(value.userId),
+        delivery: secretVersionReference(value.delivery),
+        actorId: networkId(value.actorId),
+        acceptedAt: networkCounter(value.acceptedAt),
+        digest: networkDigest(value.digest),
+    };
+});
+export const computeClusterRelayCredentialDigest = async (valueArg) => networkHash(clusterRelayCredentialContract.credentialDigestDomain, snapshotClusterRelayCredential(valueArg));
+export const validateClusterRelayCredential = async (valueArg) => {
+    try {
+        const value = snapshotClusterRelayCredential(valueArg);
+        return value.digest === await computeClusterRelayCredentialDigest(value)
+            ? [] : ['cluster relay credential digest does not match'];
+    }
+    catch {
+        return ['cluster relay credential must use its exact canonical schema'];
+    }
+};
+export const snapshotClusterRelayCredentialMutation = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'clusterId', 'mutationId', 'operation', 'expectedGeneration',
+    ]);
+    const base = { clusterId: networkId(value.clusterId), mutationId: networkId(value.mutationId) };
+    const operation = value.operation;
+    requireNetwork(operation === 'ensure' || operation === 'rotate');
+    if (operation === 'ensure') {
+        requireNetwork(value.expectedGeneration === null);
+        return { ...base, operation, expectedGeneration: null };
+    }
+    return { ...base, operation, expectedGeneration: networkCounter(value.expectedGeneration) };
+});
+export const snapshotClusterLegacyRelayCredential = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'id', 'clusterId', 'userId', 'generation', 'state', 'invalidation', 'recordedAt', 'digest',
+    ]);
+    const state = value.state;
+    requireNetwork(state === 'active' || state === 'revoked');
+    const generation = networkCounter(value.generation);
+    const invalidation = value.invalidation === null ? null : networkReference(value.invalidation);
+    // Revoked exactly when an invalidation names it, and only as the successor of an active record.
+    requireNetwork(state === 'active'
+        ? invalidation === null
+        : invalidation !== null && invalidation.generation === 1 && generation > 1);
+    return {
+        id: networkId(value.id),
+        clusterId: networkId(value.clusterId),
+        userId: networkId(value.userId),
+        generation,
+        state,
+        invalidation,
+        recordedAt: networkCounter(value.recordedAt),
+        digest: networkDigest(value.digest),
+    };
+});
+export const computeClusterLegacyRelayCredentialDigest = async (valueArg) => networkHash(clusterRelayCredentialContract.legacyCredentialDigestDomain, snapshotClusterLegacyRelayCredential(valueArg));
+export const validateClusterLegacyRelayCredential = async (valueArg) => {
+    try {
+        const value = snapshotClusterLegacyRelayCredential(valueArg);
+        return value.digest === await computeClusterLegacyRelayCredentialDigest(value)
+            ? [] : ['cluster legacy relay credential digest does not match'];
+    }
+    catch {
+        return ['cluster legacy relay credential must use its exact canonical schema'];
+    }
+};
+export const snapshotClusterLegacyRelayCredentialRetirementRequest = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'mutationId', 'clusterId', 'expectedLegacyGeneration', 'replacement', 'acceptedRegistration',
+    ]);
+    return {
+        mutationId: networkId(value.mutationId),
+        clusterId: networkId(value.clusterId),
+        expectedLegacyGeneration: networkCounter(value.expectedLegacyGeneration),
+        replacement: networkReference(value.replacement),
+        acceptedRegistration: networkReference(value.acceptedRegistration),
+    };
+});
+export const snapshotClusterLegacyRelayCredentialInvalidation = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), [
+        'id', 'generation', 'clusterId', 'credential', 'replacement', 'acceptedRegistration',
+        'actorId', 'acceptedAt', 'digest',
+    ]);
+    requireNetwork(value.generation === 1);
+    return {
+        id: networkId(value.id),
+        generation: 1,
+        clusterId: networkId(value.clusterId),
+        credential: networkReference(value.credential),
+        replacement: networkReference(value.replacement),
+        acceptedRegistration: networkReference(value.acceptedRegistration),
+        actorId: networkId(value.actorId),
+        acceptedAt: networkCounter(value.acceptedAt),
+        digest: networkDigest(value.digest),
+    };
+});
+export const computeClusterLegacyRelayCredentialInvalidationDigest = async (valueArg) => networkHash(clusterRelayCredentialContract.legacyInvalidationDigestDomain, snapshotClusterLegacyRelayCredentialInvalidation(valueArg));
+export const validateClusterLegacyRelayCredentialInvalidation = async (valueArg) => {
+    try {
+        const value = snapshotClusterLegacyRelayCredentialInvalidation(valueArg);
+        return value.digest === await computeClusterLegacyRelayCredentialInvalidationDigest(value)
+            ? [] : ['cluster legacy relay credential invalidation digest does not match'];
+    }
+    catch {
+        return ['cluster legacy relay credential invalidation must use its exact canonical schema'];
+    }
+};
+/**
+ * The active record is named exactly. The revoked one is that record's successor, so it is named
+ * by identity and the generation before it, and it names the invalidation back.
+ */
+const invalidationNamesLegacyCredential = (invalidationArg, legacyCredentialArg) => legacyCredentialArg.state === 'active'
+    ? networkEqual(invalidationArg.credential, networkReferenceOf(legacyCredentialArg))
+    : invalidationArg.credential.id === legacyCredentialArg.id
+        && invalidationArg.credential.generation === legacyCredentialArg.generation - 1
+        && networkEqual(legacyCredentialArg.invalidation, networkReferenceOf(invalidationArg));
+/**
+ * Joins an invalidation to the shared authority it revoked and to the registration that justified
+ * it, which must have been made under the very replacement the invalidation names.
+ *
+ * Content join only. Cloudly must still dereference each record as its cluster's current one and
+ * require a live verified socket for the registration while holding its compare-and-swap.
+ */
+export const bindClusterLegacyRelayCredentialInvalidation = async (invalidationArg, legacyCredentialArg, acceptedRegistrationArg) => {
+    try {
+        const invalidation = snapshotClusterLegacyRelayCredentialInvalidation(invalidationArg);
+        const legacyCredential = snapshotClusterLegacyRelayCredential(legacyCredentialArg);
+        const acceptedRegistration = snapshotClusterRelayAcceptedRegistration(acceptedRegistrationArg);
+        if ((await validateClusterLegacyRelayCredentialInvalidation(invalidation)).length
+            || (await validateClusterLegacyRelayCredential(legacyCredential)).length
+            || (await validateClusterRelayAcceptedRegistration(acceptedRegistration)).length)
+            fail();
+        requireNetwork(legacyCredential.clusterId === invalidation.clusterId
+            && acceptedRegistration.clusterId === invalidation.clusterId
+            && invalidationNamesLegacyCredential(invalidation, legacyCredential)
+            && networkEqual(invalidation.acceptedRegistration, networkReferenceOf(acceptedRegistration))
+            && networkEqual(invalidation.replacement, acceptedRegistration.credential));
+        return { invalidation, legacyCredential, acceptedRegistration };
+    }
+    catch {
+        return fail();
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQ0wsd0NBQXdDLEVBQ3hDLHdDQUF3QyxHQUN6QyxNQUFNLGNBQWMsQ0FBQztBQUt0QixPQUFPLEVBQ0wsY0FBYyxFQUNkLGNBQWMsRUFDZCxhQUFhLEVBQ2IsWUFBWSxFQUNaLFdBQVcsRUFDWCxTQUFTLEVBQ1QsYUFBYSxFQUNiLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsY0FBYyxHQUNmLE1BQU0sK0JBQStCLENBQUM7QUE4R3ZDLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsc0JBQXNCLEVBQUUscUNBQXFDO0lBQzdELDRCQUE0QixFQUFFLDRDQUE0QztJQUMxRSw4QkFBOEIsRUFBRSx5REFBeUQ7Q0FDakYsQ0FBQyxDQUFDO0FBRVosOEZBQThGO0FBQzlGLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsbUVBQW1FO0lBQ25FLHlCQUF5QjtJQUN6QiwyRUFBMkU7SUFDM0UsMEJBQTBCO0lBQzFCLGlGQUFpRjtJQUNqRixtQ0FBbUM7SUFDbkMsNkZBQTZGO0lBQzdGLDJDQUEyQztJQUMzQyxpR0FBaUc7SUFDakcsNENBQTRDO0lBQzVDLHNGQUFzRjtJQUN0RixrQ0FBa0M7SUFDbEMsaUdBQWlHO0lBQ2pHLFVBQVU7Q0FDRixDQUFDLENBQUM7QUFJWixNQUFNLElBQUksR0FBRyxHQUFVLEVBQUUsR0FBRyxNQUFNLElBQUksS0FBSyxDQUFDLDZDQUE2QyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDOUYsTUFBTSxJQUFJLEdBQUcsQ0FBSSxZQUFxQixFQUFLLEVBQUU7SUFDM0MsSUFBSSxDQUFDO1FBQUMsT0FBTyxZQUFZ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

package/dist_ts/data/fleetcutover.d.ts

@@ -35,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 = {
@@ -83,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;
@@ -554,6 +586,9 @@ 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;
@@ -564,6 +599,9 @@ export declare const fleetCutoverContract: Readonly<{
     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";
@@ -588,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>;