@serve.zone/interfaces 32.49.0 → 32.51.0

package/changelog.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 2026-10-06 - 32.51.0
+
+### Features
+
+- A legacy service's runtime attestation is captured from an administrator's host observation, so
+  it no longer needs a fleet Coreflow session or Spark, which legacy hosts do not run.
+  `IRequest_Any_Cloudly_CaptureLegacyServiceRuntimeAttestation` now carries `hostObservation`
+  (`ILegacyServiceHostObservation`, `data/deploymentlegacyimport.ts`): the Swarm service name, spec
+  image and mode (`TLegacyHostSwarmServiceMode`, replicated with its desired replicas, or global),
+  and per replica the node hostname, Swarm task id, full container id, the engine's image store
+  (`TLegacyHostImageStore`), the container's image id, the image's `RepoDigests`, the container
+  state (`TLegacyHostContainerState`) and its health (`TLegacyHostContainerHealth`, `none` when no
+  healthcheck applies). `validateLegacyServiceHostObservation` judges its exact shape,
+  `selectLegacyServiceHostObservationRootDigest` names the one root every replica runs from the
+  service's own repository, and `judgeLegacyServiceHostObservation` judges it against that root as
+  Cloudly reads it: exactly the desired replicas of a replicated service, a spec image naming the
+  repository by the source tag or the root digest, every replica running and healthy or without a
+  healthcheck (`unhealthy` and `starting` are refused), and each container's image id the root
+  digest on the containerd image store or a platform image configuration digest of the root on the
+  classic store. The source tag need not still name the root.
+  `ILegacyServiceRuntimeAttestation.data.runtime` records `evidenceSource`
+  (`TLegacyServiceRuntimeEvidenceSource`, `administrator-host-observation`) and the
+  `hostObservation` it was built from; `validateLegacyServiceRuntimeAttestation` requires both and
+  that `requiredReplicaCount` and `tasks` are the observed desired replicas and Swarm tasks.
+  The capture request's `hostObservation` and the record's `evidenceSource`/`hostObservation` are
+  new required members, which stays a minor of the one common major 32 because the previous capture
+  had no success path on a fleet without a Coreflow session, no shipped store holds an attestation
+  record, and Cloudly is the only code consumer.
+
+### Maintenance
+
+- Release tooling: `@git.zone/tstest` 7.1.0 → 7.2.0. pnpm stays at 12.8.1 until 12.8.2 is seven days old (2026-10-07 01:15 UTC); `@types/node` stays at 26.6.3 until 26.6.4 is seven days old (2026-10-08 22:39 UTC).
+
+## 2026-10-06 - 32.50.0
+
+### Features
+
+- A node can prove which projection bounds its packet authority, so withdrawn flows can be granted
+  again. `IRuntimeNetworkProjectionApplicationReceipt` (`data/networkapplication.ts`) is a
+  node's durable, monotonic receipt that every packet table it holds was composed from one admitted
+  projection, or that it holds none. `admitRuntimeNetworkProjectionApplicationReceipt` binds the
+  chain (first generation, exact predecessor, replay, scope and controller) and the head (the
+  named projection never goes back and never passes the receiver's head; an older one advances the
+  chain only). `selectRuntimeNetworkProjectionAppliedPrevious` turns a receipt into the
+  `appliedPrevious` argument of `admitRuntimeNetworkProjection`: the receipt's projection only
+  when it is exactly the previous projection. `admitRuntimeNetworkProjection` itself is unchanged.
+  `requests.runtimesession.IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication`
+  (`reportRuntimeNetworkProjectionApplication`) carries a receipt on the current session, bound by
+  `bindReportRuntimeNetworkProjectionApplicationRequest` (`current` or `historical`, like
+  protection reports) and `bindReportRuntimeNetworkProjectionApplicationResponse`.
+- The workload ingress documentation no longer promises cross-node delivery: a grant is enforced
+  only between two workloads behind the same router until cross-node one-way grants exist.
+
 ## 2026-10-06 - 32.49.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 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.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/deploymentlegacyimport.d.ts

@@ -4,8 +4,10 @@ import type { TImmutableContainerPlatform, TOciManifestMediaType, TSha256Digest
  * 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.
@@ -44,18 +46,86 @@ 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;
@@ -64,11 +134,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;
@@ -89,4 +164,43 @@ export declare const isLegacyImagePlatformManifestMediaType: (valueArg: unknown)
 /** True when a media type names an index of either family. */
 export declare const isLegacyImageImportIndexMediaType: (valueArg: unknown) => valueArg is TLegacyImageImportIndexMediaType;
 export declare const validateLegacyImageImportReference: (referenceArg: unknown) => string[];
+/**
+ * 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 declare const validateLegacyServiceHostObservation: (observationArg: unknown, labelArg?: string) => string[];
+/** True when a value is a well-formed host observation. */
+export declare const isLegacyServiceHostObservation: (valueArg: unknown) => valueArg is ILegacyServiceHostObservation;
+/**
+ * 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 declare const selectLegacyServiceHostObservationRootDigest: (argsArg: {
+    observation: ILegacyServiceHostObservation;
+    registryHost: string;
+    repository: string;
+}) => {
+    rootDigest?: TSha256Digest;
+    errors: string[];
+};
+/**
+ * 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 declare const judgeLegacyServiceHostObservation: (argsArg: {
+    observation: ILegacyServiceHostObservation;
+    source: ILegacyServiceImageSource;
+    label?: string;
+}) => string[];
 export declare const validateLegacyServiceRuntimeAttestation: (attestationArg: unknown) => string[];