@serve.zone/interfaces 32.49.0 → 32.51.0

package/ts/data/networkapplication.ts

@@ -0,0 +1,188 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeNetworkNodeScope } from './networkprojection.js';
+import { computeRuntimeNetworkProjectionDigest, snapshotRuntimeNetworkNodeScope,
+  snapshotRuntimeNetworkProjection } from './networkprojection.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import { captureNetwork, failNetwork, networkDigest, networkEqual, networkHash, networkId, networkRecord,
+  networkReference, networkReferenceOf, networkRevision, networkSafe, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * A node's durable statement that its packet authority is bounded by one admitted projection.
+ *
+ * Every packet table the node holds was composed from `projection`, or the node holds none: 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 — never an admission ACK, a single table inspection or a
+ * caller-selected flag. A crash, a reboot or a restored guard only removes authority, so a receipt
+ * never becomes false; applying a successor projection supersedes it.
+ *
+ * `nativeJournal` names the node-private joined packet journal that applied the projection, or is
+ * null when the node holds no packet table at all. The receipts of one node form one monotonic
+ * chain; a receipt never names an older projection than its predecessor. These portable values
+ * neither inspect a kernel nor authenticate their producer: the receiver binds the report to the
+ * current authenticated session or its own reporter history.
+ */
+export interface IRuntimeNetworkProjectionApplicationReceipt extends IRuntimeNetworkNodeScope {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  projection: IRuntimeAuthorityReference;
+  reporterSessionId: string;
+  bootId: string;
+  nativeJournal: IRuntimeAuthorityReference | null;
+  digest: TSha256Digest;
+}
+
+export interface IReportRuntimeNetworkProjectionApplicationRequest {
+  session: IRuntimeSessionBinding;
+  receipt: IRuntimeNetworkProjectionApplicationReceipt;
+}
+export interface IReportRuntimeNetworkProjectionApplicationResponse {
+  status: 'accepted' | 'replay';
+  receipt: IRuntimeAuthorityReference;
+  authorityUse: 'current' | 'historical';
+}
+
+export const runtimeNetworkProjectionApplicationContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-network-projection-application-receipt',
+  claim: 'packet-authority-within-the-grants-of-the-named-projection',
+  receiptSource: 'joined-native-packet-journal-or-no-packet-table',
+  appliedPrevious: 'only-a-receipt-naming-the-exact-previous-projection',
+  olderProjection: 'advances-the-chain-never-applied-previous',
+  acknowledgement: 'an-admission-ack-is-never-an-application-receipt',
+  authentication: 'current-authenticated-session-or-receiver-reporter-history',
+} as const);
+
+const bootIdPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const scopeOf = (value: IRuntimeNetworkNodeScope): IRuntimeNetworkNodeScope =>
+  ({ controller: value.controller, nodeId: value.nodeId, runtimeNamespace: value.runtimeNamespace });
+const bootId = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && bootIdPattern.test(value) && value !== '00000000-0000-0000-0000-000000000000');
+  return value;
+};
+
+/** Exact-key structural snapshot; digest and chain rules are `admitRuntimeNetworkProjectionApplicationReceipt`'s. */
+export const snapshotRuntimeNetworkProjectionApplicationReceipt = (
+  value: unknown,
+): IRuntimeNetworkProjectionApplicationReceipt => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'generation', 'previous', 'controller', 'nodeId',
+    'runtimeNamespace', 'projection', 'reporterSessionId', 'bootId', 'nativeJournal', 'digest']);
+  const scope = snapshotRuntimeNetworkNodeScope({ controller: item.controller, nodeId: item.nodeId,
+    runtimeNamespace: item.runtimeNamespace });
+  return { ...networkRevision(item), ...scope, projection: networkReference(item.projection),
+    reporterSessionId: networkId(item.reporterSessionId), bootId: bootId(item.bootId),
+    nativeJournal: item.nativeJournal === null ? null : networkReference(item.nativeJournal),
+    digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkProjectionApplicationReceiptDigest = (
+  value: IRuntimeNetworkProjectionApplicationReceipt,
+): Promise<TSha256Digest> => networkHash(runtimeNetworkProjectionApplicationContract.digestDomain,
+  snapshotRuntimeNetworkProjectionApplicationReceipt(value));
+
+/**
+ * Pure chain binding of one reported receipt. `previousReceiptValue` is the receiver's current
+ * receipt for the node, or null while it holds none; `headValue` is the receiver's current
+ * projection for the node. The owner must authenticate the reporter and fence its writes.
+ *
+ * The receipt names the head's projection chain at a generation the head has reached: the head
+ * itself, exactly, or an older generation. An older one is a receipt minted before the node
+ * admitted the head; it advances the chain and is never usable as `appliedPrevious`.
+ */
+export const admitRuntimeNetworkProjectionApplicationReceipt = async (
+  value: unknown, previousReceiptValue: unknown | null, trustedScopeValue: unknown, headValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; receipt: IRuntimeNetworkProjectionApplicationReceipt }> => {
+  try {
+    const receipt = snapshotRuntimeNetworkProjectionApplicationReceipt(value);
+    const previous = previousReceiptValue === null ? null : snapshotRuntimeNetworkProjectionApplicationReceipt(previousReceiptValue);
+    const scope = snapshotRuntimeNetworkNodeScope(captureNetwork(trustedScopeValue));
+    const head = snapshotRuntimeNetworkProjection(headValue);
+    requireNetwork(networkEqual(scopeOf(receipt), scope) && networkEqual(scopeOf(head), scope));
+    requireNetwork(receipt.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(receipt)
+      && head.digest === await computeRuntimeNetworkProjectionDigest(head));
+    requireNetwork(receipt.projection.id === head.id && receipt.projection.generation <= head.generation);
+    if (receipt.projection.generation === head.generation) requireNetwork(networkEqual(receipt.projection, networkReferenceOf(head)));
+    if (previous === null) requireNetwork(receipt.generation === 1 && receipt.previous === null);
+    else {
+      requireNetwork(networkEqual(scopeOf(previous), scope)
+        && previous.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(previous));
+      if (networkEqual(receipt, previous)) return { status: 'replay', receipt };
+      requireNetwork(receipt.id === previous.id && receipt.generation === previous.generation + 1
+        && networkEqual(receipt.previous, networkReferenceOf(previous))
+        && receipt.projection.id === previous.projection.id
+        && receipt.projection.generation >= previous.projection.generation);
+      if (receipt.projection.generation === previous.projection.generation) {
+        requireNetwork(networkEqual(receipt.projection, previous.projection));
+      }
+    }
+    return { status: 'accepted', receipt };
+  } catch { return failNetwork(); }
+};
+
+/**
+ * The `appliedPrevious` argument of `admitRuntimeNetworkProjection` for the successor of
+ * `previousProjectionValue`: the receipt's projection when it is exactly that projection, else
+ * null. `receiptValue` must be the receiver's own admitted receipt for the node (a node passes its
+ * own durable receipt, a controller the latest receipt it admitted), never an ACK field.
+ */
+export const selectRuntimeNetworkProjectionAppliedPrevious = async (
+  receiptValue: unknown | null, previousProjectionValue: unknown,
+): Promise<IRuntimeAuthorityReference | null> => {
+  try {
+    // Snapshot both caller-owned inputs before the first asynchronous operation.
+    const previous = snapshotRuntimeNetworkProjection(previousProjectionValue);
+    const receipt = receiptValue === null ? null : snapshotRuntimeNetworkProjectionApplicationReceipt(receiptValue);
+    requireNetwork(previous.digest === await computeRuntimeNetworkProjectionDigest(previous));
+    if (receipt === null) return null;
+    requireNetwork(networkEqual(scopeOf(receipt), scopeOf(previous))
+      && receipt.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(receipt));
+    return networkEqual(receipt.projection, networkReferenceOf(previous)) ? networkReferenceOf(receipt.projection) : null;
+  } catch { return failNetwork(); }
+};
+
+export const snapshotReportRuntimeNetworkProjectionApplicationRequest = (
+  value: unknown,
+): IReportRuntimeNetworkProjectionApplicationRequest => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['session', 'receipt']);
+  return { session: snapshotRuntimeSessionBinding(item.session),
+    receipt: snapshotRuntimeNetworkProjectionApplicationReceipt(item.receipt) };
+});
+
+/**
+ * Both trusted bindings come from the receiver's fenced physical-session/history owner: the
+ * current session, and the session history entry that names the receipt's reporter. A receipt
+ * minted under an earlier session of the same node still drains from its outbox as `historical`.
+ */
+export const bindReportRuntimeNetworkProjectionApplicationRequest = (
+  value: unknown, trustedCurrentSessionValue: unknown, trustedReporterSessionValue: unknown,
+): { request: IReportRuntimeNetworkProjectionApplicationRequest; authorityUse: 'current' | 'historical' } => networkSafe(() => {
+  const request = snapshotReportRuntimeNetworkProjectionApplicationRequest(value);
+  const current = snapshotRuntimeSessionBinding(captureNetwork(trustedCurrentSessionValue));
+  const reporter = snapshotRuntimeSessionBinding(captureNetwork(trustedReporterSessionValue));
+  requireNetwork(networkEqual(request.session, current) && networkEqual(scopeOf(request.receipt), scopeOf(current))
+    && networkEqual(scopeOf(reporter), scopeOf(current)) && reporter.reporterSessionId === request.receipt.reporterSessionId);
+  const authorityUse = reporter.reporterSessionId === current.reporterSessionId ? 'current' : 'historical';
+  requireNetwork(authorityUse === 'current' ? networkEqual(reporter, current)
+    : reporter.sessionEpoch < current.sessionEpoch && reporter.credentialGeneration <= current.credentialGeneration);
+  return { request, authorityUse };
+});
+
+export const snapshotReportRuntimeNetworkProjectionApplicationResponse = (
+  value: unknown,
+): IReportRuntimeNetworkProjectionApplicationResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['status', 'receipt', 'authorityUse']);
+  requireNetwork((item.status === 'accepted' || item.status === 'replay')
+    && (item.authorityUse === 'current' || item.authorityUse === 'historical'));
+  return { status: item.status, receipt: networkReference(item.receipt), authorityUse: item.authorityUse };
+});
+
+/** Compare the response with the exact SENT receipt, never with a response-derived value. */
+export const bindReportRuntimeNetworkProjectionApplicationResponse = (
+  value: unknown, sentReceiptValue: unknown,
+): IReportRuntimeNetworkProjectionApplicationResponse => networkSafe(() => {
+  const response = snapshotReportRuntimeNetworkProjectionApplicationResponse(value);
+  requireNetwork(networkEqual(response.receipt, networkReference(captureNetwork(sentReceiptValue))));
+  return response;
+});

package/ts/data/networkprojection.ts

@@ -788,9 +788,11 @@ export const bindRuntimeNetworkWorkloadLeaseToAssignment = async (leaseValue: un
 };
 
 /**
- * Pure revision decision. appliedPrevious must be the receiver's exact durable,
- * joined application receipt, never an incoming ACK field. All prior accepted
- * material/apply journals survive until effects and DNS/allocation quarantine end.
+ * Pure revision decision. appliedPrevious must come from the receiver's exact durable,
+ * joined application receipt (`IRuntimeNetworkProjectionApplicationReceipt`, selected by
+ * `selectRuntimeNetworkProjectionAppliedPrevious`), never from an incoming ACK field. Only a
+ * receipt naming exactly `previousValue` releases its carried withdrawals and tombstones. All
+ * prior accepted material/apply journals survive until effects and DNS/allocation quarantine end.
  */
 export const admitRuntimeNetworkProjection = async (
   value: unknown, previousValue: unknown | null, trustedScopeValue: unknown, appliedPreviousValue: unknown | null,

package/ts/requests/runtimesession.ts

@@ -4,6 +4,7 @@ import type * as binding from '../data/noderuntimebinding.js';
 import type * as terminal from '../data/runtimeterminalreceipt.js';
 import type * as network from '../data/networkdelivery.js';
 import type * as protection from '../data/networkprotection.js';
+import type * as application from '../data/networkapplication.js';
 import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
@@ -32,6 +33,19 @@ export interface IReq_Pallet_Controller_ReportRuntimeNetworkProtection extends p
   response: protection.IReportRuntimeNetworkProtectionResponse;
 }
 
+/**
+ * Current authenticated peer reports its durable joined application receipt: the projection that
+ * bounds its packet authority. The controller passes it as `appliedPrevious` only while it names
+ * the exact head; an admission ACK never stands in for it.
+ */
+export interface IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication
+> {
+  method: 'reportRuntimeNetworkProjectionApplication';
+  request: application.IReportRuntimeNetworkProjectionApplicationRequest;
+  response: application.IReportRuntimeNetworkProjectionApplicationResponse;
+}
+
 /**
  * Current authenticated Pallet session only. Cloudly reads the current pallet runtime and exact
  * owner records, then grants one held prepared handoff; serialized session content is no proof.

package/ts/requests/service.ts

@@ -17,7 +17,10 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
-import type { ILegacyServiceRuntimeAttestation } from '../data/deploymentlegacyimport.js';
+import type {
+  ILegacyServiceHostObservation,
+  ILegacyServiceRuntimeAttestation,
+} from '../data/deploymentlegacyimport.js';
 import type { IProtocolOffer } from '../protocol.js';
 import type {
   IRuntimeAssignmentLogAttemptPage,
@@ -330,10 +333,13 @@ extends plugins.typedrequestInterfaces.implementsTR<
 }
 
 /**
- * Captures durable evidence that a legacy `deployOnPush` service runs exactly the registry root its
- * tag names: every required replica observed healthy on that one digest, with the root's platform
- * manifests read from Cloudly's own registry. Administrators only, and only while the legacy
- * runtime still runs — incomplete evidence is refused, never stored.
+ * Captures durable evidence that a legacy `deployOnPush` service runs exactly one registry root of
+ * its own repository, from an administrator's observation of its Swarm service and containers on
+ * the hosts that run them (`hostObservation`). Cloudly judges the observation itself
+ * (`data.judgeLegacyServiceHostObservation`): every desired replica running, healthy or without a
+ * healthcheck, on one root that is whole in Cloudly's own registry, its platform manifests read
+ * from there. The source tag need not still name that root. Administrators only, and only while
+ * the legacy runtime still runs — incomplete evidence is refused, never stored.
  *
  * `expectedRuntimeDigest`, when stated, is an assertion the observed digest must equal. Capturing
  * again for an unchanged digest returns the attestation already stored.
@@ -348,6 +354,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
     identity: IIdentityCredential;
     legacyServiceId: string;
     expectedRuntimeDigest?: TSha256Digest;
+    hostObservation: ILegacyServiceHostObservation;
   };
   response: {
     attestation: ILegacyServiceRuntimeAttestation;