@serve.zone/interfaces 32.21.0 → 32.23.0

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/networkworkloadingress.ts

@@ -0,0 +1,107 @@
+import type { IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
+import type { IRuntimeNetworkWorkloadLease } from './networkprojection.js';
+import { networkCanonical, networkCounter, networkEqual, networkList, networkRecord, networkReference,
+  networkReferenceOf, networkSameScope, networkSorted, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * Exact one-way flow authority from one workload to one port of another: the cluster ingress
+ * workload dials the target workload's lease address on exactly this protocol and port.
+ *
+ * Unlike the projection's workload grants it needs neither the same organization nor a shared
+ * private network, and it opens one port instead of every port; nothing flows the other way except
+ * the replies of a connection the source opened.
+ */
+export interface IRuntimeNetworkWorkloadIngressPacketGrant {
+  source: IRuntimeAuthorityReference;
+  destination: { lease: IRuntimeAuthorityReference; protocol: 'tcp' | 'udp'; port: number };
+}
+
+/** One target port the ingress workload may dial, and the Cloudly decision that authorized it. */
+export interface IRuntimeNetworkWorkloadIngress {
+  /** Exact lease of the ingress workload, an endpoint of this projection. */
+  source: IRuntimeAuthorityReference;
+  /** Exact lease of the target workload, another endpoint of this projection. */
+  destination: IRuntimeAuthorityReference;
+  protocol: 'tcp' | 'udp';
+  /** The target workload's own listening port inside its network namespace. */
+  port: number;
+  /** Covered by the projection signature; it never enters the packet grant's identity. */
+  authorization: IRuntimeAuthorityReference;
+}
+
+/**
+ * Workload ingress selections plus retained denials. Only a projection of a `cloudly` controller may
+ * carry it; omitting it keeps the projection's canonical bytes and grants no workload ingress flow.
+ */
+export interface IRuntimeNetworkWorkloadIngressProjection {
+  /**
+   * Strictly increasing by the canonical form of `[source.id, destination.id, protocol, port]`, so
+   * one entry per tuple. Each entry names at least one endpoint placed on this projection's node.
+   */
+  grants: IRuntimeNetworkWorkloadIngress[];
+  withdrawals: IRuntimeNetworkWorkloadIngressPacketGrant[];
+}
+
+export const runtimeNetworkWorkloadIngressContract = Object.freeze({
+  controllerKind: 'cloudly',
+  source: 'ingress-workload-lease',
+  destination: 'target-workload-lease-address-exact-port',
+  maximumGrants: 1024,
+  maximumWithdrawals: 4096,
+} as const);
+
+const grantKey = (value: {
+  source: IRuntimeAuthorityReference; destination: IRuntimeAuthorityReference; protocol: string; port: number;
+}): string => networkCanonical([value.source.id, value.destination.id, value.protocol, value.port]);
+const protocol = (value: unknown): 'tcp' | 'udp' => {
+  requireNetwork(value === 'tcp' || value === 'udp'); return value;
+};
+
+const packetGrant = (value: unknown): IRuntimeNetworkWorkloadIngressPacketGrant => {
+  const item = networkRecord(value, ['source', 'destination']);
+  const destination = networkRecord(item.destination, ['lease', 'protocol', 'port']);
+  return { source: networkReference(item.source), destination: { lease: networkReference(destination.lease),
+    protocol: protocol(destination.protocol), port: networkCounter(destination.port, 65535) } };
+};
+
+const grant = (value: unknown): IRuntimeNetworkWorkloadIngress => {
+  const item = networkRecord(value, ['source', 'destination', 'protocol', 'port', 'authorization']);
+  const result = { source: networkReference(item.source), destination: networkReference(item.destination),
+    protocol: protocol(item.protocol), port: networkCounter(item.port, 65535), authorization: networkReference(item.authorization) };
+  requireNetwork(result.source.id !== result.destination.id);
+  return result;
+};
+
+/** Internal parser: the enclosing projection has already captured caller input. */
+export const snapshotWorkloadIngressProjection = (value: unknown): IRuntimeNetworkWorkloadIngressProjection => {
+  const item = networkRecord(value, ['grants', 'withdrawals']);
+  return {
+    grants: networkSorted(networkList(item.grants, runtimeNetworkWorkloadIngressContract.maximumGrants, grant), grantKey),
+    withdrawals: networkSorted(networkList(item.withdrawals, runtimeNetworkWorkloadIngressContract.maximumWithdrawals,
+      packetGrant), networkCanonical),
+  };
+};
+
+/** Internal composition after capture. The public helper validates the whole projection. */
+export const workloadIngressPacketGrantsOf = (projection: {
+  controller: IRuntimeController;
+  nodeId: string;
+  runtimeNamespace: string;
+  workloadIngress?: IRuntimeNetworkWorkloadIngressProjection;
+  endpoints: Array<{ lease: IRuntimeNetworkWorkloadLease }>;
+}): IRuntimeNetworkWorkloadIngressPacketGrant[] => {
+  const selected = projection.workloadIngress;
+  if (!selected) return [];
+  requireNetwork(projection.controller.kind === runtimeNetworkWorkloadIngressContract.controllerKind);
+  const leaseOf = (reference: IRuntimeAuthorityReference): IRuntimeNetworkWorkloadLease => {
+    const endpoint = projection.endpoints.find(candidate => networkEqual(networkReferenceOf(candidate.lease), reference));
+    requireNetwork(endpoint); return endpoint.lease;
+  };
+  const result = selected.grants.map((entry): IRuntimeNetworkWorkloadIngressPacketGrant => {
+    const source = leaseOf(entry.source), destination = leaseOf(entry.destination);
+    requireNetwork(networkSameScope(source, projection) || networkSameScope(destination, projection));
+    return { source: networkReferenceOf(source),
+      destination: { lease: networkReferenceOf(destination), protocol: entry.protocol, port: entry.port } };
+  });
+  return result.sort((left, right) => networkCanonical(left) < networkCanonical(right) ? -1 : 1);
+};

package/ts/data/runtimelocalstorageclaim.ts

@@ -0,0 +1,275 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
+import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
+  networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
+} from '../private/networkcontract.js';
+import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
+
+/**
+ * Where a local storage claim's bytes live, named by kind and never by path.
+ *
+ * `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.
+ */
+export type TRuntimeLocalStorageSource = { kind: 'directory' };
+
+/** The owner and permission bits a node gives an `empty` volume's root directory when it creates it. */
+export interface IRuntimeLocalStorageOwnership {
+  uid: number;
+  gid: number;
+  /** Numeric directory permission bits, for example `0o750`; setuid is refused. */
+  mode: number;
+}
+
+/** Where the volume appears inside the workload's container. */
+export interface IRuntimeLocalStorageMount {
+  mountPath: string;
+  readOnly: boolean;
+}
+
+/**
+ * `bound` keeps the volume and lets the node mount it; `purge` orders the node to delete the
+ * volume's bytes. A purge always follows a bound generation of the same claim.
+ */
+export type TRuntimeLocalStorageLifecycle = 'bound' | 'purge';
+
+/**
+ * A controller's authority for one retained, node-local volume of one service.
+ *
+ * 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.
+ *
+ * `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.
+ */
+export interface IRuntimeLocalStorageClaim {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  controller: IRuntimeController;
+  organizationId: string;
+  clusterId: string;
+  nodeId: string;
+  runtimeNamespace: string;
+  serviceId: string;
+  /** The service's own name for this volume, stable across every generation of the claim. */
+  volumeId: string;
+  source: TRuntimeLocalStorageSource;
+  initialization: 'empty' | 'import';
+  /** Required for `empty`, `null` for `import`. */
+  initialOwnership: IRuntimeLocalStorageOwnership | null;
+  mount: IRuntimeLocalStorageMount;
+  accessMode: 'ReadWriteOnce';
+  reclaimPolicy: 'retain';
+  lifecycle: TRuntimeLocalStorageLifecycle;
+  digest: TSha256Digest;
+}
+
+/**
+ * What the node holds for the volume after admission.
+ *
+ * `ready` exists and may be mounted; `import-required` is an `import` volume whose bytes have not
+ * arrived; `purged` is a volume whose bytes the node deleted; `uncertain` is a volume the node
+ * cannot vouch for, which it neither mounts nor deletes until an operator decides.
+ */
+export type TRuntimeLocalStorageClaimState = 'ready' | 'import-required' | 'purged' | 'uncertain';
+
+/** Controller push over the node's current authenticated session. */
+export interface IApplyRuntimeLocalStorageClaimRequest {
+  session: IRuntimeSessionBinding;
+  claim: IRuntimeLocalStorageClaim;
+}
+
+/**
+ * Durable admission acknowledgement. `claim` is the reference of the claim that was sent, also on
+ * a `historical` answer, whose `state` describes the newer generation the node holds.
+ */
+export interface IApplyRuntimeLocalStorageClaimResponse {
+  status: 'accepted' | 'replay' | 'historical';
+  state: TRuntimeLocalStorageClaimState;
+  claim: IRuntimeAuthorityReference;
+}
+
+export const runtimeLocalStorageClaimContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-local-storage-claim',
+  error: 'Runtime local storage claim contract rejected.',
+  accessMode: 'ReadWriteOnce',
+  reclaimPolicy: 'retain',
+  /** Every permission bit a claim may state: setgid, sticky and the rwx triplets. */
+  directoryModeBits: 0o3777,
+} as const);
+
+const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+const { readMountPath } = createStorageContractReaders(fail);
+const claimStates = ['ready', 'import-required', 'purged', 'uncertain'] as const;
+const responseStatuses = ['accepted', 'replay', 'historical'] as const;
+
+const sourceOf = (valueArg: unknown): TRuntimeLocalStorageSource => {
+  const value = networkRecord(valueArg, ['kind']);
+  requireNetwork(value.kind === 'directory');
+  return { kind: 'directory' };
+};
+
+const ownershipOf = (valueArg: unknown): IRuntimeLocalStorageOwnership => {
+  const value = networkRecord(valueArg, ['uid', 'gid', 'mode']);
+  requireNetwork(isRuntimeIdentityNumber(value.uid) && isRuntimeIdentityNumber(value.gid)
+    && Number.isSafeInteger(value.mode) && (value.mode as number) >= 0
+    && ((value.mode as number) & ~runtimeLocalStorageClaimContract.directoryModeBits) === 0);
+  return { uid: value.uid as number, gid: value.gid as number, mode: value.mode as number };
+};
+
+const mountOf = (valueArg: unknown): IRuntimeLocalStorageMount => {
+  const value = networkRecord(valueArg, ['mountPath', 'readOnly']);
+  requireNetwork(typeof value.readOnly === 'boolean');
+  return { mountPath: readMountPath(value.mountPath, 'mountPath'), readOnly: value.readOnly };
+};
+
+/** Detached exact-schema snapshot. The digest is a separate check. */
+export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLocalStorageClaim => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['id', 'generation', 'previous', 'controller',
+    'organizationId', 'clusterId', 'nodeId', 'runtimeNamespace', 'serviceId', 'volumeId', 'source',
+    'initialization', 'initialOwnership', 'mount', 'accessMode', 'reclaimPolicy', 'lifecycle', 'digest']);
+  const { id, generation, previous } = networkRevision(value);
+  requireNetwork((value.initialization === 'empty' && value.initialOwnership !== null)
+    || (value.initialization === 'import' && value.initialOwnership === null));
+  requireNetwork(value.accessMode === 'ReadWriteOnce' && value.reclaimPolicy === 'retain');
+  requireNetwork(value.lifecycle === 'bound' || (value.lifecycle === 'purge' && previous !== null));
+  return {
+    id, generation, previous,
+    controller: networkController(value.controller),
+    organizationId: networkId(value.organizationId),
+    clusterId: networkId(value.clusterId),
+    nodeId: networkNodeId(value.nodeId),
+    runtimeNamespace: networkId(value.runtimeNamespace),
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    source: sourceOf(value.source),
+    initialization: value.initialization as IRuntimeLocalStorageClaim['initialization'],
+    initialOwnership: value.initialOwnership === null ? null : ownershipOf(value.initialOwnership),
+    mount: mountOf(value.mount),
+    accessMode: 'ReadWriteOnce',
+    reclaimPolicy: 'retain',
+    lifecycle: value.lifecycle as TRuntimeLocalStorageLifecycle,
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeRuntimeLocalStorageClaimDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const claim = snapshotRuntimeLocalStorageClaim(valueArg);
+  try {
+    return await networkHash(runtimeLocalStorageClaimContract.digestDomain, claim);
+  } catch {
+    return fail();
+  }
+};
+
+export const validateRuntimeLocalStorageClaim = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const claim = snapshotRuntimeLocalStorageClaim(valueArg);
+    return claim.digest === await computeRuntimeLocalStorageClaimDigest(claim)
+      ? [] : ['runtime local storage claim digest does not match'];
+  } catch {
+    return ['runtime local storage claim must use its exact canonical schema'];
+  }
+};
+
+/** The `{ id, generation, digest }` an assignment's `workload.storage` seals for this claim. */
+export const getRuntimeLocalStorageClaimReference = (valueArg: unknown): IRuntimeAuthorityReference =>
+  networkReferenceOf(snapshotRuntimeLocalStorageClaim(valueArg));
+
+/**
+ * Content binding only: the assignment seals this exact claim, and both name the same controller,
+ * organization, node, runtime namespace and service. A purge claim binds to no assignment, because
+ * no workload may mount a volume being deleted. The cluster ID must come from the authenticated
+ * session, because an assignment does not contain one.
+ */
+export const bindRuntimeLocalStorageClaimToAssignment = async (
+  claimArg: unknown, assignmentArg: unknown, expectedClusterIdArg: unknown,
+): Promise<{ claim: IRuntimeLocalStorageClaim; assignment: IRuntimeAssignment }> => {
+  const claim = snapshotRuntimeLocalStorageClaim(claimArg);
+  const assignment = safe(() => snapshotRuntimeAssignment(assignmentArg));
+  if ((await validateRuntimeLocalStorageClaim(claim)).length
+    || (await validateRuntimeAssignment(assignment)).length) fail();
+  safe(() => {
+    const expectedClusterId = networkId(expectedClusterIdArg);
+    const reference = assignment.workload.storage.find((itemArg) => itemArg.id === claim.id);
+    requireNetwork(reference !== undefined
+      && networkEqual(reference, getRuntimeLocalStorageClaimReference(claim))
+      && claim.lifecycle === 'bound'
+      && claim.clusterId === expectedClusterId
+      && networkEqual(assignment.controller, claim.controller)
+      && assignment.organizationId === claim.organizationId
+      && assignment.nodeId === claim.nodeId
+      && assignment.runtimeNamespace === claim.runtimeNamespace
+      && assignment.serviceId === claim.serviceId);
+  });
+  return { claim, assignment };
+};
+
+export const snapshotApplyRuntimeLocalStorageClaimRequest = (
+  valueArg: unknown,
+): IApplyRuntimeLocalStorageClaimRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim']);
+  return { session: snapshotRuntimeSessionBinding(value.session), claim: snapshotRuntimeLocalStorageClaim(value.claim) };
+});
+
+export const snapshotApplyRuntimeLocalStorageClaimResponse = (
+  valueArg: unknown,
+): IApplyRuntimeLocalStorageClaimResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['status', 'state', 'claim']);
+  requireNetwork((responseStatuses as readonly unknown[]).includes(value.status)
+    && (claimStates as readonly unknown[]).includes(value.state));
+  return {
+    status: value.status as IApplyRuntimeLocalStorageClaimResponse['status'],
+    state: value.state as TRuntimeLocalStorageClaimState,
+    claim: networkReference(value.claim),
+  };
+});
+
+/**
+ * Admission-side content binding, not authentication: `trustedSessionArg` must be the node's
+ * CURRENT authenticated session, never read from the request. The request's session must equal it,
+ * the claim must name its controller, cluster, node and runtime namespace, and its digest must hold.
+ */
+export const bindApplyRuntimeLocalStorageClaimRequest = async (
+  valueArg: unknown, trustedSessionArg: unknown,
+): Promise<IApplyRuntimeLocalStorageClaimRequest> => {
+  const request = snapshotApplyRuntimeLocalStorageClaimRequest(valueArg);
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  if ((await validateRuntimeLocalStorageClaim(request.claim)).length) fail();
+  safe(() => requireNetwork(networkEqual(request.session, trustedSession)
+    && networkEqual(request.claim.controller, trustedSession.controller)
+    && request.claim.clusterId === trustedSession.clusterId
+    && request.claim.nodeId === trustedSession.nodeId
+    && request.claim.runtimeNamespace === trustedSession.runtimeNamespace));
+  return request;
+};
+
+/**
+ * Matches an answer to the exact claim that was sent. An `accepted` or `replay` answer must state a
+ * state the claim can be in: a bound claim is `ready`, `import-required` (for an `import` claim
+ * only) or `uncertain`; a purge is `purged` or `uncertain`. A `historical` answer describes the
+ * newer generation the node holds, so its state is not judged against the sent claim.
+ */
+export const bindApplyRuntimeLocalStorageClaimResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IApplyRuntimeLocalStorageClaimResponse => safe(() => {
+  const response = snapshotApplyRuntimeLocalStorageClaimResponse(valueArg);
+  const { claim } = snapshotApplyRuntimeLocalStorageClaimRequest(requestArg);
+  requireNetwork(networkEqual(response.claim, getRuntimeLocalStorageClaimReference(claim)));
+  if (response.status !== 'historical') {
+    requireNetwork(claim.lifecycle === 'purge'
+      ? response.state === 'purged' || response.state === 'uncertain'
+      : response.state === 'ready' || response.state === 'uncertain'
+        || (response.state === 'import-required' && claim.initialization === 'import'));
+  }
+  return response;
+});

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

@@ -76,19 +76,28 @@ export const serviceRuntimeContract = Object.freeze({
   maximumAssignmentPageSize: 256,
 } as const);
 
-const serviceRuntimeWaitingReasons = ['node-network-pending', 'conflict', 'failure-backoff'] as const;
+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',
   'secrets-unsupported', 'volumes-unsupported', 'port-protocol-unsupported', 'ports-too-many',
   'readiness-target-undeclared', 'environment-too-large', 'no-eligible-node', 'replica-limit',
   '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-initialization-unknown', 'volume-ownership-unknown',
 ] as const;
 
 /**
  * Why the producer is not converging yet, though nothing needs an administrator:
  * `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.
+ * 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, `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];
 
@@ -101,6 +110,14 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * node whose session resolved fewer workload authorities than this spec needs, which the admit step
  * refuses rather than handing the node work it would silently park. An attached network needs an
  * explicit matching policy and a current workload address pool; neither is defaulted.
+ *
+ * The volume refusals name what a local storage claim cannot express: `volume-driver-unsupported`
+ * 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];