@serve.zone/interfaces 32.21.0 → 32.22.0

package/readme.md

@@ -572,6 +572,41 @@ overlapping current grants reject, and up to 4,096 retained withdrawals carry
 forward until the caller supplies its exact joined application of the preceding
 projection.
 
+The optional `IRuntimeNetworkProjection.workloadIngress` member exists only on
+`cloudly` projections; any other controller kind carrying it rejects. It is how
+the cluster ingress workload reaches the workloads it routes to without a
+published host port: each `grants` entry names the exact lease reference of the
+ingress workload (`source`), the exact lease reference of the target workload
+(`destination`), a protocol, the target's own listening port and an
+`authorization` reference. Unlike the full-mesh workload grants, it needs neither
+the same organization nor a shared private network, it opens exactly one port,
+and it is one-way: nothing flows back except the replies of a connection the
+ingress opened. Both leases must be endpoints of the projection, they must
+differ, and at least one of them must be placed on the projection's own node.
+Entries are unique and strictly ordered by `[source.id, destination.id, protocol,
+port]`; at most 1,024 are allowed (`runtimeNetworkWorkloadIngressContract`). The
+authorization is signed content, not grant identity. A projection that omits the
+member retains its exact canonical bytes, digest and signature.
+`getRuntimeNetworkProjectionWorkloadIngressPacketGrants` validates the complete
+projection and returns detached `IRuntimeNetworkWorkloadIngressPacketGrant`s
+(`{ source, destination: { lease, protocol, port } }`). Their withdrawals follow
+the host rules: an omitted grant needs its exact withdrawal, unknown or current
+denials reject, and up to 4,096 retained withdrawals carry forward until the
+exact joined application of the preceding projection is supplied. Cloudly routes
+a cluster ingress route to the target lease address and port once the grant
+exists.
+
+The optional `IRuntimeNetworkProjection.hostPlatformEndpointIds` lists the ids of
+the protected authority's platform endpoints whose address the projection's
+node's own host carries, such as a relay listener or a Corestore beside the node
+on one machine. A node delivers workload flows to those endpoints locally instead
+of forwarding them. The list is sorted, unique, never empty when present, and
+every id must be a current platform endpoint; omitting it keeps the canonical
+bytes and states that no endpoint is local. It grants nothing: a workload still
+reaches only the endpoints it selects. The platform endpoint contract itself
+(`{ id, address, protocol, port }`) names no node, which is why this statement is
+per projection.
+
 `admitRuntimeNetworkProjection` checks exact predecessor/replay identity and
 rejects changed same-generation content, regressed membership/readiness evidence,
 changed immutable address/DNS keys, and omitted packet grants without explicit
@@ -811,6 +846,15 @@ named once; an empty `hubs` composes the authority of a runtime network whose cl
 yet. One hub costs one of the authority's 64 platform endpoints, so 64 clusters fit one
 authority.
 
+A single host that carries both a cluster's hub and platform endpoints, for example the relay
+listener and a Corestore, holds more than one address. The hub address sits inside `vpn.hubPrefix`,
+as every hub's does. The plan's own platform endpoints may not: they sit on another address of the
+same host, inside `prefixes`, outside every pool and outside both VPN prefixes. Several endpoints may
+share that one address on distinct ports, because the authority requires only each
+`address:port:protocol` to be unique. For example, with `hubPrefix` `192.0.2.0/28`, the hub binds
+`192.0.2.1` and the plan lists the relay listener and Corestore on `192.0.2.17` with two ports. The
+node's projection then names those endpoints in `hostPlatformEndpointIds`.
+
 `admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
 the following revision; any other revision is a contract violation. Leases and the managed VPN
 outlive a plan revision, so it answers:
@@ -1373,12 +1417,18 @@ phase, settlement, release or authority booleans or evidence.
 `data.IServiceRuntimeStatus { id, specRevision, state, reason, changedAt }` is the producer's verdict
 on one spec revision, and each reason belongs to exactly one state. `converged` and `converging`
 carry `reason: null`. `waiting` carries a `TServiceRuntimeWaitingReason`: `node-network-pending`,
-`conflict` or `failure-backoff`. `refused` carries a `TServiceRuntimeRefusal`:
+`conflict`, `failure-backoff`, `storage-import-pending` (an `import` local storage claim whose bytes
+have not arrived on its node) or `bindings-pending` (the secret manifest does not cover every enabled
+binding of the service yet). `refused` carries a `TServiceRuntimeRefusal`:
 `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` or `network-workload-pool-exhausted`. `ports-too-many` is a service declaring more target ports than the
+`network-workload-pool-missing`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
+`volume-options-unsupported`, `volume-shared-unsupported` or `volume-placement-unsupported`. The four
+volume refusals name what a local storage claim cannot express: a volume driver other than a
+node-local directory, driver or mount options, one volume mounted by more than one replica or
+service, and a placement that does not pin each volume to one node. `ports-too-many` is a service declaring more target ports than the
 `runtimeConfigContract.maximumTargetPorts` (64) a config carries, where `port-protocol-unsupported`
 is about one port's protocol; `node-authority-unsupported` is a node whose session resolved fewer
 workload authorities than the spec needs, refused at the admit step rather than handed to a node
@@ -1881,6 +1931,47 @@ storage provider's binding identity/generation, selected policy, matching observ
 join: callers still authenticate Cloudly and the provider, check current readiness and retain the
 native fence.
 
+### Runtime local storage claims
+
+`data.IRuntimeLocalStorageClaim` is a controller's authority for one retained, node-local volume of
+one service. Cloudly and Onebox issue it alike (`controller.kind` is `cloudly` or `onebox`). It names
+the claim revision (`id`, `generation`, `previous`), the organization, cluster, node, runtime
+namespace, service and the service's own `volumeId`, and it states:
+
+- `source`: `{ kind: 'directory' }`, a node-local directory the node derives from the claim's
+  identity under a root only the node knows. Network filesystems join this union later as further
+  kinds, with their credentials delivered as secrets and never inside a claim;
+- `initialization`: `empty` creates an empty root with `initialOwnership { uid, gid, mode }`, which
+  an `empty` claim must state, so a workload without `runAs` never meets a root-owned directory by
+  accident; `import` waits for the volume's bytes to be imported and states `initialOwnership: null`,
+  because an imported tree keeps its own ownership. `mode` holds directory permission bits only
+  (`runtimeLocalStorageClaimContract.directoryModeBits`, `0o3777`; setuid is refused);
+- `mount { mountPath, readOnly }`, judged by the storage request's own mount path rule: canonical,
+  absolute, not `/`, and never overlapping `/run/secrets`;
+- `accessMode: 'ReadWriteOnce'`, `reclaimPolicy: 'retain'`, and `lifecycle`: `bound` keeps the
+  volume, `purge` orders its bytes deleted and always follows a bound generation of the same claim.
+
+The claim carries no host path, device, mount option or credential.
+`snapshotRuntimeLocalStorageClaim` makes a detached exact-schema snapshot,
+`computeRuntimeLocalStorageClaimDigest` hashes it under `serve.zone/runtime-local-storage-claim`,
+`validateRuntimeLocalStorageClaim` verifies the stated digest, and
+`getRuntimeLocalStorageClaimReference` is the `{ id, generation, digest }` an assignment seals in
+`workload.storage`. `bindRuntimeLocalStorageClaimToAssignment(claim, assignment, expectedClusterId)`
+checks that reference and the exact controller, organization, node, runtime namespace, service and
+cluster; a `purge` claim binds to no assignment, because no workload may mount a volume being deleted.
+
+`requests.runtimesession.IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim`
+(`applyRuntimeLocalStorageClaim`) pushes one claim over the node's authenticated session:
+`{ session, claim }` → `{ status, state, claim }`. `status` is `accepted`, `replay` or `historical`;
+`state` is `ready`, `import-required`, `purged` or `uncertain` (a volume the node can vouch for
+neither way, which it neither mounts nor deletes until an operator decides); `claim` is the sent
+claim's reference. `bindApplyRuntimeLocalStorageClaimRequest(request, trustedSession)` requires the
+request's session to equal the node's current one and the claim to name its controller, cluster,
+node and runtime namespace. `bindApplyRuntimeLocalStorageClaimResponse(response, request)` binds the
+answer to the sent claim and, for `accepted` and `replay`, to a state the claim can be in: a bound
+claim is `ready`, `import-required` (an `import` claim only) or `uncertain`, a purge is `purged` or
+`uncertain`. A `historical` answer describes the newer generation the node holds.
+
 `platform.storagemigration` defines the provider-neutral cutover contract for a
 named object-storage binding. Corestore atomically owns and fences the source
 binding after validating a distinct, unfenced active-object snapshot. Onebox
@@ -2440,6 +2531,9 @@ credential is excluded.
 | `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities?, protocol }` → `{ accepted: true, revision \| null, protocol }` |
 | `getClusterIngressRouteTable` | ingress → relay | `{ knownRevision \| null }` → `{ table \| null }` |
 | `getClusterTrafficStatistics` | Cloudly → relay → ingress | `{ fromDayUtc, toDayUtc, cursor?, limit }` → `{ statistics, nextCursor? }` |
+| `pushClusterIngressRouteTableChanged` | relay → ingress | `{ revision }` → `{}` |
+| `designateClusterIngress` | admin → Cloudly | `{ identity, designation }` → `{ designation, spec, replayed }` |
+| `getClusterIngressDesignation` | admin → Cloudly | `{ identity, clusterId }` → `{ designation \| null }` |
 
 `null` for a table means Cloudly has computed none yet — a fact, not an empty table, and an
 ingress must not serve it as one. An ingress announces itself with a **method**, not a connection
@@ -2465,6 +2559,45 @@ the body in the one server order `protocol.readProtocolOffer` states — the off
 before this shape check and before the bearer — so a relay refuses a peer it cannot serve without
 asking Cloudly, and an accepted registration carries the accepting side's own offer back.
 
+A refused registration is named. A protocol mismatch stays the `IProtocolRefusal` every hop already
+carries; every other refusal travels as `IClusterIngressRegistrationRefusal { code:
+'cluster-ingress-registration-refused', reason, retryAfterMs }` in `TypedResponseError.errorData`,
+forwarded by the relay untouched. `clusterIngressRegistrationRefusalReasons` lists the reasons in
+the order Cloudly judges them: `not-ready` (Cloudly cannot judge registrations yet), `registration-invalid`
+(the body fails `validateClusterIngressRegistration`), `relay-not-connected` (the forwarding relay is
+not the connection Cloudly elected for its cluster), `ingress-not-designated`, `node-mismatch` (the
+node is not one the designation lets the ingress run on), `assignment-not-running` (no ready
+assignment of the ingress service runs on that node under its current session, or it does not carry
+the designation's current credential), `bearer-refused` and `conflict` (the designation, assignment
+or session changed while the registration was judged). `retryAfterMs` is how long the ingress waits
+before it registers again, 1 s to 300 s (`clusterIngressRegistrationContract`).
+`validateClusterIngressRegistrationRefusal` names every violation and
+`readClusterIngressRegistrationRefusal(errorData)` answers the refusal or `null`, reading plain data
+only, as `protocol.readProtocolRefusal` does. No refusal quotes the bearer.
+
+`pushClusterIngressRouteTableChanged` is the relay's hint that it holds a newer table. It carries the
+revision alone (`IClusterIngressRouteTableChange`, `validateClusterIngressRouteTableChange`) and
+nothing secret; the ingress answers it by pulling `getClusterIngressRouteTable` with the revision it
+already applied and ignores a hint that is not newer, so a lost or repeated hint costs nothing.
+
+`clusterIngressEnvironmentNames` spells the ingress workload's environment once for both sides:
+`SERVEZONE_CLUSTER_INGRESS_BEARER` (the registration bearer, delivered as a secret),
+`SERVEZONE_CLUSTER_RELAY_ORIGIN` (the exact `IClusterRelay.origin`) and `SERVEZONE_CLUSTER_NODE_ID`
+(the node the assignment runs on). Cloudly writes them; the ingress reads them.
+
+A cluster born on Pallet has no cutover scope, census or target set, so its ingress is designated by
+`IClusterIngressDesignation { id, generation, previous, clusterId, runtime, ingressServiceId,
+preparedSpecRevision, credential, actorId, acceptedAt, digest }` instead of the fleet-cutover
+designation. `runtime` is the cluster's `pallet` phase reference and `credential`
+(`IClusterIngressCredentialReference`) the public identity of the managed bearer, never its value.
+`snapshotClusterIngressDesignation`, `computeClusterIngressDesignationDigest` (domain
+`serve.zone/cluster-ingress-designation`) and `validateClusterIngressDesignation` judge it, and
+`snapshotClusterIngressDesignationRequest` the administrator's compare-and-swap intent
+(`IClusterIngressDesignationRequest { mutationId, clusterId, ingressServiceId, currentRuntime,
+expectedSpecRevision, expectedDesignation }`). **A cluster holds exactly one kind of designation**:
+Cloudly refuses to designate a cluster that holds a fleet-cutover ingress designation, and the
+reverse. Which nodes the ingress runs on is the ingress service's runtime spec placement.
+
 `IClusterTrafficStatistics` is one UTC day of one hostname's traffic on one node —
 `requests`, `bytesIn`, `bytesOut`, `connections` and the backend failures the proxy can observe
 (`connect`, `handshake`, `request`). Day buckets rather than rates: a rate answers "how busy is it

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.21.0',
+  version: '32.22.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/clusteringress.ts

@@ -1,7 +1,7 @@
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { isUtcCalendarDay } from '../private/utccalendarday.js';
 import { validateProtocolOfferOn } from '../protocol.js';
-import { hasExactKeys } from '../private/dataproperties.js';
+import { hasExactKeys, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
@@ -424,3 +424,138 @@ export const validateClusterIngressRegistration = (
   }
   return errors;
 };
+
+/**
+ * The environment variable names of the cluster ingress workload.
+ *
+ * Cloudly writes them into the ingress workload's assignment environment and the ingress reads
+ * them, so both sides spell each name once, here. `bearer` is the credential the ingress presents
+ * to `registerClusterIngress`; it is a secret and is delivered as one. `relayOrigin` is the exact
+ * `IClusterRelay.origin` of the cluster's relay, and `nodeId` is the node the assignment runs on,
+ * which the registration's `nodeId` repeats.
+ */
+export const clusterIngressEnvironmentNames = Object.freeze({
+  bearer: 'SERVEZONE_CLUSTER_INGRESS_BEARER',
+  relayOrigin: 'SERVEZONE_CLUSTER_RELAY_ORIGIN',
+  nodeId: 'SERVEZONE_CLUSTER_NODE_ID',
+} as const);
+
+/**
+ * Every reason Cloudly refuses a cluster ingress registration, in the order it judges them.
+ *
+ * A protocol mismatch is not among them: it is refused first, as the `IProtocolRefusal` every
+ * TypedRequest hop already carries, and a second name for it would be a second answer to one fact.
+ */
+export const clusterIngressRegistrationRefusalReasons = Object.freeze([
+  /** Cloudly cannot judge registrations yet: it is starting, stopping or missing its environment. */
+  'not-ready',
+  /** The body fails `validateClusterIngressRegistration`. */
+  'registration-invalid',
+  /** The relay that forwarded the registration is not the connection Cloudly elected for its cluster. */
+  'relay-not-connected',
+  /** The cluster holds no current ingress designation. */
+  'ingress-not-designated',
+  /** The named node is not one the designation lets the ingress run on. */
+  'node-mismatch',
+  /**
+   * No ready assignment of the designated ingress service runs on the named node under that node's
+   * current session, or the one that runs does not carry the designation's current credential.
+   */
+  'assignment-not-running',
+  /** The bearer is not the designation's current credential. */
+  'bearer-refused',
+  /** The designation, the assignment or the session changed while the registration was judged. */
+  'conflict',
+] as const);
+
+export type TClusterIngressRegistrationRefusalReason = typeof clusterIngressRegistrationRefusalReasons[number];
+
+export const clusterIngressRegistrationContract = Object.freeze({
+  refusalCode: 'cluster-ingress-registration-refused',
+  minimumRetryAfterMs: 1_000,
+  maximumRetryAfterMs: 300_000,
+} as const);
+
+/**
+ * The named refusal of `registerClusterIngress`, carried as `TypedResponseError.errorData` from
+ * Cloudly and forwarded by the relay untouched. `retryAfterMs` is how long the ingress waits before
+ * it registers again; it never quotes the bearer or anything derived from it.
+ */
+export interface IClusterIngressRegistrationRefusal {
+  code: 'cluster-ingress-registration-refused';
+  reason: TClusterIngressRegistrationRefusalReason;
+  retryAfterMs: number;
+}
+
+const isRetryAfterMs = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= clusterIngressRegistrationContract.minimumRetryAfterMs
+  && (valueArg as number) <= clusterIngressRegistrationContract.maximumRetryAfterMs
+);
+
+/** Validates one registration refusal and names every reason it is refused. */
+export const validateClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress registration refusal',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['code', 'reason', 'retryAfterMs'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (valueArg.code !== clusterIngressRegistrationContract.refusalCode) {
+    errors.push(`${pathArg} code must be ${clusterIngressRegistrationContract.refusalCode}`);
+  }
+  if (!(clusterIngressRegistrationRefusalReasons as readonly unknown[]).includes(valueArg.reason)) {
+    errors.push(`${pathArg} reason must be a cluster ingress registration refusal reason`);
+  }
+  if (!isRetryAfterMs(valueArg.retryAfterMs)) {
+    errors.push(`${pathArg} retryAfterMs must be an integer from `
+      + `${clusterIngressRegistrationContract.minimumRetryAfterMs} to `
+      + `${clusterIngressRegistrationContract.maximumRetryAfterMs}`);
+  }
+  return errors;
+};
+
+/**
+ * The refusal inside an error payload, or `null` when the value is not one.
+ *
+ * It reads a value that survived serialization, the way `protocol.readProtocolRefusal` does, so an
+ * ingress tells a named registration refusal apart from a protocol refusal and every other error.
+ */
+export const readClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+): IClusterIngressRegistrationRefusal | null => {
+  const refusal = readExactDataRecord(valueArg, ['code', 'reason', 'retryAfterMs']);
+  if (refusal === null || validateClusterIngressRegistrationRefusal(refusal).length > 0) {
+    return null;
+  }
+  return Object.freeze({
+    code: clusterIngressRegistrationContract.refusalCode,
+    reason: refusal.reason as TClusterIngressRegistrationRefusalReason,
+    retryAfterMs: refusal.retryAfterMs as number,
+  });
+};
+
+/**
+ * The relay's hint that it holds a newer route table.
+ *
+ * It carries the revision alone and no route, certificate or key, so it is safe to log; the
+ * ingress answers it by pulling `getClusterIngressRouteTable` with the revision it already applied,
+ * and ignores a hint whose revision is not greater than that one.
+ */
+export interface IClusterIngressRouteTableChange {
+  revision: number;
+}
+
+/** Validates one route-table change hint. */
+export const validateClusterIngressRouteTableChange = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress route table change',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['revision'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return isCounter(valueArg.revision)
+    ? []
+    : [`${pathArg} revision must be a non-negative safe integer`];
+};

package/ts/data/clusteringressdesignation.ts

@@ -0,0 +1,141 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IClusterRuntimeReference } from './clusterruntime.js';
+import { snapshotClusterRuntimeReference } from './clusterruntime.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { ISecretVersionReference } from './secret.js';
+import { captureNetwork, networkCounter, networkDigest, networkHash, networkId, networkRecord, networkReference,
+  networkRevision, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * The ingress designation of a cluster born on Pallet.
+ *
+ * A cluster that never ran Swarm has no cutover scope, census or target set, so its ingress is
+ * designated by this record instead of `IFleetCutoverIngressDesignation`. A cluster holds exactly
+ * one kind of designation at a time: Cloudly refuses to designate a cluster that holds the other
+ * kind. Which nodes the ingress runs on is the ingress service's runtime spec placement; the
+ * designation names the service and the credential, and nothing else.
+ */
+
+/** Public identity of the active ingress credential generation; it contains no credential value. */
+export interface IClusterIngressCredentialReference {
+  credentialId: string;
+  generation: number;
+  secretVersion: ISecretVersionReference;
+}
+
+/**
+ * Cloudly's accepted designation of one service as a Pallet cluster's ingress. It grants no
+ * assignment, session or registration: the ingress still registers with the credential it names.
+ */
+export interface IClusterIngressDesignation {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  clusterId: string;
+  runtime: IClusterRuntimeReference & { phase: 'pallet' };
+  ingressServiceId: string;
+  /** The ingress service's runtime spec revision the designation was accepted against. */
+  preparedSpecRevision: number;
+  credential: IClusterIngressCredentialReference;
+  actorId: string;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * Administrator intent to designate one service as the cluster's ingress. The caller supplies only
+ * compare-and-swap inputs; Cloudly owns credential generation and acceptance.
+ */
+export interface IClusterIngressDesignationRequest {
+  mutationId: string;
+  clusterId: string;
+  ingressServiceId: string;
+  currentRuntime: IClusterRuntimeReference & { phase: 'pallet' };
+  expectedSpecRevision: number;
+  /** Null for creation; the exact current designation for rotation or a change of service. */
+  expectedDesignation: IRuntimeAuthorityReference | null;
+}
+
+export const clusterIngressDesignationContract = Object.freeze({
+  digestDomain: 'serve.zone/cluster-ingress-designation',
+  error: 'Cluster ingress designation contract rejected.',
+} as const);
+
+const fail = (): never => { throw new Error(clusterIngressDesignationContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+const palletRuntime = (valueArg: unknown, clusterIdArg: string): IClusterRuntimeReference & { phase: 'pallet' } => {
+  const runtime = snapshotClusterRuntimeReference(valueArg);
+  requireNetwork(runtime.id === clusterIdArg && runtime.phase === 'pallet');
+  return { id: runtime.id, phase: 'pallet', generation: runtime.generation };
+};
+
+const credentialOf = (valueArg: unknown): IClusterIngressCredentialReference => {
+  const value = networkRecord(valueArg, ['credentialId', 'generation', 'secretVersion']);
+  const secretVersion = networkRecord(value.secretVersion, ['secretId', 'secretVersionId']);
+  return {
+    credentialId: networkId(value.credentialId),
+    generation: networkCounter(value.generation),
+    secretVersion: {
+      secretId: networkId(secretVersion.secretId),
+      secretVersionId: networkId(secretVersion.secretVersionId),
+    },
+  };
+};
+
+/** Detached exact-schema snapshot of a designation request. */
+export const snapshotClusterIngressDesignationRequest = (
+  valueArg: unknown,
+): IClusterIngressDesignationRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['mutationId', 'clusterId', 'ingressServiceId',
+    'currentRuntime', 'expectedSpecRevision', 'expectedDesignation']);
+  const clusterId = networkId(value.clusterId);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId,
+    ingressServiceId: networkId(value.ingressServiceId),
+    currentRuntime: palletRuntime(value.currentRuntime, clusterId),
+    expectedSpecRevision: networkCounter(value.expectedSpecRevision),
+    expectedDesignation: value.expectedDesignation === null ? null : networkReference(value.expectedDesignation),
+  };
+});
+
+/** Detached exact-schema snapshot. The digest is a separate check. */
+export const snapshotClusterIngressDesignation = (valueArg: unknown): IClusterIngressDesignation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['id', 'generation', 'previous', 'clusterId', 'runtime',
+    'ingressServiceId', 'preparedSpecRevision', 'credential', 'actorId', 'acceptedAt', 'digest']);
+  const { id, generation, previous } = networkRevision(value);
+  const clusterId = networkId(value.clusterId);
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    runtime: palletRuntime(value.runtime, clusterId),
+    ingressServiceId: networkId(value.ingressServiceId),
+    preparedSpecRevision: networkCounter(value.preparedSpecRevision),
+    credential: credentialOf(value.credential),
+    actorId: networkId(value.actorId),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterIngressDesignationDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const designation = snapshotClusterIngressDesignation(valueArg);
+  try {
+    return await networkHash(clusterIngressDesignationContract.digestDomain, designation);
+  } catch {
+    return fail();
+  }
+};
+
+export const validateClusterIngressDesignation = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const designation = snapshotClusterIngressDesignation(valueArg);
+    return designation.digest === await computeClusterIngressDesignationDigest(designation)
+      ? [] : ['cluster ingress designation digest does not match'];
+  } catch {
+    return ['cluster ingress designation must use its exact canonical schema'];
+  }
+};

package/ts/data/index.ts

@@ -3,6 +3,7 @@ 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';
@@ -40,6 +41,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 +52,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';

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) {