@serve.zone/interfaces 32.22.0 → 32.23.0

package/ts/data/corestorelegacyadoption.ts

@@ -0,0 +1,471 @@
+import type { IObjectStorageRetentionIntent } from '../platform/objectstorageretention.js';
+import {
+  objectStorageRetentionIntentsEqual,
+  validateObjectStorageRetentionIntent,
+} from '../platform/objectstorageretention.js';
+import { validatePlatformObjectStorageBucketName } from '../platform/objectstorage.js';
+import type { TPlatformBindingStatusReason } from '../platform/types.js';
+import { platformBindingStatusReasons } from '../platform/types.js';
+import {
+  canonicalizeStrictJson,
+  compareWireTokens,
+  createCanonicalJsonSha256Hex,
+} from '../private/canonicaljson.js';
+import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
+
+/**
+ * Moving a service's legacy Corestore resources into credential bindings.
+ *
+ * A Corestore root converted from a release before 32 still holds the databases and buckets
+ * `/resources/provision` created, one per service and capability, in its manifest. Corestore
+ * refuses a credential binding beside such a resource until an operator authorizes that exact
+ * binding to adopt it, offline, with a plan file. The flow across the three owners:
+ *
+ * 1. Corestore answers `GET /control/legacy-resources` with its `ICorestoreLegacyResourceInventory`;
+ *    the cluster relay reads it for Cloudly (`getClusterCorestoreLegacyResources`).
+ * 2. `adoptCorestoreLegacyResources` checks the admin's selection against that inventory at an
+ *    exact digest, creates each adopting binding with the legacy bucket and retention intent, and
+ *    answers the plan (`ICorestoreLegacyResourceAdoptionPlanEntry[]`).
+ * 3. The operator stops Corestore and runs its `legacy-resource-adoption` migration with that plan.
+ *    Until then Corestore refuses the binding, which reports `legacy-adoption-pending`.
+ */
+
+export type TCorestoreLegacyCapability = 'database' | 'objectstorage';
+
+/**
+ * Why Corestore's offline adoption would refuse an unadopted resource:
+ *
+ * - `not-adoptable`: its identity is not what a credential binding can adopt (an
+ *   allocation-managed database, another provider, a resource name that differs from its database
+ *   or bucket name, or a bucket name that is not a canonical S3 name);
+ * - `ordinary-credentials-rotated`: its credentials were rotated, so the delivered ones are no
+ *   longer the generation a binding adopts;
+ * - `owned-by-binding`: a credential binding or a named storage binding already owns the service
+ *   capability, the resource or the bucket.
+ */
+export type TCorestoreLegacyResourceBlocker =
+  | 'not-adoptable'
+  | 'ordinary-credentials-rotated'
+  | 'owned-by-binding';
+
+/**
+ * `unadopted` names what would stop the offline adoption, or `null` when nothing would;
+ * `authorized` names the binding the operator authorized, which is the only binding Corestore will
+ * let take the resource. A consumed adoption leaves no legacy resource behind, so it never appears.
+ */
+export type TCorestoreLegacyResourceAdoption =
+  | { state: 'unadopted'; blocker: TCorestoreLegacyResourceBlocker | null }
+  | { state: 'authorized'; bindingId: string };
+
+/**
+ * One legacy resource, by the identity Corestore's manifest states. A database is named by its
+ * database name, a bucket by its bucket name and its retention intent, `null` when it has none.
+ */
+export type TCorestoreLegacyResource =
+  | { capability: 'database'; databaseName: string; adoption: TCorestoreLegacyResourceAdoption }
+  | {
+      capability: 'objectstorage';
+      bucketName: string;
+      retention: IObjectStorageRetentionIntent | null;
+      adoption: TCorestoreLegacyResourceAdoption;
+    };
+
+/** One service's legacy resources, at most one per capability, `database` first. */
+export interface ICorestoreLegacyServiceResources {
+  serviceId: string;
+  resources: TCorestoreLegacyResource[];
+}
+
+/** What Corestore answers on `GET /control/legacy-resources`: every service, sorted by id. */
+export interface ICorestoreLegacyResourceInventory {
+  services: ICorestoreLegacyServiceResources[];
+}
+
+/**
+ * One node's legacy resources as the cluster relay read them. An unreachable node names why and
+ * lists nothing, because a silent empty list would read as a node with nothing to adopt.
+ */
+export type TClusterCorestoreLegacyResourceInventory =
+  | { nodeId: string; checkedAt: number; reachable: true; services: ICorestoreLegacyServiceResources[] }
+  | {
+      nodeId: string;
+      checkedAt: number;
+      reachable: false;
+      errorCode: 'CORESTORE_ENDPOINT_UNKNOWN' | 'CORESTORE_UNREACHABLE';
+    };
+
+/** One resource an administrator selects for adoption. */
+export interface ICorestoreLegacyResourceSelection {
+  serviceId: string;
+  capability: TCorestoreLegacyCapability;
+}
+
+/**
+ * One entry of Corestore's offline adoption plan, exactly the object its
+ * `legacy-resource-adoption` migration reads: the service, the capability and the binding that may
+ * adopt its legacy resource. The legacy identity is Corestore's own and is not restated here.
+ */
+export interface ICorestoreLegacyResourceAdoptionPlanEntry {
+  serviceId: string;
+  capability: TCorestoreLegacyCapability;
+  bindingId: string;
+}
+
+/**
+ * Why `adoptCorestoreLegacyResources` wrote nothing:
+ *
+ * - `legacy-inventory-unreachable`: the relay could not read the node's Corestore (retryable);
+ * - `legacy-inventory-changed`: the inventory no longer has `expectedInventorySha256`;
+ * - `legacy-resource-absent`: a selected service has no legacy resource of that capability;
+ * - `legacy-resource-blocked`: a selected resource is unadopted with a blocker;
+ * - `legacy-resource-authorized-elsewhere`: a selected resource is authorized for a binding Cloudly
+ *   does not hold as that resource's adoption;
+ * - `service-absent`: Cloudly has no such service;
+ * - `binding-exists`: the service already has a binding of that capability that adopts nothing,
+ *   or adopts another resource.
+ */
+export type TCorestoreLegacyAdoptionRefusal =
+  | 'legacy-inventory-unreachable'
+  | 'legacy-inventory-changed'
+  | 'legacy-resource-absent'
+  | 'legacy-resource-blocked'
+  | 'legacy-resource-authorized-elsewhere'
+  | 'service-absent'
+  | 'binding-exists';
+
+/** The named refusal of `adoptCorestoreLegacyResources`, sent as `TypedResponseError.errorData`. */
+export interface ICorestoreLegacyAdoptionErrorData {
+  code: TCorestoreLegacyAdoptionRefusal;
+  /** True for `legacy-inventory-unreachable` only; every other refusal needs a new read first. */
+  retryable: boolean;
+}
+
+export const corestoreLegacyAdoptionContract = Object.freeze({
+  /** Corestore's control path for its legacy inventory, bearer-authenticated like every other. */
+  inventoryPath: '/control/legacy-resources',
+  /** Corestore's own plan bound, which also bounds a selection and an inventory. */
+  maximumPlanEntries: 4096,
+  maximumServices: 4096,
+  maximumNameLength: 255,
+  digestDomain: 'serve.zone/corestore-legacy-resources',
+} as const);
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const printableNamePattern = /^[\x21-\x7e]+$/;
+const bareSha256Pattern = /^[a-f0-9]{64}$/;
+const blockers: readonly TCorestoreLegacyResourceBlocker[] = [
+  'not-adoptable', 'ordinary-credentials-rotated', 'owned-by-binding',
+];
+
+const isIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && identifierPattern.test(valueArg)
+);
+
+const isLegacyName = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= corestoreLegacyAdoptionContract.maximumNameLength
+  && printableNamePattern.test(valueArg)
+);
+
+const isCapability = (valueArg: unknown): valueArg is TCorestoreLegacyCapability => (
+  valueArg === 'database' || valueArg === 'objectstorage'
+);
+
+const validateAdoption = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.state === 'unadopted') {
+    if (!hasExactKeys(valueArg, ['state', 'blocker'])) return [`${pathArg} must use its exact schema`];
+    return valueArg.blocker === null || (blockers as readonly unknown[]).includes(valueArg.blocker)
+      ? []
+      : [`${pathArg} blocker must be null or a named blocker`];
+  }
+  if (valueArg.state === 'authorized') {
+    if (!hasExactKeys(valueArg, ['state', 'bindingId'])) return [`${pathArg} must use its exact schema`];
+    return isIdentifier(valueArg.bindingId) ? [] : [`${pathArg} bindingId must be a canonical identifier`];
+  }
+  return [`${pathArg} state must be unadopted or authorized`];
+};
+
+/** An adoptable resource is one the offline adoption could authorize or already did. */
+const isAdoptable = (adoptionArg: unknown): boolean => (
+  isPlainRecord(adoptionArg) && (adoptionArg.state === 'authorized' || adoptionArg.blocker === null)
+);
+
+const validateResource = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  if (valueArg.capability === 'database') {
+    if (!hasExactKeys(valueArg, ['capability', 'databaseName', 'adoption'])) {
+      return [`${pathArg} must use its exact schema`];
+    }
+    const errors = validateAdoption(valueArg.adoption, `${pathArg} adoption`);
+    if (!isLegacyName(valueArg.databaseName)) errors.push(`${pathArg} databaseName must be a bounded printable name`);
+    return errors;
+  }
+  if (valueArg.capability === 'objectstorage') {
+    if (!hasExactKeys(valueArg, ['capability', 'bucketName', 'retention', 'adoption'])) {
+      return [`${pathArg} must use its exact schema`];
+    }
+    const errors = validateAdoption(valueArg.adoption, `${pathArg} adoption`);
+    if (!isLegacyName(valueArg.bucketName)) {
+      errors.push(`${pathArg} bucketName must be a bounded printable name`);
+    } else if (errors.length === 0 && isAdoptable(valueArg.adoption)) {
+      // A binding request carries only a canonical bucket, so an adoptable bucket has to be one.
+      errors.push(...validatePlatformObjectStorageBucketName(valueArg.bucketName, `${pathArg} bucketName`));
+    }
+    if (valueArg.retention !== null) {
+      errors.push(...validateObjectStorageRetentionIntent(valueArg.retention, `${pathArg} retention`));
+    }
+    return errors;
+  }
+  return [`${pathArg} capability must be database or objectstorage`];
+};
+
+const validateServices = (valueArg: unknown, pathArg: string): string[] => {
+  if (!Array.isArray(valueArg) || valueArg.length > corestoreLegacyAdoptionContract.maximumServices) {
+    return [`${pathArg} must be a bounded array`];
+  }
+  const errors: string[] = [];
+  let previousServiceId: string | undefined;
+  for (const [index, service] of valueArg.entries()) {
+    const servicePath = `${pathArg}[${index}]`;
+    if (!isPlainRecord(service) || !hasExactKeys(service, ['serviceId', 'resources'])) {
+      errors.push(`${servicePath} must use its exact schema`);
+      continue;
+    }
+    if (!isIdentifier(service.serviceId)) {
+      errors.push(`${servicePath} serviceId must be a canonical identifier`);
+    } else {
+      if (previousServiceId !== undefined && compareWireTokens(previousServiceId, service.serviceId) >= 0) {
+        errors.push(`${pathArg} must be sorted by serviceId without repeats`);
+      }
+      previousServiceId = service.serviceId;
+    }
+    if (!Array.isArray(service.resources) || service.resources.length < 1 || service.resources.length > 2) {
+      errors.push(`${servicePath} resources must list one or two resources`);
+      continue;
+    }
+    for (const [resourceIndex, resource] of service.resources.entries()) {
+      errors.push(...validateResource(resource, `${servicePath} resources[${resourceIndex}]`));
+    }
+    if (service.resources.length === 2
+      && !(isPlainRecord(service.resources[0]) && service.resources[0].capability === 'database'
+        && isPlainRecord(service.resources[1]) && service.resources[1].capability === 'objectstorage')) {
+      errors.push(`${servicePath} resources must hold one database before one objectstorage resource`);
+    }
+  }
+  return errors;
+};
+
+/** Validates Corestore's answer on its legacy inventory path and names every reason it is refused. */
+export const validateCorestoreLegacyResourceInventory = (
+  valueArg: unknown,
+  pathArg = 'corestore legacy resource inventory',
+): string[] => {
+  if (!isPlainRecord(valueArg) || !hasExactKeys(valueArg, ['services'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return validateServices(valueArg.services, `${pathArg} services`);
+};
+
+/** Validates one node's legacy inventory as the relay reports it. Shape only. */
+export const validateClusterCorestoreLegacyResourceInventory = (
+  valueArg: unknown,
+  pathArg = 'cluster corestore legacy resource inventory',
+): string[] => {
+  if (!isPlainRecord(valueArg)) return [`${pathArg} must use its exact schema`];
+  const reachable = valueArg.reachable;
+  if (reachable === true
+    ? !hasExactKeys(valueArg, ['nodeId', 'checkedAt', 'reachable', 'services'])
+    : reachable !== false || !hasExactKeys(valueArg, ['nodeId', 'checkedAt', 'reachable', 'errorCode'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (!isClusterNodeId(valueArg.nodeId)) errors.push(`${pathArg} nodeId must be a node id`);
+  if (!Number.isSafeInteger(valueArg.checkedAt) || (valueArg.checkedAt as number) < 0) {
+    errors.push(`${pathArg} checkedAt must be a non-negative safe integer`);
+  }
+  if (reachable === true) {
+    errors.push(...validateServices(valueArg.services, `${pathArg} services`));
+  } else if (valueArg.errorCode !== 'CORESTORE_ENDPOINT_UNKNOWN' && valueArg.errorCode !== 'CORESTORE_UNREACHABLE') {
+    errors.push(`${pathArg} errorCode must name why the node could not be read`);
+  }
+  return errors;
+};
+
+const failDigest = (reasonArg: string): never => {
+  throw new Error(reasonArg);
+};
+
+/**
+ * The digest an adoption is checked against: the node and its services, not the read time, so two
+ * reads of an unchanged Corestore agree. Throws for an invalid or unreachable inventory.
+ */
+export const computeClusterCorestoreLegacyResourceInventorySha256 = async (
+  inventoryArg: TClusterCorestoreLegacyResourceInventory,
+): Promise<string> => {
+  const errors = validateClusterCorestoreLegacyResourceInventory(inventoryArg);
+  if (errors.length > 0) throw new Error(errors[0]);
+  if (inventoryArg.reachable !== true) throw new Error('an unreachable legacy inventory has no digest');
+  return createCanonicalJsonSha256Hex(canonicalizeStrictJson({
+    domain: corestoreLegacyAdoptionContract.digestDomain,
+    nodeId: inventoryArg.nodeId,
+    services: inventoryArg.services,
+  }, failDigest, 'corestore legacy resource inventory'), failDigest);
+};
+
+const selectionKey = (entryArg: { serviceId: string; capability: string }): string =>
+  `${entryArg.serviceId}\u0000${entryArg.capability}`;
+
+/** Validates an administrator's selection: 1..4096 exact entries, sorted by service then capability. */
+export const validateCorestoreLegacyResourceSelections = (
+  valueArg: unknown,
+  pathArg = 'corestore legacy resource selection',
+): string[] => {
+  if (!Array.isArray(valueArg) || valueArg.length < 1
+    || valueArg.length > corestoreLegacyAdoptionContract.maximumPlanEntries) {
+    return [`${pathArg} must be a non-empty bounded array`];
+  }
+  const errors: string[] = [];
+  let previous: string | undefined;
+  for (const [index, entry] of valueArg.entries()) {
+    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability'])
+      || !isIdentifier(entry.serviceId) || !isCapability(entry.capability)) {
+      errors.push(`${pathArg}[${index}] must be an exact { serviceId, capability }`);
+      continue;
+    }
+    const key = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
+    if (previous !== undefined && compareWireTokens(previous, key) >= 0) {
+      errors.push(`${pathArg} must be sorted by serviceId then capability without repeats`);
+    }
+    previous = key;
+  }
+  return errors;
+};
+
+/**
+ * Validates an adoption plan by the rules Corestore's migration applies: a non-empty array of at
+ * most 4096 exact `{ serviceId, capability, bindingId }` entries, canonical identifiers, and no
+ * service capability or binding id twice. Order is free.
+ */
+export const validateCorestoreLegacyResourceAdoptionPlan = (
+  valueArg: unknown,
+  pathArg = 'adoption plan',
+): string[] => {
+  if (!Array.isArray(valueArg) || valueArg.length === 0
+    || valueArg.length > corestoreLegacyAdoptionContract.maximumPlanEntries) {
+    return [`${pathArg} must be a non-empty bounded array`];
+  }
+  const errors: string[] = [];
+  const serviceCapabilities = new Set<string>();
+  const bindingIds = new Set<string>();
+  for (const [index, entry] of valueArg.entries()) {
+    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability', 'bindingId'])
+      || !isIdentifier(entry.serviceId) || !isIdentifier(entry.bindingId) || !isCapability(entry.capability)) {
+      errors.push(`${pathArg} entry ${index} must be an exact { serviceId, capability, bindingId }`);
+      continue;
+    }
+    const serviceCapability = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
+    if (serviceCapabilities.has(serviceCapability) || bindingIds.has(entry.bindingId as string)) {
+      errors.push(`${pathArg} entry ${index} repeats a service capability or binding id`);
+    }
+    serviceCapabilities.add(serviceCapability);
+    bindingIds.add(entry.bindingId as string);
+  }
+  return errors;
+};
+
+/** The binding fields an adoption judges; a full `IPlatformBinding` satisfies it. */
+export interface ICorestoreLegacyAdoptionBindingView {
+  id: string;
+  serviceId: string;
+  capability: string;
+  objectstorageBucketName?: string;
+  objectstorageRetention?: { intent: IObjectStorageRetentionIntent };
+  corestoreLegacyAdoption?: { nodeId: string; resourceName: string; inventorySha256: string };
+}
+
+/**
+ * Content check of one adopting binding against the inventory it was adopted at, and the one rule
+ * that lets a binding carry a legacy bucket name: the binding names this node, this inventory
+ * digest and the legacy resource's name; the resource is unadopted without a blocker or authorized
+ * for exactly this binding; an adopted bucket's `objectstorageBucketName` is the legacy bucket and
+ * its retention intent the legacy intent exactly, absent when the legacy bucket has none; a
+ * database binding carries neither. Whether the digest is current is the caller's to check.
+ */
+export const validatePlatformBindingCorestoreLegacyAdoption = (
+  bindingArg: ICorestoreLegacyAdoptionBindingView,
+  inventoryArg: TClusterCorestoreLegacyResourceInventory,
+  inventorySha256Arg: string,
+  pathArg = 'platform binding corestoreLegacyAdoption',
+): string[] => {
+  if (validateClusterCorestoreLegacyResourceInventory(inventoryArg).length > 0 || inventoryArg.reachable !== true
+    || typeof inventorySha256Arg !== 'string' || !bareSha256Pattern.test(inventorySha256Arg)) {
+    return [`${pathArg} needs a valid reachable inventory and its digest`];
+  }
+  const adoption = bindingArg.corestoreLegacyAdoption;
+  if (!isPlainRecord(adoption) || !hasExactKeys(adoption, ['nodeId', 'resourceName', 'inventorySha256'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  if (adoption.nodeId !== inventoryArg.nodeId || adoption.inventorySha256 !== inventorySha256Arg) {
+    return [`${pathArg} must name the inventory's node and digest`];
+  }
+  if (!isCapability(bindingArg.capability)) return [`${pathArg} needs a database or objectstorage binding`];
+  const resource = inventoryArg.services.find((serviceArg) => serviceArg.serviceId === bindingArg.serviceId)
+    ?.resources.find((resourceArg) => resourceArg.capability === bindingArg.capability);
+  if (!resource) return [`${pathArg} names no legacy resource of the service and capability`];
+  const errors: string[] = [];
+  const legacyName = resource.capability === 'database' ? resource.databaseName : resource.bucketName;
+  if (adoption.resourceName !== legacyName) errors.push(`${pathArg} resourceName must be the legacy resource's name`);
+  if (resource.adoption.state === 'unadopted' ? resource.adoption.blocker !== null
+    : resource.adoption.bindingId !== bindingArg.id) {
+    errors.push(`${pathArg} names a resource that is blocked or authorized for another binding`);
+  }
+  if (resource.capability === 'objectstorage') {
+    if (bindingArg.objectstorageBucketName !== resource.bucketName) {
+      errors.push(`${pathArg} objectstorageBucketName must be the legacy bucket`);
+    }
+    if (resource.retention === null
+      ? bindingArg.objectstorageRetention !== undefined
+      : !objectStorageRetentionIntentsEqual(bindingArg.objectstorageRetention?.intent, resource.retention)) {
+      errors.push(`${pathArg} retention intent must be the legacy bucket's exactly`);
+    }
+  } else if (bindingArg.objectstorageBucketName !== undefined || bindingArg.objectstorageRetention !== undefined) {
+    errors.push(`${pathArg} database binding must carry no bucket or retention`);
+  }
+  return errors;
+};
+
+/**
+ * The plan for every adopting binding, sorted by service then capability, in the exact entry shape
+ * Corestore's migration reads. Throws unless every binding adopts a legacy resource and the result
+ * is a valid plan.
+ */
+export const createCorestoreLegacyResourceAdoptionPlan = (
+  bindingsArg: readonly ICorestoreLegacyAdoptionBindingView[],
+): ICorestoreLegacyResourceAdoptionPlanEntry[] => {
+  const plan = bindingsArg.map((bindingArg) => {
+    if (bindingArg.corestoreLegacyAdoption === undefined || !isCapability(bindingArg.capability)) {
+      throw new Error(`binding ${bindingArg.id} adopts no legacy Corestore resource`);
+    }
+    return { serviceId: bindingArg.serviceId, capability: bindingArg.capability, bindingId: bindingArg.id };
+  }).sort((leftArg, rightArg) => compareWireTokens(selectionKey(leftArg), selectionKey(rightArg)));
+  const errors = validateCorestoreLegacyResourceAdoptionPlan(plan);
+  if (errors.length > 0) throw new Error(errors[0]);
+  return plan;
+};
+
+/**
+ * The binding status reason a Corestore control answer names: a 409 whose body is
+ * `{ ok: false, error, code }` with `code` one of the legacy adoption reasons. Every other answer,
+ * including a 409 with another code, names none and keeps its ordinary failure handling.
+ */
+export const readCorestoreLegacyAdoptionRefusal = (
+  statusCodeArg: number,
+  bodyArg: unknown,
+): TPlatformBindingStatusReason | null => (
+  statusCodeArg === 409 && isPlainRecord(bodyArg) && bodyArg.ok === false
+    && (platformBindingStatusReasons as readonly unknown[]).includes(bodyArg.code)
+    ? bodyArg.code as TPlatformBindingStatusReason
+    : null
+);

package/ts/data/index.ts

@@ -7,6 +7,7 @@ export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
+export * from './corestorelegacyadoption.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';
@@ -67,6 +68,7 @@ export * from './service.js';
 export * from './servicecredential.js';
 export * from './serviceports.js';
 export * from './serviceruntime.js';
+export * from './servicevolumeinitialization.js';
 export * from './status.js';
 export * from './taskexecution.js';
 export * from './traffic.js';

package/ts/data/networkprotection.ts

@@ -42,6 +42,18 @@ export interface IReportRuntimeNetworkProtectionRequest {
    * Absent from a node that has not stated one; never defaulted, never guessed.
    */
   uplinkAddress?: string;
+  /**
+   * Every IPv4 address the node's host carries on interfaces the node does not manage itself, as
+   * the node observed them: sorted as strings, unique, never empty when present, at most
+   * `runtimeNetworkProtectionContract.maximumHostAddresses`, and each one an address
+   * `runtimeNodeUplinkAddress` admits. Workload bridges and the managed VPN interface are the
+   * node's own and are left out.
+   *
+   * Cloudly names a platform endpoint in the node's `hostPlatformEndpointIds` when its address is
+   * one of these, which is how a host without a relay registration (a Corestore beside the node on
+   * one machine) states that an endpoint is local. Absent states nothing; never defaulted.
+   */
+  hostAddresses?: string[];
 }
 export interface IReportRuntimeNetworkProtectionResponse {
   status: 'accepted' | 'replay';
@@ -57,6 +69,7 @@ export const runtimeNetworkProtectionContract = Object.freeze({
   unavailable: 'null-native-barrier-removes-allocation-eligibility',
   historical: 'retain-for-outbox-replay-never-current-allocation-eligibility',
   quarantine: 'no-release-authority',
+  maximumHostAddresses: 32,
 } as const);
 
 const scopeOf = (value: IRuntimeNetworkNodeScope): IRuntimeNetworkNodeScope =>
@@ -123,7 +136,7 @@ export const admitRuntimeNetworkProtectionReceipt = async (
 };
 
 export const snapshotReportRuntimeNetworkProtectionRequest = (value: unknown): IReportRuntimeNetworkProtectionRequest => networkSafe(() => {
-  const item = networkRecord(captureNetwork(value), ['session', 'receipt'], ['uplinkAddress']);
+  const item = networkRecord(captureNetwork(value), ['session', 'receipt'], ['uplinkAddress', 'hostAddresses']);
   const request: IReportRuntimeNetworkProtectionRequest = {
     session: snapshotRuntimeSessionBinding(item.session),
     receipt: snapshotRuntimeNetworkProtectionReceipt(item.receipt),
@@ -131,6 +144,12 @@ export const snapshotReportRuntimeNetworkProtectionRequest = (value: unknown): I
   if (Object.hasOwn(item, 'uplinkAddress')) {
     request.uplinkAddress = runtimeNodeUplinkAddress(item.uplinkAddress);
   }
+  if (Object.hasOwn(item, 'hostAddresses')) {
+    const hostAddresses = networkSorted(networkList(item.hostAddresses,
+      runtimeNetworkProtectionContract.maximumHostAddresses, runtimeNodeUplinkAddress), (address) => address);
+    requireNetwork(hostAddresses.length > 0);
+    request.hostAddresses = hostAddresses;
+  }
   return request;
 });
 

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];