@serve.zone/interfaces 32.49.0 → 32.51.0

package/readme.md

@@ -711,9 +711,17 @@ 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.
+exact joined application of the preceding projection is supplied
+([Projection Application Receipts](#projection-application-receipts)).
+
+A signed grant is not yet a delivered flow. The receiving node enforces a grant
+only between two workloads attached behind its own router: the packet engine
+has no one-way grant across the inter-node tunnel, so a grant whose ingress
+lease and target lease run on different nodes is signed into both nodes'
+projections and admitted by both, yet neither builds a packet path for it and
+the flow stays denied. Until cross-node one-way grants exist, a controller may
+route a cluster ingress route to the target lease address and port only when the
+grant exists and both leases are placed on the same node.
 
 The optional `IRuntimeNetworkProjection.hostPlatformEndpointIds` lists the ids of
 the protected authority's platform endpoints whose address the projection's
@@ -784,7 +792,8 @@ rejects changed same-generation content, regressed membership/readiness evidence
 changed immutable address/DNS keys, and omitted packet grants without explicit
 withdrawal. Pending withdrawals/tombstones must carry forward until the caller
 supplies the exact previous projection reference from its own durable joined
-application receipt. That reference is never taken from an incoming ACK. Keep
+application receipt ([Projection Application Receipts](#projection-application-receipts)).
+That reference is never taken from an incoming ACK. Keep
 the accepted history and apply journal until native effects and DNS/allocation
 quarantine are settled; a complete new snapshot does not erase that history.
 
@@ -873,6 +882,63 @@ Noise implementation owns cryptographic validation and authentication. Credentia
 delivery does not prove a connected VPN, TUN ownership, packet enforcement or
 workload readiness, and does not replace explicit packet withdrawals.
 
+#### Projection Application Receipts
+
+`IRuntimeNetworkProjectionApplicationReceipt` is a node's durable statement that
+its packet authority is bounded by one admitted projection. Its claim is a
+ceiling: every packet table the node holds was composed from `projection`, or
+the node holds no packet table at all, so the flows its kernel admits are a
+subset of that projection's grants. Only the node's joined native packet owner
+can supply it: the journaled application of the projection's policies on every
+role, or the release of every table (`nativeJournal: null`). An admission ACK,
+a single table inspection or a success flag is never such evidence
+(`runtimeNetworkProjectionApplicationContract`). A crash, a reboot or a restored
+guard only removes authority, so a receipt stays true until the node starts
+applying a successor; from then on only the successor's receipt counts, because
+only the exact predecessor of an admitted projection is ever selected.
+
+A node's receipts form one monotonic chain bound to its node scope and reporter
+session; `bootId` records the boot that minted a receipt and is not compared.
+`admitRuntimeNetworkProjectionApplicationReceipt(receipt,
+previousReceipt, scope, head)` is the receiver's gate: the first receipt is
+generation 1, each successor names its exact predecessor, an identical receipt
+is a replay, and the named projection never goes back. The receipt must name
+the head's projection chain at a generation the head has reached: the head
+exactly, or an older generation. An older one was minted before the node
+admitted the head; it advances the chain and is never usable.
+
+`selectRuntimeNetworkProjectionAppliedPrevious(receipt, previous)` returns the
+`appliedPrevious` argument of `admitRuntimeNetworkProjection` for the successor
+of `previous`: the receipt's projection reference when it is exactly `previous`,
+otherwise null. A controller passes the latest receipt it admitted for the node;
+the node passes its own durable receipt to its own admission. Only the exact
+predecessor counts. A receipt for an older projection proves nothing about the
+grants issued since, so it releases nothing.
+
+This is why withdrawals now drop. A projection carries its predecessor's
+withdrawals, and may not grant a withdrawn flow again, until `appliedPrevious`
+names that predecessor. Once a receipt proves the node applied it, the node's
+packet authority is within the predecessor's grants, so the successor states
+only the withdrawals of grants the predecessor held and it drops. A flow
+withdrawn earlier can then be granted again. Without receipts, withdrawals only
+accumulate up to their bound, and a withdrawn flow stays withdrawn until a lease
+changes.
+
+`reportRuntimeNetworkProjectionApplication`
+(`IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication`) carries a
+receipt on the current authenticated physical session.
+`bindReportRuntimeNetworkProjectionApplicationRequest` binds it to the current
+session and the receiver-owned reporter history, as protection reports are
+bound: a receipt minted under an earlier session of the same node still drains
+from its outbox as `historical`. The response must match the exact sent receipt
+(`bindReportRuntimeNetworkProjectionApplicationResponse`). Trust rests on the
+authenticated session; the contract has no node signing key. A node's receipt
+only loosens that node's own enforcement, so a node that misreports it gains no
+authority over any other node. Each node's receipt chain is independent: a flow
+granted in the projections of two nodes is released on each by that node's own
+receipt. A receipt is not an admission acknowledgement, and an acknowledgement
+is never a receipt.
+
 ### Egress Owner Retirement
 
 An owner that is offline, revoked or gone can never acknowledge a successor, so
@@ -3574,7 +3640,7 @@ The immutable deployment workflow is:
 
 A legacy `deployOnPush` service without deployable source moves to a greenfield successor by a legacy import, which replaces step 2:
 
-- While the legacy replicas still run — before its runtime is frozen — an administrator captures the evidence with `captureLegacyServiceRuntimeAttestation` (`requests.service.IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation`). The stored `data.ILegacyServiceRuntimeAttestation` records every required replica healthy on one digest, the registry root the legacy tag names, and that root's platform manifests; `data.validateLegacyServiceRuntimeAttestation` states its rules. Incomplete evidence is refused, never stored, and there is no substitute once the runtime is stopped. `getLegacyServiceRuntimeAttestations` lists what Cloudly holds for a legacy service; both requests are for administrators only.
+- While the legacy replicas still run — before its runtime is frozen — an administrator reads the legacy Swarm service and every container of its tasks on the hosts that run them, and submits that as `hostObservation` (`data.ILegacyServiceHostObservation`: Swarm service name, spec image and mode with its desired replicas; per replica the node hostname, Swarm task id, container id, the engine's image store, the container's image id, the image's `RepoDigests`, the container state and its health, `none` when no healthcheck applies) to `captureLegacyServiceRuntimeAttestation` (`requests.service.IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation`). `data.validateLegacyServiceHostObservation` judges its shape, `data.selectLegacyServiceHostObservationRootDigest` names the one root every replica runs from the service's own repository, and `data.judgeLegacyServiceHostObservation` judges it against that root as Cloudly reads it from its own registry: exactly the desired replicas of a replicated service, its spec image naming the repository by the source tag or the root digest, every replica `running` and `healthy` or `none`, each container's image id the root digest on the containerd image store or one of the root's platform image configuration digests on the classic store. The source tag need not still name the root. The stored `data.ILegacyServiceRuntimeAttestation` records that root, its platform manifests, the replicas, the evidence source `administrator-host-observation` and the observation itself; `data.validateLegacyServiceRuntimeAttestation` states its rules. Incomplete evidence is refused, never stored, and there is no substitute once the runtime is stopped. `getLegacyServiceRuntimeAttestations` lists what Cloudly holds for a legacy service; both requests are for administrators only.
 - The greenfield reservation, and every preflight of it, names `legacyImport` (`data.ILegacyImageImportReference`: legacy service, attestation, asserted source root digest) instead of `sourceRevision`, `sourceDirty` and release evidence. Refusals are the blockers `LEGACY_IMPORT_ATTESTATION_MISSING`, `LEGACY_IMPORT_SOURCE_MISMATCH` and `LEGACY_IMPORT_PLATFORM_MISMATCH`.
 - Instead of the registry push, the deployer calls `importServiceDeploymentLegacyImage`: Cloudly imports the attested image from its own registry into the reserved tag — an index root as it is, a single platform manifest under a one-descriptor index of the manifest's own family — and records release evidence of source `cloudly-legacy-import` naming the legacy source. Steps 3 to 5 follow unchanged; `selectTrustedImageReleaseEvidence` accepts that evidence only with `evidenceSource: 'cloudly-legacy-import'`.
 - The reservation and the import need the capability `deployment:import-legacy`, which only an organization-service-slot grant can carry.

package/ts/00_commitinfo_data.ts

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

package/ts/data/deploymentlegacyimport.ts

@@ -4,15 +4,22 @@ import type {
   TSha256Digest,
 } from './immutableimage.js';
 import { normalizeSha256Digest } from './immutableimage.js';
-import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import {
+  hasExactKeys,
+  isPlainRecord,
+  readDataElements,
+  readDataProperties,
+} from '../private/dataproperties.js';
 
 /**
  * Legacy image import: a greenfield deployment whose image is the one a legacy `deployOnPush`
  * service already runs, instead of one built from a source revision.
  *
  * A legacy service without deployable source still has an image in Cloudly's registry and, until
- * its runtime is frozen, healthy replicas running it. An administrator captures that fact once as
- * a {@link ILegacyServiceRuntimeAttestation} while the replicas still run. A greenfield successor
+ * its runtime is frozen, replicas running it. An administrator observes those replicas on the
+ * hosts that run them ({@link ILegacyServiceHostObservation}) while they still run, and Cloudly
+ * captures that observation once as a {@link ILegacyServiceRuntimeAttestation} after it verified
+ * the observed root against its own registry. A greenfield successor
  * reservation names the attestation in `legacyImport` instead of a `sourceRevision`, and Cloudly
  * then imports the attested image into the successor's own repository and release tag itself:
  * the bytes never leave the registry and the release records that it was imported, not built.
@@ -60,19 +67,98 @@ export interface ILegacyServiceImageSource {
   platforms: ILegacyImagePlatformManifest[];
 }
 
-/** One healthy replica of the legacy service, observed running the attested digest. */
+/**
+ * One replica of the legacy service, observed running the attested digest in its own stated
+ * health: healthy, or running with no healthcheck that could state one.
+ */
 export interface ILegacyServiceRuntimeTaskAttestation {
+  /** The replica's runtime identity: the Swarm task it was observed as. */
   deploymentId: string;
+  /** The hostname of the node the replica was observed on. */
   nodeName: string;
   observedDigest: TSha256Digest;
 }
 
+/**
+ * Where the runtime part of an attestation comes from. `administrator-host-observation`: an
+ * administrator read the legacy Swarm service and its containers on the hosts that run them, and
+ * Cloudly judged that observation against its own registry.
+ */
+export type TLegacyServiceRuntimeEvidenceSource = 'administrator-host-observation';
+
+/** A container's state as the Docker engine reports it (`State.Status`). */
+export type TLegacyHostContainerState =
+  | 'created'
+  | 'running'
+  | 'paused'
+  | 'restarting'
+  | 'removing'
+  | 'exited'
+  | 'dead';
+
+/**
+ * A container's health as the Docker engine reports it (`State.Health.Status`). `none`: no
+ * healthcheck applies to the container — the image declares none and the service adds none — so
+ * the engine reports no health state at all.
+ */
+export type TLegacyHostContainerHealth = 'healthy' | 'unhealthy' | 'starting' | 'none';
+
+/**
+ * The image store of the Docker engine that runs a container. On the `containerd` store a
+ * container's image id is the digest of the root it was pulled as; on the `classic` store it is
+ * the image configuration digest of the platform manifest the engine pulled.
+ */
+export type TLegacyHostImageStore = 'containerd' | 'classic';
+
+/** A Swarm service's mode (`Spec.Mode`): a replicated service states its desired replicas. */
+export type TLegacyHostSwarmServiceMode =
+  | { kind: 'replicated'; desiredReplicas: number }
+  | { kind: 'global' };
+
+/** One replica of a legacy Swarm service, as an administrator read it on the node that runs it. */
+export interface ILegacyHostReplicaObservation {
+  /** The hostname of the node the task runs on. */
+  nodeHostname: string;
+  /** The Swarm task id (25 lowercase base-36 characters). */
+  swarmTaskId: string;
+  /** The full container id of the task (64 lowercase hex characters). */
+  containerId: string;
+  imageStore: TLegacyHostImageStore;
+  /** The container's image id (`Image`), a sha256 digest. */
+  containerImageId: TSha256Digest;
+  /** The `RepoDigests` of the container's image, exactly as the engine lists them. */
+  imageRepoDigests: string[];
+  state: TLegacyHostContainerState;
+  health: TLegacyHostContainerHealth;
+}
+
+/**
+ * An administrator's observation of the legacy Swarm service of one legacy service and of every
+ * container its tasks run, read on the hosts while the legacy runtime still runs.
+ *
+ * It states facts, not conclusions: Cloudly judges it against its own registry
+ * ({@link judgeLegacyServiceHostObservation}) before it attests anything.
+ */
+export interface ILegacyServiceHostObservation {
+  /** The Swarm service name. */
+  swarmServiceName: string;
+  /** The image reference of the Swarm service spec (`Spec.TaskTemplate.ContainerSpec.Image`). */
+  specImage: string;
+  mode: TLegacyHostSwarmServiceMode;
+  /** When the administrator read the hosts, in milliseconds since the epoch. */
+  observedAt: number;
+  /** Every running task's replica, sorted by `swarmTaskId`. */
+  replicas: ILegacyHostReplicaObservation[];
+}
+
 /**
  * Durable evidence, captured by an administrator while the legacy runtime still ran, that every
- * required replica of a legacy service was healthy and ran exactly the registry root it names.
+ * desired replica of a legacy service ran, in its own stated health, exactly the registry root it
+ * names.
  *
  * Cloudly writes one and never changes it. A capture only succeeds on complete evidence, so a
- * stored attestation is by construction one whose runtime digest is its source root digest.
+ * stored attestation is by construction one whose runtime digest is its source root digest and
+ * whose runtime part is exactly the host observation it records.
  */
 export interface ILegacyServiceRuntimeAttestation {
   id: string;
@@ -81,11 +167,16 @@ export interface ILegacyServiceRuntimeAttestation {
     organizationId: string;
     source: ILegacyServiceImageSource;
     runtime: {
+      /** The desired replicas of the observed replicated Swarm service. */
       requiredReplicaCount: number;
+      /** Replicas observed running healthy, or running with no healthcheck (`health: 'none'`). */
       healthyReplicaCount: number;
       runtimeDigest: TSha256Digest;
-      /** Sorted by deploymentId, one per required replica. */
+      /** Sorted by deploymentId, one per required replica: the observed replicas. */
       tasks: ILegacyServiceRuntimeTaskAttestation[];
+      evidenceSource: TLegacyServiceRuntimeEvidenceSource;
+      /** The observation the runtime part was built from, as the administrator submitted it. */
+      hostObservation: ILegacyServiceHostObservation;
     };
     capturedByUserId: string;
     capturedAt: number;
@@ -120,6 +211,31 @@ const legacyImageImportIndexMediaTypes: readonly TLegacyImageImportIndexMediaTyp
   'application/vnd.docker.distribution.manifest.list.v2+json',
 ];
 const legacyImagePlatforms: readonly TImmutableContainerPlatform[] = ['linux/amd64', 'linux/arm64'];
+const legacyHostContainerStates: readonly TLegacyHostContainerState[] = [
+  'created',
+  'running',
+  'paused',
+  'restarting',
+  'removing',
+  'exited',
+  'dead',
+];
+const legacyHostContainerHealths: readonly TLegacyHostContainerHealth[] = [
+  'healthy',
+  'unhealthy',
+  'starting',
+  'none',
+];
+/** The health states a replica may be attested in: healthy, or no healthcheck at all. */
+const attestableLegacyHostContainerHealths: readonly TLegacyHostContainerHealth[] = ['healthy', 'none'];
+const legacyHostImageStores: readonly TLegacyHostImageStore[] = ['containerd', 'classic'];
+const swarmTaskIdRegex = /^[a-z0-9]{25}$/;
+const containerIdRegex = /^[0-9a-f]{64}$/;
+const swarmServiceNameRegex = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/;
+const nodeHostnameRegex = /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+const imageReferenceRegex = /^\S{1,512}$/;
+const repoDigestRegex = /^[^\s@]{1,440}@sha256:[0-9a-f]{64}$/;
+const maximumRepoDigestCount = 32;
 
 const isIdentifier = (valueArg: unknown): valueArg is string => (
   typeof valueArg === 'string' && identifierRegex.test(valueArg)
@@ -168,6 +284,256 @@ export const validateLegacyImageImportReference = (referenceArg: unknown): strin
   return errors;
 };
 
+const validateHostReplicaObservation = (
+  replicaArg: unknown,
+  labelArg: string,
+): string[] => {
+  const replica = readDataProperties(replicaArg);
+  if (replica === null) return [`${labelArg} must be a plain data object`];
+  const errors: string[] = [];
+  if (!hasExactKeys(replica, [
+    'nodeHostname',
+    'swarmTaskId',
+    'containerId',
+    'imageStore',
+    'containerImageId',
+    'imageRepoDigests',
+    'state',
+    'health',
+  ])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof replica.nodeHostname !== 'string' || !nodeHostnameRegex.test(replica.nodeHostname)) {
+    errors.push(`${labelArg}.nodeHostname must be a host name`);
+  }
+  if (typeof replica.swarmTaskId !== 'string' || !swarmTaskIdRegex.test(replica.swarmTaskId)) {
+    errors.push(`${labelArg}.swarmTaskId must be a Swarm task id`);
+  }
+  if (typeof replica.containerId !== 'string' || !containerIdRegex.test(replica.containerId)) {
+    errors.push(`${labelArg}.containerId must be a full container id`);
+  }
+  if (!legacyHostImageStores.some((storeArg) => storeArg === replica.imageStore)) {
+    errors.push(`${labelArg}.imageStore must be containerd or classic`);
+  }
+  if (!isCanonicalDigest(replica.containerImageId)) {
+    errors.push(`${labelArg}.containerImageId must be a canonical sha256 digest`);
+  }
+  const repoDigests = readDataElements(replica.imageRepoDigests, maximumRepoDigestCount);
+  if (repoDigests === null
+    || repoDigests.some((entryArg) => typeof entryArg !== 'string' || !repoDigestRegex.test(entryArg))
+    || new Set(repoDigests).size !== repoDigests.length) {
+    errors.push(`${labelArg}.imageRepoDigests must be unique digested image references`);
+  }
+  if (!legacyHostContainerStates.some((stateArg) => stateArg === replica.state)) {
+    errors.push(`${labelArg}.state must be a Docker container state`);
+  }
+  if (!legacyHostContainerHealths.some((healthArg) => healthArg === replica.health)) {
+    errors.push(`${labelArg}.health must be healthy, unhealthy, starting or none`);
+  }
+  return errors;
+};
+
+const validateHostSwarmServiceMode = (modeArg: unknown, labelArg: string): string[] => {
+  const mode = readDataProperties(modeArg);
+  if (mode === null) return [`${labelArg} must be a plain data object`];
+  if (mode.kind === 'global') {
+    return hasExactKeys(mode, ['kind']) ? [] : [`${labelArg} must use its exact schema`];
+  }
+  if (mode.kind !== 'replicated') return [`${labelArg}.kind must be replicated or global`];
+  const errors: string[] = [];
+  if (!hasExactKeys(mode, ['kind', 'desiredReplicas'])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof mode.desiredReplicas !== 'number'
+    || !Number.isSafeInteger(mode.desiredReplicas)
+    || mode.desiredReplicas < 0
+    || mode.desiredReplicas > maximumReplicaCount) {
+    errors.push(`${labelArg}.desiredReplicas must be a bounded replica count`);
+  }
+  return errors;
+};
+
+/**
+ * The shape of a host observation: exact keys at every level, Docker's own value sets, at most 64
+ * replicas, unique and sorted by Swarm task id, each container observed once. It judges nothing
+ * against a registry; {@link judgeLegacyServiceHostObservation} does.
+ */
+export const validateLegacyServiceHostObservation = (
+  observationArg: unknown,
+  labelArg = 'hostObservation',
+): string[] => {
+  const observation = readDataProperties(observationArg);
+  if (observation === null) return [`${labelArg} must be a plain data object`];
+  const errors: string[] = [];
+  if (!hasExactKeys(observation, ['swarmServiceName', 'specImage', 'mode', 'observedAt', 'replicas'])) {
+    errors.push(`${labelArg} must use its exact schema`);
+  }
+  if (typeof observation.swarmServiceName !== 'string'
+    || !swarmServiceNameRegex.test(observation.swarmServiceName)) {
+    errors.push(`${labelArg}.swarmServiceName must be a Swarm service name`);
+  }
+  if (typeof observation.specImage !== 'string' || !imageReferenceRegex.test(observation.specImage)) {
+    errors.push(`${labelArg}.specImage must be a bounded image reference`);
+  }
+  errors.push(...validateHostSwarmServiceMode(observation.mode, `${labelArg}.mode`));
+  if (!isPositiveSafeInteger(observation.observedAt, Number.MAX_SAFE_INTEGER)) {
+    errors.push(`${labelArg}.observedAt must be a positive timestamp`);
+  }
+  const replicas = readDataElements(observation.replicas, maximumReplicaCount);
+  if (replicas === null) {
+    errors.push(`${labelArg}.replicas must be a list of at most ${maximumReplicaCount} replicas`);
+    return errors;
+  }
+  replicas.forEach((replicaArg, indexArg) => {
+    errors.push(...validateHostReplicaObservation(replicaArg, `${labelArg}.replicas[${indexArg}]`));
+  });
+  const readReplicaKey = (replicaArg: unknown, keyArg: string): unknown => (
+    readDataProperties(replicaArg)?.[keyArg]
+  );
+  const taskIds = replicas.map((replicaArg) => readReplicaKey(replicaArg, 'swarmTaskId'));
+  const sortedTaskIds = taskIds
+    .filter((idArg): idArg is string => typeof idArg === 'string')
+    .sort();
+  if (new Set(taskIds).size !== taskIds.length
+    || JSON.stringify(taskIds) !== JSON.stringify(sortedTaskIds)) {
+    errors.push(`${labelArg}.replicas must be unique and sorted by swarmTaskId`);
+  }
+  const containerIds = replicas.map((replicaArg) => readReplicaKey(replicaArg, 'containerId'));
+  if (new Set(containerIds).size !== containerIds.length) {
+    errors.push(`${labelArg}.replicas must observe each container once`);
+  }
+  return errors;
+};
+
+/** True when a value is a well-formed host observation. */
+export const isLegacyServiceHostObservation = (
+  valueArg: unknown,
+): valueArg is ILegacyServiceHostObservation => (
+  validateLegacyServiceHostObservation(valueArg).length === 0
+);
+
+/**
+ * The root digest one replica was pulled as from `registryHost/repository`.
+ *
+ * On the containerd store that is the container's image id, which the image's `RepoDigests` must
+ * list for the repository. On the classic store it is the one digest `RepoDigests` lists for the
+ * repository; none, or more than one, leaves the root unknown.
+ */
+const selectReplicaRootDigest = (
+  replicaArg: ILegacyHostReplicaObservation,
+  repositoryReferenceArg: string,
+): TSha256Digest | undefined => {
+  const prefix = `${repositoryReferenceArg}@`;
+  const repositoryDigests = replicaArg.imageRepoDigests
+    .filter((entryArg) => entryArg.startsWith(prefix))
+    .map((entryArg) => normalizeSha256Digest(entryArg.slice(prefix.length)))
+    .filter((digestArg): digestArg is TSha256Digest => digestArg !== undefined);
+  if (replicaArg.imageStore === 'containerd') {
+    return repositoryDigests.includes(replicaArg.containerImageId)
+      ? replicaArg.containerImageId
+      : undefined;
+  }
+  return repositoryDigests.length === 1 ? repositoryDigests[0] : undefined;
+};
+
+/**
+ * The one root digest every observed replica runs from the legacy service's own repository, which
+ * is the digest Cloudly then inspects in its registry. Refused when a replica's root from that
+ * repository is unknown, when the replicas run more than one root, or when nothing was observed.
+ */
+export const selectLegacyServiceHostObservationRootDigest = (argsArg: {
+  observation: ILegacyServiceHostObservation;
+  registryHost: string;
+  repository: string;
+}): { rootDigest?: TSha256Digest; errors: string[] } => {
+  const repositoryReference = `${argsArg.registryHost}/${argsArg.repository}`;
+  const errors: string[] = [];
+  const roots = new Set<TSha256Digest>();
+  argsArg.observation.replicas.forEach((replicaArg, indexArg) => {
+    const root = selectReplicaRootDigest(replicaArg, repositoryReference);
+    if (root === undefined) {
+      errors.push(replicaArg.imageStore === 'containerd'
+        ? `hostObservation.replicas[${indexArg}] image is not listed as ${repositoryReference}@<its image id>`
+        : `hostObservation.replicas[${indexArg}] image lists not exactly one digest of ${repositoryReference}`);
+      return;
+    }
+    roots.add(root);
+  });
+  if (argsArg.observation.replicas.length === 0) {
+    errors.push('hostObservation must observe at least one replica');
+  }
+  if (roots.size > 1) {
+    errors.push('hostObservation replicas run more than one root digest');
+  }
+  const [rootDigest] = [...roots];
+  return errors.length === 0 && rootDigest !== undefined ? { rootDigest, errors } : { errors };
+};
+
+/**
+ * Judges a well-formed host observation against the registry source Cloudly inspected for it.
+ * Every rule an attestation's runtime part must meet:
+ *
+ * - the Swarm service is replicated, with at least one desired replica, and exactly its desired
+ *   replicas were observed;
+ * - its spec image names the source repository by the source tag, by the root digest, or by both;
+ * - every replica is `running`, and `healthy` or without a healthcheck (`none`) — `unhealthy` and
+ *   `starting` are refused;
+ * - every replica runs the source root from the source repository: its image lists
+ *   `registryHost/repository@rootDigest`, and its image id is the root digest on the containerd
+ *   store or one of the root's platform image configuration digests on the classic store.
+ */
+export const judgeLegacyServiceHostObservation = (argsArg: {
+  observation: ILegacyServiceHostObservation;
+  source: ILegacyServiceImageSource;
+  label?: string;
+}): string[] => {
+  const label = argsArg.label ?? 'hostObservation';
+  const { observation, source } = argsArg;
+  const errors: string[] = [];
+  if (observation.mode.kind !== 'replicated') {
+    errors.push(`${label}.mode must be replicated: a legacy service runs as a replicated Swarm service`);
+  } else if (observation.mode.desiredReplicas < 1) {
+    errors.push(`${label}.mode must desire at least one replica`);
+  } else if (observation.replicas.length !== observation.mode.desiredReplicas) {
+    errors.push(`${label} must observe exactly the ${observation.mode.desiredReplicas} desired replicas`);
+  }
+  const repositoryReference = `${source.registryHost}/${source.repository}`;
+  const specImages = [
+    `${repositoryReference}:${source.tag}`,
+    `${repositoryReference}@${source.rootDigest}`,
+    `${repositoryReference}:${source.tag}@${source.rootDigest}`,
+  ];
+  if (!specImages.includes(observation.specImage)) {
+    errors.push(`${label}.specImage must name ${repositoryReference} by its source tag or root digest`);
+  }
+  const imageConfigDigests = source.platforms.map((platformArg) => platformArg.imageConfigDigest);
+  observation.replicas.forEach((replicaArg, indexArg) => {
+    const replicaLabel = `${label}.replicas[${indexArg}]`;
+    if (replicaArg.state !== 'running') {
+      errors.push(`${replicaLabel}.state must be running`);
+    }
+    if (!attestableLegacyHostContainerHealths.includes(replicaArg.health)) {
+      errors.push(`${replicaLabel}.health must be healthy or none`);
+    }
+    if (!replicaArg.imageRepoDigests.includes(`${repositoryReference}@${source.rootDigest}`)) {
+      errors.push(`${replicaLabel} image must be ${repositoryReference}@${source.rootDigest}`);
+    }
+    if (replicaArg.imageStore === 'containerd') {
+      if (replicaArg.containerImageId !== source.rootDigest) {
+        errors.push(`${replicaLabel}.containerImageId must be the root digest on the containerd image store`);
+      }
+      return;
+    }
+    if (!imageConfigDigests.includes(replicaArg.containerImageId)) {
+      errors.push(`${replicaLabel}.containerImageId must be a platform image configuration digest of the root on the classic image store`);
+    }
+    if (selectReplicaRootDigest(replicaArg, repositoryReference) === undefined) {
+      errors.push(`${replicaLabel} image must list exactly one digest of ${repositoryReference} on the classic image store`);
+    }
+  });
+  return errors;
+};
+
 const validatePlatformManifest = (
   manifestArg: unknown,
   indexArg: number,
@@ -270,17 +636,54 @@ const validateImageSource = (sourceArg: unknown): string[] => {
   return errors;
 };
 
-const validateRuntime = (runtimeArg: unknown, rootDigestArg: unknown): string[] => {
+const isLegacyServiceImageSource = (valueArg: unknown): valueArg is ILegacyServiceImageSource => (
+  validateImageSource(valueArg).length === 0
+);
+
+const validateRuntime = (runtimeArg: unknown, sourceArg: unknown): string[] => {
   if (!isPlainRecord(runtimeArg)) return ['runtime must be an object'];
+  const rootDigest = isPlainRecord(sourceArg) ? sourceArg.rootDigest : undefined;
   const errors: string[] = [];
   if (!hasExactKeys(runtimeArg, [
     'requiredReplicaCount',
     'healthyReplicaCount',
     'runtimeDigest',
     'tasks',
+    'evidenceSource',
+    'hostObservation',
   ])) {
     errors.push('runtime must use its exact schema');
   }
+  if (runtimeArg.evidenceSource !== 'administrator-host-observation') {
+    errors.push('runtime.evidenceSource must be administrator-host-observation');
+  }
+  const hostObservation = runtimeArg.hostObservation;
+  const observationErrors = validateLegacyServiceHostObservation(
+    hostObservation, 'runtime.hostObservation');
+  errors.push(...observationErrors);
+  if (observationErrors.length === 0
+    && isLegacyServiceHostObservation(hostObservation)
+    && isLegacyServiceImageSource(sourceArg)) {
+    errors.push(...judgeLegacyServiceHostObservation({
+      observation: hostObservation,
+      source: sourceArg,
+      label: 'runtime.hostObservation',
+    }));
+    if (hostObservation.mode.kind === 'replicated'
+      && runtimeArg.requiredReplicaCount !== hostObservation.mode.desiredReplicas) {
+      errors.push('runtime.requiredReplicaCount must be the observed desired replicas');
+    }
+    const recordedTasks = readDataElements(runtimeArg.tasks, maximumReplicaCount) ?? [];
+    if (recordedTasks.length !== hostObservation.replicas.length
+      || hostObservation.replicas.some((replicaArg, indexArg) => {
+        const task = recordedTasks[indexArg];
+        return !isPlainRecord(task)
+          || task.deploymentId !== replicaArg.swarmTaskId
+          || task.nodeName !== replicaArg.nodeHostname;
+      })) {
+      errors.push('runtime.tasks must be the observed replicas: each Swarm task on its node');
+    }
+  }
   if (!isPositiveSafeInteger(runtimeArg.requiredReplicaCount, maximumReplicaCount)) {
     errors.push('runtime.requiredReplicaCount must be a positive bounded replica count');
   }
@@ -289,7 +692,7 @@ const validateRuntime = (runtimeArg: unknown, rootDigestArg: unknown): string[]
   }
   if (!isCanonicalDigest(runtimeArg.runtimeDigest)) {
     errors.push('runtime.runtimeDigest must be a canonical sha256 digest');
-  } else if (runtimeArg.runtimeDigest !== rootDigestArg) {
+  } else if (runtimeArg.runtimeDigest !== rootDigest) {
     errors.push('runtime.runtimeDigest must be the attested source root digest');
   }
   if (!Array.isArray(runtimeArg.tasks) || runtimeArg.tasks.length !== runtimeArg.requiredReplicaCount) {
@@ -363,9 +766,6 @@ export const validateLegacyServiceRuntimeAttestation = (attestationArg: unknown)
     errors.push('capturedAt must be a positive timestamp');
   }
   errors.push(...validateImageSource(data.source));
-  errors.push(...validateRuntime(
-    data.runtime,
-    isPlainRecord(data.source) ? data.source.rootDigest : undefined,
-  ));
+  errors.push(...validateRuntime(data.runtime, data.source));
   return errors;
 };

package/ts/data/index.ts

@@ -36,6 +36,7 @@ export * from './nodeenrollment.js';
 export * from './noderuntimebinding.js';
 export * from './noderetirement.js';
 export * from './networkaddressplan.js';
+export * from './networkapplication.js';
 export * from './networkauthority.js';
 export * from './networkcredential.js';
 export * from './networkdelivery.js';