@serve.zone/interfaces 32.21.0 → 32.22.0

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

@@ -76,19 +76,25 @@ 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',
+] 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',
 ] 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, and `bindings-pending` for the secret manifest to cover every enabled binding of the service.
  */
 export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[number];
 
@@ -101,6 +107,11 @@ 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.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 

package/ts/private/storagecontract.ts

@@ -614,6 +614,7 @@ export const createStorageContractReaders = (failArg: TCanonicalJsonFailure) =>
     readCapacityQuantity,
     capacityQuantityBytes,
     readEnvironmentKey,
+    readMountPath,
     normalizeCapacityRequest,
     normalizeDelivery,
     normalizeObjectStorageRequest,

package/ts/requests/clusteringress.ts

@@ -1,4 +1,10 @@
 import * as clusterIngressInterfaces from '../data/clusteringress.js';
+import type {
+  IClusterIngressDesignation,
+  IClusterIngressDesignationRequest,
+} from '../data/clusteringressdesignation.js';
+import type { IServiceRuntimeSpec } from '../data/serviceruntime.js';
+import type { IIdentityCredential } from '../data/user.js';
 import type { IProtocolOffer } from '../protocol.js';
 import * as plugins from '../plugins.js';
 
@@ -70,6 +76,12 @@ export interface IReq_Relay_Cloudly_GetClusterRouteTable extends plugins.typedre
  * Both hops judge the body in the one server order `protocol.readProtocolOffer`
  * states, negotiating before the bearer is verified, as the shape states at
  * `validateClusterIngressRegistration`.
+ *
+ * A protocol mismatch is refused with `IProtocolRefusal`; every other refusal
+ * travels as `IClusterIngressRegistrationRefusal` in `TypedResponseError.errorData`,
+ * naming the reason and the `retryAfterMs` the ingress waits before it registers
+ * again. The relay forwards Cloudly's refusal untouched and refuses with the same
+ * shape when it cannot reach Cloudly at all (`not-ready`).
  */
 export interface IReq_Ingress_Relay_Cloudly_RegisterClusterIngress extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -100,6 +112,25 @@ export interface IReq_Ingress_Relay_Cloudly_RegisterClusterIngress extends plugi
   };
 }
 
+/**
+ * The relay tells its registered ingress that it holds a newer table.
+ *
+ * A hint, not a delivery: it carries the revision alone and nothing secret, and
+ * the ingress answers it by pulling `getClusterIngressRouteTable` with the
+ * revision it already applied. A lost or repeated hint costs nothing, because the
+ * table's own revision is the idempotency; a hint whose revision is not greater
+ * than the applied one is ignored.
+ */
+export interface IReq_Relay_Ingress_PushClusterIngressRouteTableChanged
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Ingress_PushClusterIngressRouteTableChanged
+> {
+  method: 'pushClusterIngressRouteTableChanged';
+  request: clusterIngressInterfaces.IClusterIngressRouteTableChange;
+  response: Record<string, never>;
+}
+
 /**
  * The ingress fetches the table the relay holds.
  *
@@ -147,3 +178,37 @@ export interface IReq_Any_Ingress_GetClusterTrafficStatistics extends plugins.ty
     nextCursor?: string;
   };
 }
+
+/**
+ * Cloudly designates one existing service as the ingress of a cluster born on Pallet, creating the
+ * managed ingress bearer and the designation atomically. A cluster holds one kind of designation:
+ * Cloudly refuses a cluster that holds a fleet-cutover ingress designation.
+ */
+export interface IReq_Admin_Cloudly_DesignateClusterIngress
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_DesignateClusterIngress
+> {
+  method: 'designateClusterIngress';
+  request: {
+    identity: IIdentityCredential;
+    designation: IClusterIngressDesignationRequest;
+  };
+  response: {
+    designation: IClusterIngressDesignation;
+    /** The ingress service's exact-cluster runtime spec the designation was accepted against. */
+    spec: IServiceRuntimeSpec;
+    replayed: boolean;
+  };
+}
+
+/** The cluster's current ingress designation; `null` when the cluster holds none of this kind. */
+export interface IReq_Admin_Cloudly_GetClusterIngressDesignation
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_GetClusterIngressDesignation
+> {
+  method: 'getClusterIngressDesignation';
+  request: { identity: IIdentityCredential; clusterId: string };
+  response: { designation: IClusterIngressDesignation | null };
+}

package/ts/requests/runtimesession.ts

@@ -8,6 +8,7 @@ import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
 import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
+import type * as localStorage from '../data/runtimelocalstorageclaim.js';
 
 /** Current-peer, exact-projection authorization; response contains secret keys. */
 export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredential extends plugins.typedrequestInterfaces.implementsTR<
@@ -163,6 +164,21 @@ export interface IReq_Controller_Pallet_ApplyRuntimeAssignment extends plugins.t
   response: data.IApplyRuntimeAssignmentResponse;
 }
 
+/**
+ * Controller push of one local storage claim over the already authenticated Pallet-initiated
+ * connection; `bindApplyRuntimeLocalStorageClaimRequest` binds it to that session. The answer is a
+ * durable admission acknowledgement plus the volume's state; it grants no mount by itself, which
+ * only an assignment that seals the claim's reference does.
+ */
+export interface IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim
+> {
+  method: 'applyRuntimeLocalStorageClaim';
+  request: localStorage.IApplyRuntimeLocalStorageClaimRequest;
+  response: localStorage.IApplyRuntimeLocalStorageClaimResponse;
+}
+
 /** Current-peer report, including exact historical outbox recovery after reconnect. */
 export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservation extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,