@serve.zone/interfaces 32.22.0 → 32.24.0

package/ts/data/runtimelocalstorageclaim.ts

@@ -6,17 +6,77 @@ import { snapshotRuntimeSessionBinding } from './runtimesession.js';
 import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
   networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
 } from '../private/networkcontract.js';
+import { parseCanonicalIpAddress } from '../private/ipaddress.js';
 import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
 import { createStorageContractReaders } from '../private/storagecontract.js';
 
+/** A node-local directory the node derives from the claim's identity under a root only the node knows. */
+export type TRuntimeLocalStorageDirectorySource = {
+  kind: 'directory';
+};
+
+/**
+ * A directory on an NFS export. The node mounts `server:export` and uses `subPath` below it.
+ *
+ * `server` is a lowercase fully qualified hostname or a canonical IP literal, on the standard port.
+ * `export` is the canonical absolute path the server exports, `/` included. `subPath` is the
+ * volume's directory below the export, as canonical relative segments, or `.` for the export
+ * itself. `version` pins one protocol version. NFS authenticates the node's host, not a user, so
+ * the source names no credential.
+ */
+export type TRuntimeLocalStorageNfsSource = {
+  kind: 'nfs';
+  server: string;
+  export: string;
+  subPath: string;
+  version: TRuntimeLocalStorageNfsVersion;
+};
+
 /**
- * Where a local storage claim's bytes live, named by kind and never by path.
+ * A directory on an SMB share. The node mounts `//server/share` and uses `subPath` below it.
  *
- * `directory` is a node-local directory the node derives from the claim's identity under a root
- * only the node knows. Network filesystems join this union as further kinds; their credentials
- * travel as secrets and never inside a claim.
+ * `server` and `subPath` follow the NFS rules; `share` is one share name. `version` pins one
+ * dialect. `credential` names the credential authority the node authenticates with, by reference
+ * only: the claim never carries a user name, password or domain, and the node resolves the material
+ * through the controller's secret delivery.
  */
-export type TRuntimeLocalStorageSource = { kind: 'directory' };
+export type TRuntimeLocalStorageSmbSource = {
+  kind: 'smb';
+  server: string;
+  share: string;
+  subPath: string;
+  version: TRuntimeLocalStorageSmbVersion;
+  credential: IRuntimeAuthorityReference;
+};
+
+/**
+ * Where a local storage claim's bytes live, named by kind and never by a node's host path.
+ *
+ * A network source names the remote location and nothing about how to mount it: no mount option,
+ * no port and no credential value. The node derives every mount parameter from these fields alone.
+ * The kinds are type aliases, as `{ kind: 'directory' }` always was, so a source stays assignable
+ * to a plain record.
+ */
+export type TRuntimeLocalStorageSource =
+  | TRuntimeLocalStorageDirectorySource
+  | TRuntimeLocalStorageNfsSource
+  | TRuntimeLocalStorageSmbSource;
+
+/**
+ * The NFS protocol versions a claim may pin, spelled as the kernel's NFS `vers=` parameter spells
+ * them. NFS version 4 is always stated with its minor version: the bare `4` negotiates one, which
+ * the kernel keeps only for backward compatibility, and a claim must mean the same mount on every
+ * node. Version 2 is refused.
+ */
+export type TRuntimeLocalStorageNfsVersion = (typeof runtimeLocalStorageClaimContract.nfsVersions)[number];
+
+/**
+ * The SMB dialects a claim may pin, spelled as the kernel's CIFS `vers=` parameter spells them.
+ * Only SMB 3 dialects, the first that encrypt; the kernel refuses 1.0 and 2.0 unless built with
+ * insecure legacy dialects. `3` alone negotiates one and is refused for the same reason as a bare
+ * NFS `4`.
+ */
+export type TRuntimeLocalStorageSmbVersion = (typeof runtimeLocalStorageClaimContract.smbVersions)[number];
 
 /** The owner and permission bits a node gives an `empty` volume's root directory when it creates it. */
 export interface IRuntimeLocalStorageOwnership {
@@ -39,15 +99,19 @@ export interface IRuntimeLocalStorageMount {
 export type TRuntimeLocalStorageLifecycle = 'bound' | 'purge';
 
 /**
- * A controller's authority for one retained, node-local volume of one service.
+ * A controller's authority for one retained volume of one service, mounted on one node.
  *
- * Cloudly and Onebox issue it alike. It names the volume by identity only: no host path, no
- * device, no mount option and no credential. The node resolves the identity to its own storage.
+ * Cloudly and Onebox issue it alike. It never names a host path, a device, a mount option or a
+ * credential value. A `directory` source names the volume by identity only, and the node resolves
+ * it to its own storage; a network source names the remote directory and, for SMB, the credential
+ * by reference.
  *
  * `initialization` says what the node does when the volume does not exist yet. `empty` creates an
  * empty root with `initialOwnership`, which it must state, so a workload that runs as the image's
  * own user never meets a root-owned directory by accident. `import` waits for the volume's bytes to
- * be imported and states no ownership: an imported tree keeps the ownership it carries.
+ * be imported and states no ownership: an imported tree keeps the ownership it carries. SMB carries
+ * no POSIX ownership, so the node presents an SMB volume with `initialOwnership`, and an `smb`
+ * source is always `empty`.
  */
 export interface IRuntimeLocalStorageClaim {
   id: string;
@@ -104,6 +168,16 @@ export const runtimeLocalStorageClaimContract = Object.freeze({
   reclaimPolicy: 'retain',
   /** Every permission bit a claim may state: setgid, sticky and the rwx triplets. */
   directoryModeBits: 0o3777,
+  nfsVersions: ['3', '4.0', '4.1', '4.2'],
+  smbVersions: ['3.0', '3.02', '3.1.1'],
+  /** The longest hostname a network source may name, in characters. */
+  maximumServerLength: 253,
+  /** The longest `export` or `subPath`, in characters; every character is printable ASCII. */
+  maximumPathLength: 1024,
+  /** The longest segment of an `export` or `subPath`. */
+  maximumSegmentLength: 255,
+  /** The longest SMB share name. */
+  maximumShareLength: 80,
 } as const);
 
 const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
@@ -112,7 +186,90 @@ const { readMountPath } = createStorageContractReaders(fail);
 const claimStates = ['ready', 'import-required', 'purged', 'uncertain'] as const;
 const responseStatuses = ['accepted', 'replay', 'historical'] as const;
 
+const hostnameLabelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Printable ASCII without a space. One spelling per name, so two claims cannot name one directory
+ * two ways, and nothing a mount source or an option string reads as a separator.
+ */
+const printableAsciiPattern = /^[\x21-\x7e]+$/;
+/** A comma or `=` would read as a mount option; the rest have meaning in a mount source or an SMB name. */
+const pathSegmentForbiddenPattern = /["*,/:<=>?\\|]/;
+/** SMB refuses these in a share name, beyond what it refuses in a path segment. */
+const shareForbiddenPattern = /[+;\[\]]/;
+
+/**
+ * A lowercase fully qualified hostname of two or more labels whose last label is not numeric, or a
+ * canonical IP literal. One label would resolve through each node's own search domains; a numeric
+ * last label would let a non-canonical address pass as a hostname. There is no port and no
+ * userinfo: the node connects to the protocol's standard port.
+ */
+const serverOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string');
+  if (parseCanonicalIpAddress(valueArg) !== null) return valueArg;
+  const labels = valueArg.split('.');
+  requireNetwork(valueArg.length <= runtimeLocalStorageClaimContract.maximumServerLength && labels.length >= 2
+    && labels.every((labelArg) => hostnameLabelPattern.test(labelArg))
+    && !/^[0-9]+$/.test(labels[labels.length - 1]));
+  return valueArg;
+};
+
+const isPathSegment = (valueArg: string): boolean =>
+  valueArg.length <= runtimeLocalStorageClaimContract.maximumSegmentLength
+  && printableAsciiPattern.test(valueArg) && !pathSegmentForbiddenPattern.test(valueArg)
+  && valueArg !== '.' && valueArg !== '..';
+
+const isRelativeSegments = (valueArg: string): boolean =>
+  valueArg.length <= runtimeLocalStorageClaimContract.maximumPathLength
+  && valueArg.split('/').every(isPathSegment);
+
+/** `/`, or `/` followed by canonical segments without a trailing slash. */
+const exportOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && valueArg.length <= runtimeLocalStorageClaimContract.maximumPathLength
+    && valueArg.startsWith('/') && (valueArg === '/' || isRelativeSegments(valueArg.slice(1))));
+  return valueArg;
+};
+
+/** `.`, or canonical relative segments. */
+const subPathOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && (valueArg === '.' || isRelativeSegments(valueArg)));
+  return valueArg;
+};
+
+const shareOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && valueArg.length <= runtimeLocalStorageClaimContract.maximumShareLength
+    && isPathSegment(valueArg) && !shareForbiddenPattern.test(valueArg));
+  return valueArg;
+};
+
+const literalOf = <TLiteral extends string>(valueArg: unknown, allowedArg: readonly TLiteral[]): TLiteral => {
+  requireNetwork((allowedArg as readonly unknown[]).includes(valueArg));
+  return valueArg as TLiteral;
+};
+
 const sourceOf = (valueArg: unknown): TRuntimeLocalStorageSource => {
+  requireNetwork(valueArg !== null && typeof valueArg === 'object');
+  const { kind } = valueArg as Record<string, unknown>;
+  if (kind === 'nfs') {
+    const value = networkRecord(valueArg, ['kind', 'server', 'export', 'subPath', 'version']);
+    return {
+      kind: 'nfs',
+      server: serverOf(value.server),
+      export: exportOf(value.export),
+      subPath: subPathOf(value.subPath),
+      version: literalOf(value.version, runtimeLocalStorageClaimContract.nfsVersions),
+    };
+  }
+  if (kind === 'smb') {
+    const value = networkRecord(valueArg, ['kind', 'server', 'share', 'subPath', 'version', 'credential']);
+    return {
+      kind: 'smb',
+      server: serverOf(value.server),
+      share: shareOf(value.share),
+      subPath: subPathOf(value.subPath),
+      version: literalOf(value.version, runtimeLocalStorageClaimContract.smbVersions),
+      credential: networkReference(value.credential),
+    };
+  }
   const value = networkRecord(valueArg, ['kind']);
   requireNetwork(value.kind === 'directory');
   return { kind: 'directory' };
@@ -142,6 +299,8 @@ export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLoc
     || (value.initialization === 'import' && value.initialOwnership === null));
   requireNetwork(value.accessMode === 'ReadWriteOnce' && value.reclaimPolicy === 'retain');
   requireNetwork(value.lifecycle === 'bound' || (value.lifecycle === 'purge' && previous !== null));
+  const source = sourceOf(value.source);
+  requireNetwork(source.kind !== 'smb' || value.initialization === 'empty');
   return {
     id, generation, previous,
     controller: networkController(value.controller),
@@ -151,7 +310,7 @@ export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLoc
     runtimeNamespace: networkId(value.runtimeNamespace),
     serviceId: networkId(value.serviceId),
     volumeId: networkId(value.volumeId),
-    source: sourceOf(value.source),
+    source,
     initialization: value.initialization as IRuntimeLocalStorageClaim['initialization'],
     initialOwnership: value.initialOwnership === null ? null : ownershipOf(value.initialOwnership),
     mount: mountOf(value.mount),

package/ts/data/service.ts

@@ -17,6 +17,7 @@ import type {
   IServiceSecretConfiguration,
   IServiceSecretDeploymentPlan,
 } from './secret.js';
+import type { TServiceVolumeInitialization } from './servicevolumeinitialization.js';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -32,8 +33,17 @@ export interface IServiceVolume {
   backup?: boolean;
   /** Driver-specific options forwarded to Docker's VolumeDriver.Create request. */
   options?: Record<string, string>;
+  /**
+   * Server-managed: how the volume's node-local storage claim starts on a Pallet cluster. Only
+   * `setServiceVolumeInitialization` writes it; a volume without one is refused as
+   * `volume-initialization-unknown` instead of being created empty.
+   */
+  initialization?: TServiceVolumeInitialization;
 }
 
+/** Caller-writable volume declaration. Its initialization has its own fenced request. */
+export type TServiceWritableVolume = Omit<IServiceVolume, 'initialization'>;
+
 const organizationIdRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
 
 /** Validates the canonical organization authority used by service operations. */
@@ -255,12 +265,18 @@ export type TServiceWritableData = Omit<
   | 'secretConfiguration'
   | 'secretDeployment'
   | 'mail'
+  | 'volumes'
 > & {
   /**
    * Mail configuration stays caller-writable, except for the CoreMail binding
    * metadata Cloudly derives from reconciliation.
    */
   mail?: TServiceMailWritableConfig;
+  /**
+   * Volumes stay caller-writable, except for their initialization, which Cloudly refuses here.
+   * A stored initialization stays with the volume of the same mount path and goes with it.
+   */
+  volumes?: TServiceWritableVolume[];
 };
 
 /** Caller-writable update data. Null explicitly removes an existing argument vector. */

package/ts/data/serviceruntime.ts

@@ -78,6 +78,7 @@ export const serviceRuntimeContract = Object.freeze({
 
 const serviceRuntimeWaitingReasons = [
   'node-network-pending', 'conflict', 'failure-backoff', 'storage-import-pending', 'bindings-pending',
+  'legacy-adoption-pending',
 ] as const;
 const serviceRuntimeRefusals = [
   'cluster-runtime-missing', 'organization-missing', 'image-plan-missing', 'platform-unsupported',
@@ -86,7 +87,7 @@ const serviceRuntimeRefusals = [
   'node-authority-unsupported', 'network-policy-missing', 'network-policy-mismatch',
   'network-workload-pool-missing', 'network-workload-pool-exhausted',
   'volume-driver-unsupported', 'volume-options-unsupported', 'volume-shared-unsupported',
-  'volume-placement-unsupported',
+  'volume-placement-unsupported', 'volume-initialization-unknown', 'volume-ownership-unknown',
 ] as const;
 
 /**
@@ -94,7 +95,9 @@ const serviceRuntimeRefusals = [
  * `node-network-pending` waits for a node's network readiness, `conflict` for a sweep over inputs
  * that changed while it ran, `failure-backoff` for a failed replica's backoff to elapse,
  * `storage-import-pending` for an `import` local storage claim whose bytes have not arrived on its
- * node, and `bindings-pending` for the secret manifest to cover every enabled binding of the service.
+ * node, `bindings-pending` for the secret manifest to cover every enabled binding of the service, and
+ * `legacy-adoption-pending` for a Corestore binding whose legacy resource waits for the offline
+ * adoption Corestore requires (the binding's `statusReason` of the same name).
  */
 export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
 
@@ -112,6 +115,9 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * a volume of a driver other than a node-local directory, `volume-options-unsupported` driver or
  * mount options, `volume-shared-unsupported` one volume mounted by more than one replica or service,
  * and `volume-placement-unsupported` a placement that does not pin each volume to one node.
+ * `volume-initialization-unknown` is a volume without an initialization and
+ * `volume-ownership-unknown` a `run-as` ownership under `runAs: null`
+ * (`deriveServiceVolumeClaimInitialization`); neither is defaulted.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 

package/ts/data/servicevolumeinitialization.ts

@@ -0,0 +1,159 @@
+import type { IRuntimeLocalStorageOwnership } from './runtimelocalstorageclaim.js';
+import { runtimeLocalStorageClaimContract } from './runtimelocalstorageclaim.js';
+import type { IServiceRuntimeProfile } from './serviceruntime.js';
+import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
+
+/**
+ * Where an `import` volume's bytes come from.
+ *
+ * `docker-volume` is a Docker volume on the host the claim's node runs on, named exactly as Docker
+ * lists it; a Corestore-driver volume is named the same way. The operator copies its tree into the
+ * node's import directory; the node never reads this reference, and the local storage claim does
+ * not carry it.
+ */
+export type TServiceVolumeImportSource = { kind: 'docker-volume'; volumeName: string };
+
+/**
+ * The owner and permission bits an `empty` volume's root directory gets.
+ *
+ * `explicit` states the numeric owner. `run-as` takes the owner from the runtime spec's
+ * `profile.runAs` (user and group) when the claim is first issued; the mode is always stated,
+ * because no mode is right for every image.
+ */
+export type TServiceVolumeOwnership =
+  | { kind: 'explicit'; uid: number; gid: number; mode: number }
+  | { kind: 'run-as'; mode: number };
+
+/**
+ * How a service volume's node-local claim starts: `empty` creates a fresh root with the stated
+ * ownership, `import` waits for the bytes of an existing volume.
+ */
+export type TServiceVolumeInitialization =
+  | { kind: 'empty'; ownership: TServiceVolumeOwnership }
+  | { kind: 'import'; source: TServiceVolumeImportSource };
+
+/**
+ * What a volume's initialization derives for a local storage claim, or why it derives nothing.
+ *
+ * `volume-initialization-unknown` is a volume with no initialization: Cloudly never assumes
+ * `empty`, because an empty volume in front of a service whose data sits in a legacy volume would
+ * start that service without its data. `volume-ownership-unknown` is a `run-as` ownership while
+ * the runtime spec runs the image's own user (`runAs: null`), whose numeric identity Cloudly does
+ * not know.
+ */
+export type TServiceVolumeClaimInitialization =
+  | { status: 'derived'; initialization: 'empty'; initialOwnership: IRuntimeLocalStorageOwnership }
+  | { status: 'derived'; initialization: 'import'; initialOwnership: null }
+  | { status: 'refused'; reason: 'volume-initialization-unknown' | 'volume-ownership-unknown' };
+
+/**
+ * Why `setServiceVolumeInitialization` wrote nothing. `volume-not-found` names no declared volume
+ * at that mount path, `conflict` a stored initialization other than `expected`,
+ * `volume-initialization-invalid` a value this contract refuses, and
+ * `volume-initialization-bound` a change while a bound local storage claim of the volume exists:
+ * a claim keeps the initialization and ownership it was issued with for its whole life.
+ */
+export type TServiceVolumeInitializationRefusal =
+  | 'volume-not-found'
+  | 'conflict'
+  | 'volume-initialization-invalid'
+  | 'volume-initialization-bound';
+
+/** The named refusal of `setServiceVolumeInitialization`, sent as `TypedResponseError.errorData`. */
+export interface IServiceVolumeInitializationErrorData {
+  code: TServiceVolumeInitializationRefusal;
+  retryable: false;
+}
+
+export const serviceVolumeInitializationContract = Object.freeze({
+  /** Every permission bit an ownership may state, the local storage claim's own bound. */
+  directoryModeBits: runtimeLocalStorageClaimContract.directoryModeBits,
+  maximumDockerVolumeNameLength: 255,
+} as const);
+
+/** Docker's own volume name grammar, `[a-zA-Z0-9][a-zA-Z0-9_.-]`, which needs two characters. */
+const dockerVolumeNamePattern = /^[A-Za-z0-9][A-Za-z0-9_.-]+$/;
+
+const isDirectoryMode = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= 0
+  && ((valueArg as number) & ~serviceVolumeInitializationContract.directoryModeBits) === 0;
+
+const validateOwnership = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.kind === 'explicit') {
+    if (!hasExactKeys(valueArg, ['kind', 'uid', 'gid', 'mode'])) return [`${pathArg} must use its exact schema`];
+    const errors: string[] = [];
+    if (!isRuntimeIdentityNumber(valueArg.uid) || !isRuntimeIdentityNumber(valueArg.gid)) {
+      errors.push(`${pathArg} uid and gid must be runtime identity numbers`);
+    }
+    if (!isDirectoryMode(valueArg.mode)) errors.push(`${pathArg} mode must hold directory permission bits only`);
+    return errors;
+  }
+  if (valueArg.kind === 'run-as') {
+    if (!hasExactKeys(valueArg, ['kind', 'mode'])) return [`${pathArg} must use its exact schema`];
+    return isDirectoryMode(valueArg.mode) ? [] : [`${pathArg} mode must hold directory permission bits only`];
+  }
+  return [`${pathArg} kind must be explicit or run-as`];
+};
+
+const validateImportSource = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg) || valueArg.kind !== 'docker-volume'
+    || !hasExactKeys(valueArg, ['kind', 'volumeName'])) {
+    return [`${pathArg} must be an exact docker-volume source`];
+  }
+  return typeof valueArg.volumeName === 'string'
+    && valueArg.volumeName.length <= serviceVolumeInitializationContract.maximumDockerVolumeNameLength
+    && dockerVolumeNamePattern.test(valueArg.volumeName)
+    ? []
+    : [`${pathArg} volumeName must be a Docker volume name`];
+};
+
+/** Validates one volume initialization and names every reason it is refused. */
+export const validateServiceVolumeInitialization = (
+  valueArg: unknown,
+  pathArg = 'service volume initialization',
+): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.kind === 'empty') {
+    if (!hasExactKeys(valueArg, ['kind', 'ownership'])) return [`${pathArg} must use its exact schema`];
+    return validateOwnership(valueArg.ownership, `${pathArg} ownership`);
+  }
+  if (valueArg.kind === 'import') {
+    if (!hasExactKeys(valueArg, ['kind', 'source'])) return [`${pathArg} must use its exact schema`];
+    return validateImportSource(valueArg.source, `${pathArg} source`);
+  }
+  return [`${pathArg} kind must be empty or import`];
+};
+
+/**
+ * The claim fields a volume's initialization derives under a runtime spec's `runAs`.
+ *
+ * Absent initialization refuses as `volume-initialization-unknown`; a `run-as` ownership under
+ * `runAs: null` refuses as `volume-ownership-unknown`. Nothing is defaulted. The answer is for the
+ * first generation of a claim only: later generations carry that claim's own initialization and
+ * ownership, whatever `runAs` says by then. A malformed initialization or `runAs` throws.
+ */
+export const deriveServiceVolumeClaimInitialization = (
+  initializationArg: TServiceVolumeInitialization | undefined,
+  runAsArg: IServiceRuntimeProfile['runAs'],
+): TServiceVolumeClaimInitialization => {
+  if (initializationArg === undefined) return { status: 'refused', reason: 'volume-initialization-unknown' };
+  const errors = validateServiceVolumeInitialization(initializationArg);
+  if (errors.length > 0) throw new Error(errors[0]);
+  if (runAsArg !== null && !(isPlainRecord(runAsArg) && hasExactKeys(runAsArg, ['user', 'group'])
+    && isRuntimeIdentityNumber(runAsArg.user) && isRuntimeIdentityNumber(runAsArg.group))) {
+    throw new Error('runAs must be null or an exact user and group');
+  }
+  if (initializationArg.kind === 'import') {
+    return { status: 'derived', initialization: 'import', initialOwnership: null };
+  }
+  const ownership = initializationArg.ownership;
+  if (ownership.kind === 'explicit') {
+    return { status: 'derived', initialization: 'empty',
+      initialOwnership: { uid: ownership.uid, gid: ownership.gid, mode: ownership.mode } };
+  }
+  if (runAsArg === null) return { status: 'refused', reason: 'volume-ownership-unknown' };
+  return { status: 'derived', initialization: 'empty',
+    initialOwnership: { uid: runAsArg.user, gid: runAsArg.group, mode: ownership.mode } };
+};

package/ts/platform/types.ts

@@ -16,6 +16,60 @@ export type TPlatformCapability =
 export type TPlatformAccessMode = 'rpc' | 'binding' | 'sidecar' | 'internal';
 export type TPlatformBindingStatus = 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
 export type TPlatformDesiredState = 'enabled' | 'disabled';
+
+export const platformBindingStatusReasons = [
+  'legacy-adoption-pending',
+  'legacy-adoption-conflict',
+  'legacy-adoption-mismatch',
+] as const;
+
+/**
+ * Why a binding holds the status it reports, where the status alone does not say.
+ *
+ * All three come from Corestore's refusal of a credential binding beside a legacy
+ * `/resources/provision` resource (`code` in its 409 body, read with
+ * `readCorestoreLegacyAdoptionRefusal`):
+ *
+ * - `legacy-adoption-pending` (status `provisioning`): the service owns a legacy resource of this
+ *   capability that no offline adoption authorizes yet. It clears when the operator runs
+ *   Corestore's adoption with the plan Cloudly produced.
+ * - `legacy-adoption-conflict` (status `failed`): the adoption authorizes another binding id, or
+ *   it was already consumed.
+ * - `legacy-adoption-mismatch` (status `failed`): the legacy resource is no longer the one the
+ *   adoption authorized, its database tenant is absent, or the binding's bucket or retention
+ *   intent differs from the legacy bucket's.
+ */
+export type TPlatformBindingStatusReason = typeof platformBindingStatusReasons[number];
+
+const platformBindingStatusOfReason: Readonly<Record<TPlatformBindingStatusReason, TPlatformBindingStatus>> =
+  Object.freeze({
+    'legacy-adoption-pending': 'provisioning',
+    'legacy-adoption-conflict': 'failed',
+    'legacy-adoption-mismatch': 'failed',
+  });
+
+/** The one status each reason is reported with. */
+export const getPlatformBindingStatusOfReason = (
+  reasonArg: TPlatformBindingStatusReason,
+): TPlatformBindingStatus => platformBindingStatusOfReason[reasonArg];
+
+/**
+ * Validates a reported status and its optional reason: a reason must be a member of the
+ * vocabulary and come with its one status. An absent reason is valid with every status.
+ */
+export const validatePlatformBindingStatusReason = (
+  statusArg: unknown,
+  reasonArg: unknown,
+  pathArg = 'platform binding statusReason',
+): string[] => {
+  if (reasonArg === undefined) return [];
+  if (!(platformBindingStatusReasons as readonly unknown[]).includes(reasonArg)) {
+    return [`${pathArg} must be a platform binding status reason`];
+  }
+  return platformBindingStatusOfReason[reasonArg as TPlatformBindingStatusReason] === statusArg
+    ? []
+    : [`${pathArg} ${reasonArg as string} requires status ${platformBindingStatusOfReason[reasonArg as TPlatformBindingStatusReason]}`];
+};
 export type TPlatformEndpointProtocol =
   | 'typedrequest'
   | 'http'
@@ -55,6 +109,23 @@ export interface IPlatformServiceEndpoint {
   port?: number;
 }
 
+/**
+ * The legacy Corestore resource an object-storage or database binding adopts.
+ *
+ * Server-managed: only `adoptCorestoreLegacyResources` writes it, in the same write that creates
+ * the binding, and Cloudly refuses it (and `objectstorageBucketName`) on `upsertPlatformBinding`.
+ * `nodeId` is the node whose Corestore holds the resource, so the binding is placed there and
+ * nowhere else; `resourceName` is the legacy database or bucket name; `inventorySha256` is the
+ * legacy inventory the adoption was checked against. An adopted bucket's
+ * `objectstorageBucketName` is the legacy bucket and its `objectstorageRetention.intent` the legacy
+ * intent exactly, or absent when the legacy bucket has none.
+ */
+export interface IPlatformBindingCorestoreLegacyAdoption {
+  nodeId: string;
+  resourceName: string;
+  inventorySha256: string;
+}
+
 export interface IPlatformBinding {
   id: string;
   serviceId: string;
@@ -69,6 +140,10 @@ export interface IPlatformBinding {
   objectstorageBucketName?: string;
   /** Capability-specific value-free immutable-retention intent and evidence. */
   objectstorageRetention?: IObjectStorageRetentionBinding;
+  /** Server-managed: the legacy Corestore resource this binding adopts. */
+  corestoreLegacyAdoption?: IPlatformBindingCorestoreLegacyAdoption;
+  /** Why the binding holds its status, as the responsible cluster reported it. */
+  statusReason?: TPlatformBindingStatusReason;
   createdAt?: number;
   updatedAt?: number;
 }

package/ts/requests/corestore.ts

@@ -1,5 +1,11 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
+import type {
+  ICorestoreLegacyResourceAdoptionPlanEntry,
+  ICorestoreLegacyResourceSelection,
+  TClusterCorestoreLegacyResourceInventory,
+} from '../data/corestorelegacyadoption.js';
+import type { IPlatformBinding } from '../platform/types.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
@@ -277,3 +283,76 @@ extends plugins.typedrequestInterfaces.implementsTR<
     inventory: ICorestoreNodeInventory;
   };
 }
+
+/**
+ * Cloudly asks the relay for one exact node's legacy Corestore resources.
+ *
+ * The relay reads Corestore's `corestoreLegacyAdoptionContract.inventoryPath` with the control
+ * token and answers `reachable: true` with its services, or `reachable: false` with the reason, never
+ * an empty list for a node it could not read.
+ */
+export interface IReq_Cloudly_Relay_GetClusterCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_GetClusterCorestoreLegacyResources
+> {
+  method: 'getClusterCorestoreLegacyResources';
+  request: {
+    nodeId: string;
+  };
+  response: {
+    inventory: TClusterCorestoreLegacyResourceInventory;
+  };
+}
+
+/**
+ * An administrator reads one node's legacy Corestore resources through its cluster's relay, with
+ * the digest an adoption is checked against (`null` for an unreachable node).
+ */
+export interface IReq_Any_Cloudly_GetCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetCorestoreLegacyResources
+> {
+  method: 'getCorestoreLegacyResources';
+  request: {
+    identity: IIdentity;
+    clusterId: string;
+    nodeId: string;
+  };
+  response: {
+    inventory: TClusterCorestoreLegacyResourceInventory;
+    inventorySha256: string | null;
+  };
+}
+
+/**
+ * The only path that creates a binding carrying a legacy bucket name.
+ *
+ * Cloudly reads the node's legacy inventory again, requires `expectedInventorySha256`, and for
+ * each selected resource creates the adopting binding in one transaction: enabled, placed on
+ * `nodeId`, with `corestoreLegacyAdoption`, and for a bucket the legacy bucket name and retention
+ * intent (`validatePlatformBindingCorestoreLegacyAdoption`). A resource whose adopting binding
+ * already exists is answered unchanged. The response lists the adopting bindings and the plan
+ * (`createCorestoreLegacyResourceAdoptionPlan`) the operator hands to Corestore's offline
+ * `legacy-resource-adoption` migration. Refusals travel as `ICorestoreLegacyAdoptionErrorData`.
+ */
+export interface IReq_Any_Cloudly_AdoptCorestoreLegacyResources
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_AdoptCorestoreLegacyResources
+> {
+  method: 'adoptCorestoreLegacyResources';
+  request: {
+    identity: IIdentity;
+    clusterId: string;
+    nodeId: string;
+    expectedInventorySha256: string;
+    /** Sorted by service then capability (`validateCorestoreLegacyResourceSelections`). */
+    resources: ICorestoreLegacyResourceSelection[];
+  };
+  response: {
+    bindings: IPlatformBinding[];
+    plan: ICorestoreLegacyResourceAdoptionPlanEntry[];
+  };
+}