@serve.zone/interfaces 32.21.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

@@ -3,9 +3,11 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+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';
@@ -40,6 +42,9 @@ export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrant, IRuntimeNetworkRouterProjection } from './networkrouter.js';
 export type { IRuntimeNetworkHostIngress, IRuntimeNetworkHostPacketGrant, IRuntimeNetworkHostProjection } from './networkhost.js';
 export { runtimeNetworkHostContract } from './networkhost.js';
+export type { IRuntimeNetworkWorkloadIngress, IRuntimeNetworkWorkloadIngressPacketGrant,
+  IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
+export { runtimeNetworkWorkloadIngressContract } from './networkworkloadingress.js';
 export * from './networkprotection.js';
 export * from './networksigning.js';
 export * from './privatenetwork.js';
@@ -48,6 +53,7 @@ export * from './releaseversion.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';
 export * from './runtimestorageclaim.js';
+export * from './runtimelocalstorageclaim.js';
 export * from './runtimesession.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';
@@ -62,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/networkprojection.ts

@@ -9,6 +9,8 @@ import { routerPacketGrantsOf, snapshotRouterProjection,
   type IRuntimeNetworkRouterPacketGrant, type IRuntimeNetworkRouterProjection } from './networkrouter.js';
 import { hostPacketGrantsOf, snapshotHostProjection,
   type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
+import { snapshotWorkloadIngressProjection, workloadIngressPacketGrantsOf,
+  type IRuntimeNetworkWorkloadIngressPacketGrant, type IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
 import { buildPrivateNetworkFqdn, composeServicePrivateNetworkDnsPolicy,
   snapshotPrivateNetwork, snapshotServicePrivateNetworks } from './privatenetwork.js';
 import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkDigest,
@@ -167,6 +169,21 @@ export interface IRuntimeNetworkProjection extends IRuntimeNetworkNodeScope {
    * host-origin flow; any other controller kind carrying it is refused.
    */
   host?: IRuntimeNetworkHostProjection;
+  /**
+   * One-way workload ingress selections of a `cloudly` projection: the cluster ingress workload dials
+   * exact target workload ports across organizations (`IRuntimeNetworkWorkloadIngressPacketGrant`).
+   * Omitted, it keeps the canonical bytes and grants no such flow; any other controller kind
+   * carrying it is refused.
+   */
+  workloadIngress?: IRuntimeNetworkWorkloadIngressProjection;
+  /**
+   * Ids of the protected authority's platform endpoints whose address this projection's node's own
+   * host carries, such as a relay listener or a Corestore beside the node on one machine. The node
+   * delivers workload flows to them locally instead of forwarding them. Sorted, unique and never
+   * empty when present; omitted, it keeps the canonical bytes and states that no endpoint is local.
+   * It grants nothing: a workload still reaches only the endpoints it selects.
+   */
+  hostPlatformEndpointIds?: string[];
   digest: TSha256Digest;
 }
 
@@ -322,9 +339,16 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
   requireNetwork(new TextEncoder().encode(networkCanonical(captured)).length <= runtimeNetworkProjectionContract.maximumCanonicalBytes);
   const hasRouter = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'router');
   const hasHost = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'host');
+  const hasWorkloadIngress = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'workloadIngress');
+  const hasHostPlatformEndpoints = captured !== null && typeof captured === 'object'
+    && Object.hasOwn(captured, 'hostPlatformEndpointIds');
   const item = networkRecord(captured, ['id', 'generation', 'previous', 'controller', 'nodeId', 'runtimeNamespace',
     'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest',
-    ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : [])]);
+    ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : []), ...(hasWorkloadIngress ? ['workloadIngress'] : []),
+    ...(hasHostPlatformEndpoints ? ['hostPlatformEndpointIds'] : [])]);
+  const hostPlatformEndpointIds = hasHostPlatformEndpoints
+    ? networkSorted(networkList(item.hostPlatformEndpointIds, 64, networkId), value => value) : [];
+  requireNetwork(!hasHostPlatformEndpoints || hostPlatformEndpointIds.length > 0);
   return { ...networkRevision(item), ...networkScope(item),
     protectedAuthority: snapshotRuntimeNetworkProtectedAuthority(item.protectedAuthority),
     allocationAuthorities: networkSorted(networkList(item.allocationAuthorities, 16, snapshotRuntimeNetworkProtectedAuthority), refKey),
@@ -335,6 +359,8 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
     withdrawals: networkSorted(networkList(item.withdrawals, 4096, packetGrant), networkCanonical),
     ...(hasRouter ? { router: snapshotRouterProjection(item.router) } : {}),
     ...(hasHost ? { host: snapshotHostProjection(item.host) } : {}),
+    ...(hasWorkloadIngress ? { workloadIngress: snapshotWorkloadIngressProjection(item.workloadIngress) } : {}),
+    ...(hasHostPlatformEndpoints ? { hostPlatformEndpointIds } : {}),
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
 });
 
@@ -434,6 +460,7 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
       }
       requireNetwork(!projection.retiredLeases.some(retired => networkEqual(retired, networkReferenceOf(lease))));
     }
+    for (const id of projection.hostPlatformEndpointIds ?? []) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
     for (let index = 0; index < projection.endpoints.length; index++) for (let previous = 0; previous < index; previous++) {
       requireNetwork(!networkOverlaps(projection.endpoints[index].lease.ipv4.linkSubnet, projection.endpoints[previous].lease.ipv4.linkSubnet));
     }
@@ -444,6 +471,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
     requireNetwork((projection.router?.withdrawals ?? []).every(grant => !routerGrants.has(networkCanonical(grant))));
     const hostGrants = new Set(hostPacketGrantsOf(projection).map(networkCanonical));
     requireNetwork((projection.host?.withdrawals ?? []).every(grant => !hostGrants.has(networkCanonical(grant))));
+    const workloadIngressGrants = new Set(workloadIngressPacketGrantsOf(projection).map(networkCanonical));
+    requireNetwork((projection.workloadIngress?.withdrawals ?? []).every(grant => !workloadIngressGrants.has(networkCanonical(grant))));
     requireNetwork(projection.digest === await computeRuntimeNetworkProjectionDigest(projection));
     return projection;
   } catch { return failNetwork(); }
@@ -461,6 +490,12 @@ export const getRuntimeNetworkProjectionRouterPacketGrants = async (value: unkno
 export const getRuntimeNetworkProjectionHostPacketGrants = async (value: unknown): Promise<IRuntimeNetworkHostPacketGrant[]> =>
   hostPacketGrantsOf(await validateRuntimeNetworkProjection(value));
 
+/** One-way workload ingress authority comes only from explicit signed `cloudly` selections of exact target ports. */
+export const getRuntimeNetworkProjectionWorkloadIngressPacketGrants = async (
+  value: unknown,
+): Promise<IRuntimeNetworkWorkloadIngressPacketGrant[]> =>
+  workloadIngressPacketGrantsOf(await validateRuntimeNetworkProjection(value));
+
 /** Complete offline DNS material, including authorized names never previously queried. */
 /** Select exact local receivers before expansion; all targets still come from
  * the complete validated projection. Selection supplies no attachment authority. */
@@ -526,6 +561,7 @@ export const admitRuntimeNetworkProjection = async (
     if (previousInput === null) {
       requireNetwork(projection.generation === 1 && applied === null && projection.withdrawals.length === 0
         && (projection.router?.withdrawals.length ?? 0) === 0 && (projection.host?.withdrawals.length ?? 0) === 0
+        && (projection.workloadIngress?.withdrawals.length ?? 0) === 0
         && projection.retiredLeases.length === 0 && projection.retiredHandoffs.length === 0);
       return { status: 'accepted', projection };
     }
@@ -567,6 +603,15 @@ export const admitRuntimeNetworkProjection = async (
     for (const grant of previousHostGrants) requireNetwork(hostGrants.has(networkCanonical(grant)) || hostWithdrawals.has(networkCanonical(grant)));
     const knownHostWithdrawals = new Set([...previousHostGrants, ...(previous.host?.withdrawals ?? [])].map(networkCanonical));
     requireNetwork((projection.host?.withdrawals ?? []).every(grant => knownHostWithdrawals.has(networkCanonical(grant))));
+    const workloadIngressGrants = new Set(workloadIngressPacketGrantsOf(projection).map(networkCanonical));
+    const workloadIngressWithdrawals = new Set((projection.workloadIngress?.withdrawals ?? []).map(networkCanonical));
+    const previousWorkloadIngressGrants = workloadIngressPacketGrantsOf(previous);
+    for (const grant of previousWorkloadIngressGrants) requireNetwork(workloadIngressGrants.has(networkCanonical(grant))
+      || workloadIngressWithdrawals.has(networkCanonical(grant)));
+    const knownWorkloadIngressWithdrawals = new Set([...previousWorkloadIngressGrants,
+      ...(previous.workloadIngress?.withdrawals ?? [])].map(networkCanonical));
+    requireNetwork((projection.workloadIngress?.withdrawals ?? []).every(grant =>
+      knownWorkloadIngressWithdrawals.has(networkCanonical(grant))));
     const knownLeases = [...previous.endpoints.map(endpoint => networkReferenceOf(endpoint.lease)), ...previous.retiredLeases];
     const knownHandoffs = [...(previous.handoff ? [networkReferenceOf(previous.handoff)] : []), ...previous.retiredHandoffs];
     requireNetwork(projection.retiredLeases.every(retired => knownLeases.some(known => networkEqual(known, retired)))
@@ -578,6 +623,9 @@ export const admitRuntimeNetworkProjection = async (
       for (const grant of previous.withdrawals) requireNetwork(withdrawn.has(networkCanonical(grant)));
       for (const grant of previous.router?.withdrawals ?? []) requireNetwork(routerWithdrawals.has(networkCanonical(grant)));
       for (const grant of previous.host?.withdrawals ?? []) requireNetwork(hostWithdrawals.has(networkCanonical(grant)));
+      for (const grant of previous.workloadIngress?.withdrawals ?? []) {
+        requireNetwork(workloadIngressWithdrawals.has(networkCanonical(grant)));
+      }
       requireCarried(previous.retiredLeases, projection.retiredLeases); requireCarried(previous.retiredHandoffs, projection.retiredHandoffs);
     }
     for (const old of previous.endpoints) {