@serve.zone/interfaces 31.5.0 → 31.7.0

package/dist_ts/requests/backup.d.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IArchivePruneResult, IArchiveRetentionPolicy, IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, IIsolatedRestoreNodeState, IIsolatedRestoreRecord, TBackupSnapshot, TIsolatedRestoreResourceMapping } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity, IIdentityCredential } from '../data/user.js';
+import type { ICorestoreDatabaseClosureDescriptor } from '../runtime.corestore.relay.js';
 export interface IReq_Any_Cloudly_CreateServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateServiceBackup> {
     method: 'createServiceBackup';
     request: {
@@ -48,6 +49,15 @@ export interface IReq_Any_Cloudly_RestoreServiceBackup extends plugins.typedrequ
         backup: IBackupRecord;
     };
 }
+/**
+ * Superseded by `backupClusterService`, which names the node.
+ *
+ * This method was dispatched at the coreflow that had tagged itself with the
+ * node's hostname; a cluster relay authors no tags and serves every node of its
+ * cluster, so the node it should act on can no longer be inferred from which
+ * connection answered. It is retired together with the tag in the coordinated
+ * major.
+ */
 export interface IReq_Cloudly_Coreflow_ExecuteServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_ExecuteServiceBackup> {
     method: 'executeServiceBackup';
     request: {
@@ -63,6 +73,7 @@ export interface IReq_Cloudly_Coreflow_ExecuteServiceBackup extends plugins.type
         replication?: IBackupReplicationResult;
     };
 }
+/** Superseded by `restoreClusterService`; see `executeServiceBackup`. */
 export interface IReq_Cloudly_Coreflow_ExecuteServiceRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_ExecuteServiceRestore> {
     method: 'executeServiceRestore';
     request: {
@@ -90,6 +101,14 @@ export interface IReq_Coreflow_Cloudly_PrepareBackupReplication extends plugins.
         missingObjects: IBackupArchiveObject[];
     };
 }
+/**
+ * Retiring: `contentsBase64` carries a whole archive object inside one JSON
+ * envelope, which costs a third of the payload in encoding and bounds a backup
+ * by the message ceiling rather than by the transport. `backupServiceDatabaseClosure`
+ * streams the same bytes as a VirtualStream. Removal is the coordinated major,
+ * once every relay and every Cloudly speak the streamed contract; Corestore
+ * already documents its repository-wide archive object routes as legacy.
+ */
 export interface IReq_Coreflow_Cloudly_UploadBackupArchiveObject extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Coreflow_Cloudly_UploadBackupArchiveObject> {
     method: 'uploadBackupArchiveObject';
     request: {
@@ -123,6 +142,7 @@ export interface IReq_Coreflow_Cloudly_GetBackupArchiveManifest extends plugins.
         manifest: IBackupArchiveManifest;
     };
 }
+/** Retiring with `uploadBackupArchiveObject`; `restoreServiceDatabaseClosure` replaces it. */
 export interface IReq_Coreflow_Cloudly_DownloadBackupArchiveObject extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Coreflow_Cloudly_DownloadBackupArchiveObject> {
     method: 'downloadBackupArchiveObject';
     request: {
@@ -135,6 +155,7 @@ export interface IReq_Coreflow_Cloudly_DownloadBackupArchiveObject extends plugi
         contentsBase64: string;
     };
 }
+/** Superseded by `pruneClusterNodeArchive`; see `executeServiceBackup`. */
 export interface IReq_Cloudly_Coreflow_PruneNodeArchive extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_PruneNodeArchive> {
     method: 'coreflowPruneNodeArchive';
     request: {
@@ -146,6 +167,127 @@ export interface IReq_Cloudly_Coreflow_PruneNodeArchive extends plugins.typedreq
         result?: IArchivePruneResult;
     };
 }
+/**
+ * Backs up one service on one exact node of this cluster.
+ *
+ * The cluster relay serves every node of its cluster over one session, so the
+ * node is a request field: the connection that answers proves which cluster is
+ * speaking, never which node is meant. Everything else is what
+ * `executeServiceBackup` carried, so a caller moving to this method changes its
+ * routing and nothing about its backup.
+ */
+export interface IReq_Cloudly_Relay_BackupClusterService extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Relay_BackupClusterService> {
+    method: 'backupClusterService';
+    request: {
+        /** The cluster node whose Corestore holds this service's data. */
+        nodeId: string;
+        backupId: string;
+        service: IService;
+        tags?: Record<string, string>;
+        replication?: {
+            enabled: boolean;
+        };
+    };
+    response: {
+        snapshots: TBackupSnapshot[];
+        replication?: IBackupReplicationResult;
+    };
+}
+/** Restores one service on one exact node of this cluster; see `backupClusterService`. */
+export interface IReq_Cloudly_Relay_RestoreClusterService extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Relay_RestoreClusterService> {
+    method: 'restoreClusterService';
+    request: {
+        /** The cluster node whose Corestore receives the restore. */
+        nodeId: string;
+        backupId: string;
+        service: IService;
+        snapshots: TBackupSnapshot[];
+        clear?: boolean;
+        resourceTypes?: Array<TBackupSnapshot['type']>;
+        replication?: {
+            enabled: boolean;
+        };
+    };
+    response: {
+        restored: TBackupSnapshot[];
+    };
+}
+/**
+ * Prunes the archive of one exact node of this cluster.
+ *
+ * `found` stays false when that node has no archive to prune, which is a fact
+ * about the node rather than a failure of the relay.
+ */
+export interface IReq_Cloudly_Relay_PruneClusterNodeArchive extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Relay_PruneClusterNodeArchive> {
+    method: 'pruneClusterNodeArchive';
+    request: {
+        /** The cluster node whose archive is pruned. */
+        nodeId: string;
+        retention: IArchiveRetentionPolicy;
+        dryRun?: boolean;
+    };
+    response: {
+        found: boolean;
+        result?: IArchivePruneResult;
+    };
+}
+/**
+ * The relay carries one service database closure to Cloudly.
+ *
+ * Relay-initiated, like every other byte a cluster sends: a cluster is
+ * outbound-only, so Cloudly cannot pull from it. The relay exports the closure
+ * from its node's Corestore and sends those exact bytes on its own session.
+ *
+ * `accepted` permits sending; it never confirms storage. The stream's own
+ * acceptance receipt, observed through `completion`, is what confirms that
+ * Cloudly durably holds the closure — exactly as `pushImageVersion` works.
+ *
+ * No identity field: the cluster is the one the verified machine identity on
+ * the relay's own session names, exactly as `getClusterRouteTable` and
+ * `getClusterPlatformDesiredState` work. A request-level identity would be a
+ * second authority for the same fact, and the weaker of the two.
+ */
+export interface IReq_Relay_Cloudly_BackupServiceDatabaseClosure extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Relay_Cloudly_BackupServiceDatabaseClosure> {
+    method: 'backupServiceDatabaseClosure';
+    request: {
+        backupId: string;
+        serviceId: string;
+        /** The cluster node this closure was exported from. */
+        nodeId: string;
+        /** Exact bytes and Corestore's receipt for them; validated before any byte moves. */
+        descriptor: ICorestoreDatabaseClosureDescriptor;
+        /** Requester sends closure bytes; the TypedHandler receives the opposite endpoint. */
+        closure: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+    };
+    response: {
+        accepted: boolean;
+    };
+}
+/**
+ * The relay fetches one service database closure back from Cloudly.
+ *
+ * The descriptor arrives with the stream rather than after it, because
+ * Corestore's restore needs the exact byte length and receipt before the first
+ * byte is written: the relay opens its Corestore request from this descriptor
+ * and only then drains the stream into it.
+ *
+ * No identity field, for the same reason as `backupServiceDatabaseClosure`: the
+ * relay's own session names the cluster.
+ */
+export interface IReq_Relay_Cloudly_RestoreServiceDatabaseClosure extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Relay_Cloudly_RestoreServiceDatabaseClosure> {
+    method: 'restoreServiceDatabaseClosure';
+    request: {
+        backupId: string;
+        serviceId: string;
+        /** The cluster node the closure is restored onto. */
+        nodeId: string;
+    };
+    response: {
+        descriptor: ICorestoreDatabaseClosureDescriptor;
+        /** Requester receives closure bytes; the TypedHandler returns a sender endpoint. */
+        closure: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+    };
+}
 /**
  * Creates a restore in a new non-runnable data-plane scratch namespace.
  * Cloudly derives clusterId and sourceServiceId from the authoritative backup,
@@ -225,6 +367,18 @@ export interface IReq_Any_Cloudly_GetIsolatedRestoreById extends plugins.typedre
 export interface IReq_Cloudly_Coreflow_PrepareIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_PrepareIsolatedRestore> {
     method: 'coreflowPrepareIsolatedRestore';
     request: {
+        /**
+         * The compact RS256 restore grant Cloudly signed for exactly this
+         * operation, carried untouched to Corestore.
+         *
+         * Corestore accepts no other authority on an isolated-restore route: the
+         * grant names the operation, expires within minutes, and binds the cluster,
+         * the node, the canonical resource mappings and the archive manifest, so a
+         * relay can carry it but can neither widen it nor mint one. Sensitive
+         * ephemeral input: exclude the complete request from hooks, logs and
+         * journals on every hop.
+         */
+        restoreGrant: string;
         clusterId: string;
         targetNodeName: string;
         restoreId: string;
@@ -240,10 +394,55 @@ export interface IReq_Cloudly_Coreflow_PrepareIsolatedRestore extends plugins.ty
         state: IIsolatedRestoreNodeState;
     };
 }
+/**
+ * Cloudly stages one archive object of an isolated restore on the relay's node.
+ *
+ * Cloudly holds the source backup, so these bytes travel Cloudly → relay and
+ * the requester is the sender. One object per call, as the archive manifest
+ * lists it: Corestore writes staged objects under a `write-object` grant, one
+ * bounded chunk at a time, and the relay is what turns this stream into those
+ * chunks. The object descriptor is the manifest entry itself — path, exact size
+ * and digest — so the relay can prove the complete object before it counts as
+ * written, and so a replayed stage settles on the same bytes.
+ */
+export interface IReq_Cloudly_Relay_StageIsolatedRestoreArchive extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Relay_StageIsolatedRestoreArchive> {
+    method: 'stageIsolatedRestoreArchive';
+    request: {
+        /**
+         * The compact RS256 restore grant for the `write-object` operation, carried
+         * untouched to Corestore. Sensitive ephemeral input, like every other
+         * grant on these routes.
+         */
+        restoreGrant: string;
+        clusterId: string;
+        targetNodeName: string;
+        restoreId: string;
+        expectedRevision: number;
+        /** The manifest entry these bytes complete: `path`, `size`, `sha256`. */
+        object: IBackupArchiveObject;
+        /** Requester sends the object bytes; the TypedHandler receives them. */
+        archive: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+    };
+    response: {
+        state: IIsolatedRestoreNodeState;
+    };
+}
 /** Read-only status for one exact cluster/node/restore routing key. */
 export interface IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus> {
     method: 'coreflowGetIsolatedRestoreStatus';
     request: {
+        /**
+         * The compact RS256 restore grant Cloudly signed for exactly this
+         * operation, carried untouched to Corestore.
+         *
+         * Corestore accepts no other authority on an isolated-restore route: the
+         * grant names the operation, expires within minutes, and binds the cluster,
+         * the node, the canonical resource mappings and the archive manifest, so a
+         * relay can carry it but can neither widen it nor mint one. Sensitive
+         * ephemeral input: exclude the complete request from hooks, logs and
+         * journals on every hop.
+         */
+        restoreGrant: string;
         clusterId: string;
         targetNodeName: string;
         restoreId: string;
@@ -256,6 +455,18 @@ export interface IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus extends plugins.
 export interface IReq_Cloudly_Coreflow_ExecuteIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_ExecuteIsolatedRestore> {
     method: 'coreflowExecuteIsolatedRestore';
     request: {
+        /**
+         * The compact RS256 restore grant Cloudly signed for exactly this
+         * operation, carried untouched to Corestore.
+         *
+         * Corestore accepts no other authority on an isolated-restore route: the
+         * grant names the operation, expires within minutes, and binds the cluster,
+         * the node, the canonical resource mappings and the archive manifest, so a
+         * relay can carry it but can neither widen it nor mint one. Sensitive
+         * ephemeral input: exclude the complete request from hooks, logs and
+         * journals on every hop.
+         */
+        restoreGrant: string;
         clusterId: string;
         targetNodeName: string;
         restoreId: string;
@@ -272,6 +483,18 @@ export interface IReq_Cloudly_Coreflow_ExecuteIsolatedRestore extends plugins.ty
 export interface IReq_Cloudly_Coreflow_CleanupIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_CleanupIsolatedRestore> {
     method: 'coreflowCleanupIsolatedRestore';
     request: {
+        /**
+         * The compact RS256 restore grant Cloudly signed for exactly this
+         * operation, carried untouched to Corestore.
+         *
+         * Corestore accepts no other authority on an isolated-restore route: the
+         * grant names the operation, expires within minutes, and binds the cluster,
+         * the node, the canonical resource mappings and the archive manifest, so a
+         * relay can carry it but can neither widen it nor mint one. Sensitive
+         * ephemeral input: exclude the complete request from hooks, logs and
+         * journals on every hop.
+         */
+        restoreGrant: string;
         clusterId: string;
         targetNodeName: string;
         restoreId: string;

package/dist_ts/requests/corestore.d.ts

@@ -19,6 +19,10 @@ export interface ICorestoreServiceResources {
 /**
  * Corestore inventory of one node (each coreflow node runs its own corestore;
  * the data is node-local, which is what makes node placement matter).
+ *
+ * Superseded by `IClusterCorestoreInventory`, which names the node by its
+ * cluster-document id instead of by the Swarm hostnames a connection tagged
+ * itself with.
  */
 export interface ICorestoreNodeInventory {
     /** Swarm node hostnames of the reporting coreflow. */
@@ -63,6 +67,35 @@ export interface ICoreflowInventoryRegistration {
     reporterSessionId: string;
     registeredAt: number;
 }
+/**
+ * What one node's Corestore holds, as the cluster relay read it.
+ *
+ * Node identity is the cluster document's node id: one relay serves every node
+ * of its cluster, so which node an inventory describes is stated, never derived
+ * from which connection answered. An unreachable node names why — `errorCode`
+ * is required whenever `reachable` is false and refused whenever it is true —
+ * because a node whose Corestore cannot be reached is a fact the control plane
+ * needs, and a silent empty inventory would read as "nothing provisioned",
+ * which is the opposite.
+ */
+export interface IClusterCorestoreInventory {
+    nodeId: string;
+    checkedAt: number;
+    reachable: boolean;
+    errorCode?: 'CORESTORE_ENDPOINT_UNKNOWN' | 'CORESTORE_UNREACHABLE';
+    services: ICorestoreServiceResources[];
+}
+/**
+ * Validates one cluster Corestore inventory and names every reason it is
+ * refused.
+ *
+ * Shape only. Whether that node belongs to the cluster, and whether a resource
+ * should exist, are decisions for the control plane that asked; an inventory
+ * that passes here has claimed neither. A reachable inventory that names an
+ * error, and an unreachable one that lists resources, are both refused: an
+ * answer has to be one of the two things it can be.
+ */
+export declare const validateClusterCorestoreInventory: (valueArg: unknown, pathArg?: string) => string[];
 export interface IReq_Any_Cloudly_GetCorestoreInventory extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetCorestoreInventory> {
     method: 'getCorestoreInventory';
     request: {
@@ -70,6 +103,30 @@ export interface IReq_Any_Cloudly_GetCorestoreInventory extends plugins.typedreq
     };
     response: ICorestoreInventoryReport;
 }
+/**
+ * Cloudly asks the relay what one exact node of its cluster holds.
+ *
+ * The node is a request field because one relay serves them all: the connection
+ * that answers proves the cluster, never the node. A greenfield cluster answers
+ * with an empty `services` list and `reachable: true`, which is the proof that
+ * a namespace is blank — distinct from `reachable: false`, which proves
+ * nothing at all.
+ *
+ * Named apart from `getCorestoreInventory` on purpose: that method is Cloudly's
+ * own operator-facing read and lives on the other end of this socket. One name
+ * on both ends would leave direction as the only thing telling two different
+ * bodies apart.
+ */
+export interface IReq_Cloudly_Relay_GetClusterCorestoreInventory extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Relay_GetClusterCorestoreInventory> {
+    method: 'getClusterCorestoreInventory';
+    request: {
+        nodeId: string;
+    };
+    response: {
+        inventory: IClusterCorestoreInventory;
+    };
+}
+/** Superseded by `getClusterCorestoreInventory`, which names the node. */
 export interface IReq_Cloudly_Coreflow_GetCorestoreInventory extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_GetCorestoreInventory> {
     method: 'coreflowGetCorestoreInventory';
     request: Record<string, never>;

package/dist_ts/requests/corestore.js

@@ -1,2 +1,103 @@
 import * as plugins from '../plugins.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29yZXN0b3JlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcmVxdWVzdHMvY29yZXN0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=
+const clusterCorestoreInventoryIdentifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const isClusterCorestoreRecord = (valueArg) => (Boolean(valueArg)
+    && typeof valueArg === 'object'
+    && !Array.isArray(valueArg)
+    && (Object.getPrototypeOf(valueArg) === Object.prototype
+        || Object.getPrototypeOf(valueArg) === null));
+const hasClusterCorestoreKeys = (valueArg, keysArg, optionalKeysArg = []) => {
+    const actualKeys = Object.keys(valueArg);
+    return keysArg.every((keyArg) => actualKeys.includes(keyArg))
+        && actualKeys.every((keyArg) => keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg));
+};
+const validateClusterCorestoreServiceResources = (valueArg, pathArg) => {
+    if (!isClusterCorestoreRecord(valueArg)
+        || !hasClusterCorestoreKeys(valueArg, ['serviceId', 'resources', 'updatedAt'], ['serviceName'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (typeof valueArg.serviceId !== 'string'
+        || !clusterCorestoreInventoryIdentifierPattern.test(valueArg.serviceId)) {
+        errors.push(`${pathArg} serviceId must be a bounded identifier`);
+    }
+    if (!Number.isSafeInteger(valueArg.updatedAt) || valueArg.updatedAt < 0) {
+        errors.push(`${pathArg} updatedAt must be a non-negative safe integer`);
+    }
+    if (!Array.isArray(valueArg.resources)) {
+        errors.push(`${pathArg} resources must be an array`);
+        return errors;
+    }
+    for (const [index, resource] of valueArg.resources.entries()) {
+        const resourcePath = `${pathArg} resources[${index}]`;
+        if (!isClusterCorestoreRecord(resource)
+            || !hasClusterCorestoreKeys(resource, ['capability', 'provider', 'resourceName', 'createdAt'])) {
+            errors.push(`${resourcePath} must use its exact schema`);
+            continue;
+        }
+        if (resource.capability !== 'database' && resource.capability !== 'objectstorage') {
+            errors.push(`${resourcePath} capability must be database or objectstorage`);
+        }
+        if (typeof resource.provider !== 'string' || resource.provider.length === 0) {
+            errors.push(`${resourcePath} provider must be a non-empty string`);
+        }
+        if (typeof resource.resourceName !== 'string' || resource.resourceName.length === 0) {
+            errors.push(`${resourcePath} resourceName must be a non-empty string`);
+        }
+        if (!Number.isSafeInteger(resource.createdAt) || resource.createdAt < 0) {
+            errors.push(`${resourcePath} createdAt must be a non-negative safe integer`);
+        }
+    }
+    return errors;
+};
+/**
+ * Validates one cluster Corestore inventory and names every reason it is
+ * refused.
+ *
+ * Shape only. Whether that node belongs to the cluster, and whether a resource
+ * should exist, are decisions for the control plane that asked; an inventory
+ * that passes here has claimed neither. A reachable inventory that names an
+ * error, and an unreachable one that lists resources, are both refused: an
+ * answer has to be one of the two things it can be.
+ */
+export const validateClusterCorestoreInventory = (valueArg, pathArg = 'cluster corestore inventory') => {
+    if (!isClusterCorestoreRecord(valueArg)
+        || !hasClusterCorestoreKeys(valueArg, ['nodeId', 'checkedAt', 'reachable', 'services'], ['errorCode'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (typeof valueArg.nodeId !== 'string'
+        || !clusterCorestoreInventoryIdentifierPattern.test(valueArg.nodeId)) {
+        errors.push(`${pathArg} nodeId must be a bounded identifier`);
+    }
+    if (!Number.isSafeInteger(valueArg.checkedAt) || valueArg.checkedAt < 0) {
+        errors.push(`${pathArg} checkedAt must be a non-negative safe integer`);
+    }
+    if (typeof valueArg.reachable !== 'boolean') {
+        errors.push(`${pathArg} reachable must be a boolean`);
+    }
+    if (valueArg.errorCode !== undefined
+        && valueArg.errorCode !== 'CORESTORE_ENDPOINT_UNKNOWN'
+        && valueArg.errorCode !== 'CORESTORE_UNREACHABLE') {
+        errors.push(`${pathArg} errorCode must name why the node could not be read`);
+    }
+    if (valueArg.reachable === true && valueArg.errorCode !== undefined) {
+        errors.push(`${pathArg} must not carry an errorCode while it reports the node reachable`);
+    }
+    if (valueArg.reachable === false && valueArg.errorCode === undefined) {
+        // An unreachable node with no reason reads like a node holding nothing,
+        // which is the one confusion this shape exists to prevent.
+        errors.push(`${pathArg} must name why the node could not be read while it reports it unreachable`);
+    }
+    if (!Array.isArray(valueArg.services)) {
+        errors.push(`${pathArg} services must be an array`);
+        return errors;
+    }
+    if (valueArg.reachable === false && valueArg.services.length > 0) {
+        errors.push(`${pathArg} must list no services while it reports the node unreachable`);
+    }
+    for (const [index, service] of valueArg.services.entries()) {
+        errors.push(...validateClusterCorestoreServiceResources(service, `${pathArg} services[${index}]`));
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29yZXN0b3JlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcmVxdWVzdHMvY29yZXN0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDO0FBNEd6QyxNQUFNLDBDQUEwQyxHQUFHLHFDQUFxQyxDQUFDO0FBRXpGLE1BQU0sd0JBQXdCLEdBQUcsQ0FDL0IsUUFBaUIsRUFDb0IsRUFBRSxDQUFDLENBQ3hDLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDZCxPQUFPLFFBQVEsS0FBSyxRQUFRO09BQzVCLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDeEIsQ0FBQyxNQUFNLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTO1dBQ25ELE1BQU0sQ0FBQyxjQUFjLENBQUMsUUFBUSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQy9DLENBQUM7QUFFRixNQUFNLHVCQUF1QixHQUFHLENBQzlCLFFBQWlDLEVBQ2pDLE9BQTBCLEVBQzFCLGtCQUFxQyxFQUFFLEVBQzlCLEVBQUU7SUFDWCxNQUFNLFVBQVUsR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQ3pDLE9BQU8sT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUMsVUFBVSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsQ0FBQztXQUN4RCxVQUFVLENBQUMsS0FBSyxDQUFDLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxPQUFPLENBQUMsUUFBUSxDQUFDLE1BQU0sQ0FBQyxJQUFJLGVBQWUsQ0FBQyxRQUFRLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztBQUNsRyxDQUFDLENBQUM7QUFFRixNQUFNLHdDQUF3QyxHQUFHLENBQy9DLFFBQWlCLEVBQ2pCLE9BQWUsRUFDTCxFQUFFO0lBQ1osSUFBSSxDQUFDLHdCQUF3QixDQUFD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

package/dist_ts/requests/node.d.ts

@@ -150,6 +150,37 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
         ok: boolean;
     };
 }
+/**
+ * An administrator states where one node's Corestore control API answers.
+ *
+ * Corestore is node-local, so one relay serving a whole cluster must be told per node where to
+ * dial; the cluster-local alias every component used while Docker Swarm resolved it is exactly
+ * what stops resolving. The endpoint is control-plane state Cloudly owns and the relay reads,
+ * so an administrator sets it here rather than a relay discovering it.
+ *
+ * Cloudly validates the endpoint with `validateClusterNodeCorestore` before it writes, takes the
+ * node's own real-write fence inside the writing transaction so a concurrent deletion conflicts
+ * instead of leaving an endpoint behind for a node that is gone, and pushes the cluster
+ * configuration afterwards so every connected relay learns the change without reconnecting.
+ *
+ * `endpoint: null` clears it, which is the same fact as never having set one: the node runs no
+ * Corestore the relay may reach, and an inventory for it answers
+ * `errorCode: 'CORESTORE_ENDPOINT_UNKNOWN'` rather than guessing a hostname. The endpoint says
+ * where, never with what — no credential travels in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint> {
+    method: 'setClusterNodeCorestoreEndpoint';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        /** A canonical `http:` or `https:` origin, or `null` to state that this node has none. */
+        endpoint: string | null;
+    };
+    response: {
+        /** The node as it now stands, so a caller needs no second read to see what it set. */
+        node: IClusterNode;
+    };
+}
 export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Spark_Cloudly_SendHeartbeat> {
     method: 'sparkNodeHeartbeat';
     request: {

package/dist_ts/requests/platform.d.ts

@@ -12,6 +12,36 @@ export interface IReq_Any_Cloudly_GetPlatformDesiredState extends plugins.typedr
         bindings: IPlatformBinding[];
     };
 }
+/**
+ * One platform binding and the node its Corestore resources live on.
+ *
+ * Corestore is node-local, so a binding without a node is a database nobody can
+ * place: while every cluster ran one coreflow per node, "this node" was whoever
+ * answered, and a cluster relay serving every node has no such implicit answer.
+ * The placement is Cloudly's, derived from where the service is assigned.
+ */
+export interface IClusterPlatformBindingPlacement {
+    nodeId: string;
+    binding: IPlatformBinding;
+}
+/**
+ * The desired platform state for the relay's own cluster, node by node.
+ *
+ * Its session decides which cluster it speaks for, so the request carries no
+ * cluster of its own. It replaces `getPlatformDesiredState` for a cluster
+ * relay: the same capabilities and provider configs, and bindings that state
+ * where they belong instead of leaving it to be inferred.
+ */
+export interface IReq_Relay_Cloudly_GetClusterPlatformDesiredState extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Relay_Cloudly_GetClusterPlatformDesiredState> {
+    method: 'getClusterPlatformDesiredState';
+    request: Record<string, never>;
+    response: {
+        capabilities: IPlatformCapability[];
+        providerConfigs: IPlatformProviderConfig[];
+        /** Sorted by node, then by binding id, so two reads compare directly. */
+        bindings: IClusterPlatformBindingPlacement[];
+    };
+}
 export interface IReq_Any_Cloudly_GetPlatformCapabilities extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetPlatformCapabilities> {
     method: 'getPlatformCapabilities';
     request: {

package/dist_ts/runtime.corestore.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import type { IActiveSecretRecipientMetadata, IIdentityCredential, ISecretVersionReference } from './data/index.js';
+import type { IActiveSecretRecipientMetadata, ICorestoreDatabaseAllocationReference, IIdentityCredential, ISecretVersionReference } from './data/index.js';
 import type { ISecretEnvelopeAdmissionBindingV1 } from './runtime.js';
 import type { IObjectStorageRetentionIntentV1, IObjectStorageRetentionEvidenceExpectationV1, IObjectStorageRetentionEvidenceV1 } from './platform/objectstorageretention.js';
 export type TCorestoreCredentialCapability = 'database' | 'objectstorage';
@@ -257,14 +257,12 @@ export declare const corestoreDatabaseBackupRuntimeLimits: Readonly<{
     maximumClosureChunks: 1000000;
     maximumServiceNameBytes: 1024;
 }>;
-export interface ICorestoreDatabaseAllocationReference {
-    purpose: 'scratch-rehearsal';
-    rehearsalId: string;
-    allocationId: string;
-    generation: number;
-    bindingSha256: string;
-    receiptSha256: string;
-}
+/**
+ * Declared in the data tree, because an isolated restore's canonical resource
+ * mappings bind the exact same reference and that tree carries no runtime
+ * import. Re-exported here so this module's readers keep one import site.
+ */
+export type { ICorestoreDatabaseAllocationReference };
 export interface ICorestoreDatabaseBackupSnapshotTags {
     corestore: 'resource';
     serviceId: string;
@@ -336,4 +334,3 @@ export declare const computeCorestoreDatabaseAllocationReferenceSha256: (valueAr
 export declare const computeCorestoreDatabaseBackupReceiptSha256: (valueArg: unknown) => Promise<string>;
 export declare const computeCorestoreDatabaseBackupRestoreRequestSha256: (valueArg: unknown) => Promise<string>;
 export declare const computeCorestoreDatabaseBackupRestoreResponseSha256: (valueArg: unknown) => Promise<string>;
-export {};