@serve.zone/interfaces 32.50.0 → 32.52.0

package/dist_ts/data/sparknodereport.d.ts

@@ -22,7 +22,28 @@ export interface ISparkNodeReport {
         localRuntimeReady: true;
         workloadReadiness: 'unverified';
     };
+    /**
+     * The outcome of Spark's last attempt to apply a desired hostname (`sparkNodeHostContract`), when
+     * it made one since it started. Whether the node carries the hostname is `runtime.hostname`.
+     */
+    hostApply?: ISparkNodeHostApply;
 }
+/** Whether Spark applied a desired hostname: `applied` once the host carries it. */
+export type TSparkNodeHostApplyOutcome = 'applied' | 'failed';
+/** One attempt to apply the desired hostname of one generation. */
+export interface ISparkNodeHostApply {
+    /** The `ISparkNodeDesiredHost.generation` the attempt applied. */
+    generation: number;
+    /** The hostname it applied. */
+    hostname: string;
+    outcome: TSparkNodeHostApplyOutcome;
+    /** `failed` only, and required there: why, as operator text. */
+    reason?: string;
+}
+/** Bounds of `ISparkNodeHostApply.reason`. */
+export declare const sparkNodeHostApplyContract: Readonly<{
+    readonly maximumReasonLength: 512;
+}>;
 /** HTTPS POST body. Never log, persist, or return nodeToken. */
 export interface ISparkNodeHeartbeatRequest {
     nodeId: string;
@@ -65,3 +86,42 @@ export declare const sparkNodeHeartbeatContract: Readonly<{
 export declare const snapshotSparkNodeReport: (valueArg: unknown) => ISparkNodeReport;
 export declare const snapshotSparkNodeHeartbeatRequest: (valueArg: unknown) => ISparkNodeHeartbeatRequest;
 export declare const snapshotSparkNodeHeartbeatReceipt: (valueArg: unknown) => ISparkNodeHeartbeatReceipt;
+/** HTTPS POST body asking for the hostname Cloudly wants the node to carry. Never log, persist, or return nodeToken. */
+export interface ISparkNodeHostRequest {
+    nodeId: string;
+    nodeToken: string;
+    /** Read and negotiated before the node is authenticated; see `sparkNodeHostContract`. */
+    protocol: IProtocolOffer;
+}
+/**
+ * The hostname Cloudly wants the node to carry: `IClusterNode.data.hostnameIntent`, as the node
+ * applies it.
+ *
+ * `hostname: null` with `generation: 0` states that Cloudly holds no intent for the node, and Spark
+ * leaves the host's hostname as it is. Applying is idempotent: a host that already carries the
+ * hostname is left alone, and every answer states the whole desired value rather than a change.
+ */
+export interface ISparkNodeDesiredHost {
+    nodeId: string;
+    hostname: string | null;
+    generation: number;
+    /** The controller's offer, so the node judges the answer it acts on. */
+    protocol: IProtocolOffer;
+}
+/**
+ * The node runtime's desired-host route.
+ *
+ * Authenticated with the node's Spark credential exactly like `sparkNodeHeartbeatContract`, and
+ * judged in the same server order: protocol offer first, against this server's `sparkNode` offer
+ * and within `maxRequestBytes`, answered with `protocolRefusalStatus` and an `IProtocolRefusal` body
+ * on refusal, before the node is authenticated. Spark reports the outcome of applying the answer as
+ * `ISparkNodeReport.hostApply` on its next heartbeat.
+ */
+export declare const sparkNodeHostContract: Readonly<{
+    readonly endpoint: "/spark/nodes/host";
+    readonly maxRequestBytes: 1024;
+    readonly maxResponseBytes: 1024;
+    readonly protocolRefusalStatus: 422;
+}>;
+export declare const snapshotSparkNodeHostRequest: (valueArg: unknown) => ISparkNodeHostRequest;
+export declare const snapshotSparkNodeDesiredHost: (valueArg: unknown) => ISparkNodeDesiredHost;

package/dist_ts/data/sparknodereport.js

@@ -1,7 +1,12 @@
 import { isReleaseVersion } from './releaseversion.js';
-import { readExactDataRecord } from '../private/dataproperties.js';
+import { readDataProperties, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer } from '../protocol.js';
+import { isClusterNodeHostname } from './clusternodehostname.js';
+/** Bounds of `ISparkNodeHostApply.reason`. */
+export const sparkNodeHostApplyContract = Object.freeze({
+    maximumReasonLength: 512,
+});
 /**
  * The node runtime's own heartbeat route.
  *
@@ -48,9 +53,27 @@ const integer = (valueArg, minimumArg) => {
     requireValue(Number.isSafeInteger(value) && value >= minimumArg);
     return value;
 };
+/** One `hostApply`: exactly its keys, a reason exactly when it failed. */
+const snapshotSparkNodeHostApply = (valueArg) => {
+    const keys = ['generation', 'hostname', 'outcome'];
+    const value = readExactDataRecord(valueArg, keys) ?? record(valueArg, [...keys, 'reason']);
+    requireValue(isClusterNodeHostname(value.hostname));
+    const generation = integer(value.generation, 1);
+    if (value.outcome === 'applied') {
+        requireValue(value.reason === undefined);
+        return Object.freeze({ generation, hostname: value.hostname, outcome: 'applied' });
+    }
+    requireValue(value.outcome === 'failed');
+    return Object.freeze({ generation, hostname: value.hostname, outcome: 'failed',
+        reason: text(value.reason, /^[\x20-\x7e]+$/, sparkNodeHostApplyContract.maximumReasonLength) });
+};
 /** Exact inert JSON records; detaches and freezes before any consumer awaits. */
 export const snapshotSparkNodeReport = (valueArg) => {
-    const value = record(valueArg, ['observedAt', 'metrics', 'runtime']);
+    const reportKeys = ['observedAt', 'metrics', 'runtime'];
+    const properties = readDataProperties(valueArg);
+    requireValue(properties !== null);
+    const hasHostApply = Object.hasOwn(properties, 'hostApply');
+    const value = record(valueArg, hasHostApply ? [...reportKeys, 'hostApply'] : reportKeys);
     const metrics = record(value.metrics, ['cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB',
         'diskUsedGB', 'diskAvailableGB']);
     const runtime = record(value.runtime, ['hostname', 'platform', 'arch', 'osRelease', 'bundle',
@@ -77,6 +100,7 @@ export const snapshotSparkNodeReport = (valueArg) => {
             }),
             localRuntimeReady: true, workloadReadiness: 'unverified',
         }),
+        ...(hasHostApply ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
     });
 };
 export const snapshotSparkNodeHeartbeatRequest = (valueArg) => {
@@ -100,4 +124,43 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg) => {
         protocol: readProtocolOffer(value),
     });
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmtub2RlcmVwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zcGFya25vZGVyZXBvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDdkQsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbkUsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBQy9ELE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxpQkFBaUIsRUFBdUIsTUFBTSxnQkFBZ0IsQ0FBQztBQWlEbkc7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3RELFFBQVEsRUFBRSx3QkFBd0I7SUFDbEMsZUFBZSxFQUFFLElBQUk7SUFDckIsZ0JBQWdCLEVBQUUsSUFBSTtJQUN0QixxQkFBcUIsRUFBRSx5QkFBeUI7Q0FDeEMsQ0FBQyxDQUFDO0FBRVosTUFBTSxJQUFJLEdBQUcsR0FBVSxFQUFFLEdBQUcsTUFBTSxJQUFJLEtBQUssQ0FBQyx5Q0FBeUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzFGLFNBQVMsWUFBWSxDQUFDLFFBQWlCO0lBQ3JDLElBQUksQ0FBQyxRQUFRO1FBQUUsSUFBSSxFQUFFLENBQUM7QUFDeEIsQ0FBQztBQUNELHNHQUFzRztBQUN0RyxNQUFNLE1BQU0sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBMEIsRUFBMkIsRUFBRTtJQUN4RixNQUFNLE1BQU0sR0FBRyxtQkFBbUIsQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDdEQsWUFBWSxDQUFDLE1BQU0sS0FBSyxJQUFJLENBQUMsQ0FBQztJQUM5QixPQUFPLE1BQU0sQ0FBQztBQUNoQixDQUFDLENBQUM7QUFDRixNQUFNLElBQUksR0FBRyxDQUFDLFFBQWlCLEVBQUUs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
+/**
+ * The node runtime's desired-host route.
+ *
+ * Authenticated with the node's Spark credential exactly like `sparkNodeHeartbeatContract`, and
+ * judged in the same server order: protocol offer first, against this server's `sparkNode` offer
+ * and within `maxRequestBytes`, answered with `protocolRefusalStatus` and an `IProtocolRefusal` body
+ * on refusal, before the node is authenticated. Spark reports the outcome of applying the answer as
+ * `ISparkNodeReport.hostApply` on its next heartbeat.
+ */
+export const sparkNodeHostContract = Object.freeze({
+    endpoint: '/spark/nodes/host',
+    maxRequestBytes: 1024,
+    maxResponseBytes: 1024,
+    protocolRefusalStatus: protocolRefusalHttpStatus,
+});
+export const snapshotSparkNodeHostRequest = (valueArg) => {
+    const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol']);
+    return Object.freeze({
+        nodeId: nodeId(value.nodeId),
+        nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
+        protocol: readProtocolOffer(value),
+    });
+};
+export const snapshotSparkNodeDesiredHost = (valueArg) => {
+    const value = record(valueArg, ['nodeId', 'hostname', 'generation', 'protocol']);
+    const hostname = value.hostname;
+    if (hostname === null) {
+        requireValue(value.generation === 0);
+    }
+    else {
+        requireValue(isClusterNodeHostname(hostname));
+    }
+    return Object.freeze({
+        nodeId: nodeId(value.nodeId),
+        hostname,
+        generation: hostname === null ? 0 : integer(value.generation, 1),
+        protocol: readProtocolOffer(value),
+    });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmtub2RlcmVwb3J0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zcGFya25vZGVyZXBvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDdkQsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDdkYsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBQy9ELE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxpQkFBaUIsRUFBdUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNuRyxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQTBDakUsOENBQThDO0FBQzlDLE1BQU0sQ0FBQyxNQUFNLDBCQUEwQixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDdEQsbUJBQW1CLEVBQUUsR0FBRztDQUNoQixDQUFDLENBQUM7QUE0Qlo7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3RELFFBQVEsRUFBRSx3QkFBd0I7SUFDbEMsZUFBZSxFQUFFLElBQUk7SUFDckIsZ0JBQWdCLEVBQUUsSUFBSTtJQUN0QixxQkFBcUIsRUFBRSx5QkFBeUI7Q0FDeEMsQ0FBQyxDQUFDO0FBRVosTUFBTSxJQUFJLEdBQUcsR0FBVSxFQUFFLEdBQUcsTUFBTSxJQUFJLEtBQUssQ0FBQyx5Q0FBeUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzFGLFNBQVMsWUFBWSxDQUFDLFFBQWlCO0lBQ3JDLElBQUksQ0FBQyxRQUFRO1FBQUUsSUFBSSxFQUFFLENBQUM7QUFDeEIsQ0FBQztBQUNELHNHQUFzRztBQUN0RyxNQUFNLE1BQU0sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBMEIsRUFBMkIsRUFBRTtJQUN4RixNQUFN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

package/dist_ts/requests/node.d.ts

@@ -110,6 +110,13 @@ export interface IReq_Any_Cloudly_CreateNodeJumpCommand extends plugins.typedreq
         role?: IClusterNode['data']['role'];
         nodeType?: IClusterNode['data']['nodeType'];
         ttlMs?: number;
+        /**
+         * The new node's name (`data.isClusterNodeName`). The setup command names the host
+         * `cloudly-worker-<nodeName>` (`data.deriveDefaultClusterNodeHostname`) before it enrolls, so
+         * the node enrolls under its default hostname. Absent, the node keeps the hostname it has and
+         * its name is proposed from that (`data.proposeClusterNodeName`).
+         */
+        nodeName?: string;
     };
     response: {
         jumpCode: string;
@@ -283,6 +290,58 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extend
         node: IClusterNode;
     };
 }
+/**
+ * An administrator renames a node: the static hostname Cloudly wants it to carry
+ * (`IClusterNode.data.hostnameIntent.hostname`).
+ *
+ * The node's name stays as it is: the new intent keeps the name of the node's current intent. A
+ * node without an intent takes the name `data.proposeClusterNodeName(hostname)` (`foo` names the
+ * node `foo`, `cloudly-worker-grasberg` names it `grasberg`), and is refused `name-invalid` when
+ * that is `null`.
+ *
+ * Cloudly records the intent and answers at once; Spark applies the intent of the latest
+ * generation on the host and the node has converged when its report states the new hostname. A new
+ * intent may replace one the node has not converged to, whether it is still applying, failed or
+ * never reached the node. `expectedGeneration` is the generation of the node's current intent, `0`
+ * when it has none, and serializes concurrent changes. Every refusal is one of
+ * `data.clusterNodeHostnameRefusals` and changes nothing.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetClusterNodeHostname> {
+    method: 'setClusterNodeHostname';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        expectedGeneration: number;
+        /** One lowercase RFC 1123 label (`data.isClusterNodeHostname`). */
+        hostname: string;
+    };
+    response: {
+        /** The node as it now stands, carrying the new intent. */
+        node: IClusterNode;
+    };
+}
+/**
+ * An administrator resets a node to the default scheme: hostname `cloudly-worker-<name>`
+ * (`data.deriveDefaultClusterNodeHostname`).
+ *
+ * `name` replaces the node's name when stated; absent, the name of the node's current intent is
+ * used, and a node without an intent is refused `name-invalid`. Recorded, applied and replaceable
+ * exactly like `setClusterNodeHostname`, with the same refusals.
+ */
+export interface IReq_Any_Cloudly_ResetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ResetClusterNodeHostname> {
+    method: 'resetClusterNodeHostname';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        expectedGeneration: number;
+        /** The node's name (`data.isClusterNodeName`). */
+        name?: string;
+    };
+    response: {
+        /** The node as it now stands, carrying the new intent. */
+        node: IClusterNode;
+    };
+}
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateNodeAction> {
     method: 'createNodeAction';
     request: {

package/dist_ts/requests/service.d.ts

@@ -9,7 +9,7 @@ import type { IImageRelease } from '../data/immutableimage.js';
 import type { IDeploymentPreflightReport, IDeploymentPreflightRequestData } from '../data/deploymentpreflight.js';
 import type { IDeploymentReservationInput, IServiceDeploymentOperation, IServiceDeploymentStatus } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
-import type { ILegacyServiceRuntimeAttestation } from '../data/deploymentlegacyimport.js';
+import type { ILegacyServiceHostObservation, ILegacyServiceRuntimeAttestation } from '../data/deploymentlegacyimport.js';
 import type { IProtocolOffer } from '../protocol.js';
 import type { IRuntimeAssignmentLogAttemptPage, IRuntimeAssignmentLogPage } from '../data/runtimeassignmentlogs.js';
 import type { IServiceRuntimeAssignmentView, IServiceRuntimeSpec, IServiceRuntimeStatus, TServiceRuntimeSpecWritableData } from '../data/serviceruntime.js';
@@ -224,10 +224,13 @@ export interface IRequest_Any_Cloudly_CleanupServiceDeployment extends plugins.t
     };
 }
 /**
- * Captures durable evidence that a legacy `deployOnPush` service runs exactly the registry root its
- * tag names: every required replica observed healthy on that one digest, with the root's platform
- * manifests read from Cloudly's own registry. Administrators only, and only while the legacy
- * runtime still runs — incomplete evidence is refused, never stored.
+ * Captures durable evidence that a legacy `deployOnPush` service runs exactly one registry root of
+ * its own repository, from an administrator's observation of its Swarm service and containers on
+ * the hosts that run them (`hostObservation`). Cloudly judges the observation itself
+ * (`data.judgeLegacyServiceHostObservation`): every desired replica running, healthy or without a
+ * healthcheck, on one root that is whole in Cloudly's own registry, its platform manifests read
+ * from there. The source tag need not still name that root. Administrators only, and only while
+ * the legacy runtime still runs — incomplete evidence is refused, never stored.
  *
  * `expectedRuntimeDigest`, when stated, is an assertion the observed digest must equal. Capturing
  * again for an unchanged digest returns the attestation already stored.
@@ -238,6 +241,7 @@ export interface IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation ext
         identity: IIdentityCredential;
         legacyServiceId: string;
         expectedRuntimeDigest?: TSha256Digest;
+        hostObservation: ILegacyServiceHostObservation;
     };
     response: {
         attestation: ILegacyServiceRuntimeAttestation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.50.0",
+  "version": "32.52.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -30,7 +30,7 @@
     "@git.zone/tsbuild": "^5.1.2",
     "@git.zone/tsdoc": "^3.0.2",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^7.1.0",
+    "@git.zone/tstest": "^7.2.0",
     "@types/node": "26.6.3"
   },
   "files": [

package/readme.md

@@ -203,6 +203,19 @@ current authority or workload readiness. Persist only the report and receipt in
 `IClusterNode.data.sparkNodeReport`, never the bearer. Keep legacy reporting
 separate. This endpoint does not deliver or acknowledge operator actions.
 
+`data.sparkNodeHostContract` defines the node's desired-host route,
+`/spark/nodes/host`, with 1024-byte request and response bounds, authenticated and
+judged in the same order as the heartbeat. `ISparkNodeHostRequest` carries the
+Spark bearer and the sender's offer; `ISparkNodeDesiredHost` answers with the whole
+desired value of `IClusterNode.data.hostnameIntent` — the hostname and its
+generation — never a change, and `hostname: null` with generation `0` states that
+Cloudly holds no intent, so Spark leaves the host's hostname as it is. Spark applies
+the latest generation and states the outcome of its last attempt as the optional
+`ISparkNodeReport.hostApply` (`applied`, or `failed` with a bounded reason) on its
+next heartbeat; the node has converged when `runtime.hostname` states the intent's
+hostname. A Spark that sends `hostApply` raises its `minimumPeerVersion` so it
+reaches only a Cloudly that reads it.
+
 The snapshot functions reject unknown keys, accessors, malformed identities and
 nonfinite/out-of-range numbers, then return detached frozen records. Transports
 own byte limits, timeouts and cancellation. These contracts do not implement a
@@ -2921,6 +2934,11 @@ Common data contracts include:
 
 - `ICluster` and `IClusterNode` for cluster membership and provisioning state, including the
   optional `ICluster.data.relay` block described below.
+- `clusternodehostname` for the static hostname Cloudly wants a node to carry:
+  `IClusterNodeHostnameIntent` on `IClusterNode.data.hostnameIntent`, the default scheme
+  `cloudly-worker-<name>` (`clusterNodeHostnameContract`, `deriveDefaultClusterNodeHostname`,
+  `proposeClusterNodeName`) and the named `clusterNodeHostnameRefusals` of
+  `setClusterNodeHostname` and `resetClusterNodeHostname`.
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
@@ -3640,7 +3658,7 @@ The immutable deployment workflow is:
 
 A legacy `deployOnPush` service without deployable source moves to a greenfield successor by a legacy import, which replaces step 2:
 
-- While the legacy replicas still run — before its runtime is frozen — an administrator captures the evidence with `captureLegacyServiceRuntimeAttestation` (`requests.service.IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation`). The stored `data.ILegacyServiceRuntimeAttestation` records every required replica healthy on one digest, the registry root the legacy tag names, and that root's platform manifests; `data.validateLegacyServiceRuntimeAttestation` states its rules. Incomplete evidence is refused, never stored, and there is no substitute once the runtime is stopped. `getLegacyServiceRuntimeAttestations` lists what Cloudly holds for a legacy service; both requests are for administrators only.
+- While the legacy replicas still run — before its runtime is frozen — an administrator reads the legacy Swarm service and every container of its tasks on the hosts that run them, and submits that as `hostObservation` (`data.ILegacyServiceHostObservation`: Swarm service name, spec image and mode with its desired replicas; per replica the node hostname, Swarm task id, container id, the engine's image store, the container's image id, the image's `RepoDigests`, the container state and its health, `none` when no healthcheck applies) to `captureLegacyServiceRuntimeAttestation` (`requests.service.IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation`). `data.validateLegacyServiceHostObservation` judges its shape, `data.selectLegacyServiceHostObservationRootDigest` names the one root every replica runs from the service's own repository, and `data.judgeLegacyServiceHostObservation` judges it against that root as Cloudly reads it from its own registry: exactly the desired replicas of a replicated service, its spec image naming the repository by the source tag or the root digest, every replica `running` and `healthy` or `none`, each container's image id the root digest on the containerd image store or one of the root's platform image configuration digests on the classic store. The source tag need not still name the root. The stored `data.ILegacyServiceRuntimeAttestation` records that root, its platform manifests, the replicas, the evidence source `administrator-host-observation` and the observation itself; `data.validateLegacyServiceRuntimeAttestation` states its rules. Incomplete evidence is refused, never stored, and there is no substitute once the runtime is stopped. `getLegacyServiceRuntimeAttestations` lists what Cloudly holds for a legacy service; both requests are for administrators only.
 - The greenfield reservation, and every preflight of it, names `legacyImport` (`data.ILegacyImageImportReference`: legacy service, attestation, asserted source root digest) instead of `sourceRevision`, `sourceDirty` and release evidence. Refusals are the blockers `LEGACY_IMPORT_ATTESTATION_MISSING`, `LEGACY_IMPORT_SOURCE_MISMATCH` and `LEGACY_IMPORT_PLATFORM_MISMATCH`.
 - Instead of the registry push, the deployer calls `importServiceDeploymentLegacyImage`: Cloudly imports the attested image from its own registry into the reserved tag — an index root as it is, a single platform manifest under a one-descriptor index of the manifest's own family — and records release evidence of source `cloudly-legacy-import` naming the legacy source. Steps 3 to 5 follow unchanged; `selectTrustedImageReleaseEvidence` accepts that evidence only with `evidenceSource: 'cloudly-legacy-import'`.
 - The reservation and the import need the capability `deployment:import-legacy`, which only an organization-service-slot grant can carry.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.50.0',
+  version: '32.52.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusternode.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import { isSha256Digest, type TSha256Digest, type TImmutableContainerPlatform } from './immutableimage.js';
 import type { ISparkNodeReportRecord } from './sparknodereport.js';
+import type { IClusterNodeHostnameIntent } from './clusternodehostname.js';
 import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
 import type { IPlatformDatabaseEndpoint } from '../platform/database.js';
 import {
@@ -1765,6 +1766,13 @@ export interface IClusterNode {
 
     /** Separately accepted Pallet-era host report; never grants workload readiness. */
     sparkNodeReport?: ISparkNodeReportRecord;
+
+    /**
+     * The static hostname Cloudly wants this node to carry, which Spark applies on the host. The
+     * node has converged when `sparkNodeReport` states the same hostname. Absent until enrollment
+     * or a migration records one; Spark then leaves the host's hostname as it is.
+     */
+    hostnameIntent?: IClusterNodeHostnameIntent;
     
     /**
      * Docker swarm node ID if part of swarm

package/ts/data/clusternodehostname.ts

@@ -0,0 +1,153 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+
+/**
+ * The static hostname a cluster node runs under, and the scheme Cloudly names a node by default.
+ *
+ * Cloudly owns the hostname a node should carry (`IClusterNode.data.hostnameIntent`); Spark applies
+ * it on the host and reports the hostname it observes, so a node has converged when its report
+ * states the intent's hostname. The default scheme is `cloudly-worker-<name>`: `name` is the
+ * operator's short name for the node (`ottilie`, `grasberg`), kept beside the hostname so the node
+ * can always be reset to the default however it was renamed.
+ *
+ * A hostname here is one RFC 1123 label, lowercase: the node's short static hostname, which is
+ * what enrollment already requires of a host. A fully qualified name is DNS, not the host's name.
+ */
+export const clusterNodeHostnameContract = Object.freeze({
+  /** The default hostname is this prefix followed by the node's name. */
+  defaultPrefix: 'cloudly-worker-',
+  /** One DNS label. */
+  maximumHostnameLength: 63,
+  /** What is left of one label after `defaultPrefix`. */
+  maximumNameLength: 48,
+  /** `requestedBy` is an identity's user id. */
+  maximumRequestedByLength: 256,
+  error: 'Cluster node hostname contract rejected.',
+} as const);
+
+const hostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** True for one lowercase RFC 1123 label of 1 to 63 characters: a node's static hostname. */
+export const isClusterNodeHostname = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= clusterNodeHostnameContract.maximumHostnameLength
+  && hostnameLabel.test(valueArg)
+);
+
+/** True for a node name the default scheme can carry: a label of at most 48 characters. */
+export const isClusterNodeName = (valueArg: unknown): valueArg is string => (
+  isClusterNodeHostname(valueArg) && valueArg.length <= clusterNodeHostnameContract.maximumNameLength
+);
+
+/** `cloudly-worker-<name>`; throws for a name the scheme cannot carry. */
+export const deriveDefaultClusterNodeHostname = (nameArg: string): string => {
+  if (!isClusterNodeName(nameArg)) {
+    throw new Error(clusterNodeHostnameContract.error);
+  }
+  return `${clusterNodeHostnameContract.defaultPrefix}${nameArg}`;
+};
+
+/**
+ * The node name an observed hostname suggests, or `null` when it suggests none.
+ *
+ * It reads the first label of the hostname, so a report that states a dotted name proposes its
+ * short name. A label already in the default scheme proposes what follows the prefix
+ * (`cloudly-worker-ottilie` → `ottilie`); any other valid label proposes itself unchanged
+ * (`cloudlyworkergrasberg` stays `cloudlyworkergrasberg`). It never guesses a name out of a
+ * label in another scheme: an operator states that name when resetting the node to the default.
+ */
+export const proposeClusterNodeName = (hostnameArg: string): string | null => {
+  const label = hostnameArg.split('.')[0];
+  if (!isClusterNodeHostname(label)) {
+    return null;
+  }
+  const prefix = clusterNodeHostnameContract.defaultPrefix;
+  if (label.startsWith(prefix) && isClusterNodeName(label.slice(prefix.length))) {
+    return label.slice(prefix.length);
+  }
+  return isClusterNodeName(label) ? label : null;
+};
+
+/** The hostname Cloudly wants a node to carry; `IClusterNode.data.hostnameIntent`. */
+export interface IClusterNodeHostnameIntent {
+  /** The node's name: the input of the default scheme, and what a reset to the default uses. */
+  name: string;
+  /** The static hostname the node should carry; the default derived from `name` or any other label. */
+  hostname: string;
+  /** Counts accepted intents from 1; a change names the generation it replaces. */
+  generation: number;
+  /** Unix milliseconds on Cloudly's clock when this intent was accepted. */
+  requestedAt: number;
+  /** The administrator who asked for it; absent for the intent enrollment or a migration recorded. */
+  requestedBy?: string;
+}
+
+/** True when the intent's hostname is the default its name derives. */
+export const isDefaultClusterNodeHostname = (intentArg: IClusterNodeHostnameIntent): boolean => (
+  isClusterNodeName(intentArg.name) && intentArg.hostname === deriveDefaultClusterNodeHostname(intentArg.name)
+);
+
+const fail = (): never => { throw new Error(clusterNodeHostnameContract.error); };
+function requireValue(valueArg: unknown): asserts valueArg {
+  if (!valueArg) fail();
+}
+const counter = (valueArg: unknown, minimumArg: number): number => {
+  requireValue(typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minimumArg);
+  return valueArg;
+};
+
+/** Exact, detached and frozen; refuses every key and value this contract does not state. */
+export const snapshotClusterNodeHostnameIntent = (valueArg: unknown): IClusterNodeHostnameIntent => {
+  const keys = ['name', 'hostname', 'generation', 'requestedAt'];
+  const value = readExactDataRecord(valueArg, keys) ?? readExactDataRecord(valueArg, [...keys, 'requestedBy']);
+  requireValue(value !== null);
+  requireValue(isClusterNodeName(value.name) && isClusterNodeHostname(value.hostname));
+  const intent: IClusterNodeHostnameIntent = {
+    name: value.name, hostname: value.hostname,
+    generation: counter(value.generation, 1), requestedAt: counter(value.requestedAt, 1),
+  };
+  if (Object.hasOwn(value, 'requestedBy')) {
+    const requestedBy = value.requestedBy;
+    requireValue(typeof requestedBy === 'string' && requestedBy.length > 0
+      && requestedBy.length <= clusterNodeHostnameContract.maximumRequestedByLength
+      && /^[\x21-\x7e]+$/.test(requestedBy));
+    intent.requestedBy = requestedBy;
+  }
+  return Object.freeze(intent);
+};
+
+/**
+ * Every reason Cloudly answers instead of renaming a node or resetting it to the default. Each
+ * travels by name as a `TypedResponseError`, and a refused request changes nothing.
+ */
+export const clusterNodeHostnameRefusals = Object.freeze([
+  /** No node of that id exists. */
+  'node-missing',
+  /** The requested hostname is not one lowercase RFC 1123 label (`isClusterNodeHostname`). */
+  'hostname-invalid',
+  /**
+   * The node would carry no name the default scheme can carry (`isClusterNodeName`). A rename keeps
+   * the name of the node's intent; a node without an intent takes
+   * `proposeClusterNodeName(<requested hostname>)`, and is refused when that is `null`. A reset
+   * names no valid name, or names none while the node has no intent whose name it could reuse.
+   */
+  'name-invalid',
+  /** Another node of the cluster carries that hostname, as reported or as its intent. */
+  'hostname-in-use',
+  /** The node's intent already is that hostname under that name. */
+  'hostname-unchanged',
+  /**
+   * Cloudly holds state naming the node by its current hostname that it cannot move to the new
+   * hostname with the change, such as a rollout in flight that targets the node.
+   */
+  'node-hostname-referenced',
+  /** The node does not run the Pallet-era node runtime, the only one that applies a hostname. */
+  'node-runtime-unsupported',
+  /**
+   * `expectedGeneration` is not the node's current intent generation: read the node again. This
+   * fence alone serializes changes; an intent the node has not converged to may always be replaced.
+   */
+  'conflict',
+] as const);
+
+/** One of the reasons Cloudly answers instead of a hostname change. */
+export type TClusterNodeHostnameRefusalCode = typeof clusterNodeHostnameRefusals[number];