@serve.zone/interfaces 29.0.0 → 30.1.0

package/ts/data/runtimeterminalreceipt.ts

@@ -0,0 +1,338 @@
+import type { TSha256Digest } from './immutableimage.js';
+import { isSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignmentReferenceV1, IRuntimeAssignmentV1 } from './runtimeassignment.js';
+import { evaluateRuntimeAssignmentV1, getRuntimeAssignmentV1Reference,
+  snapshotRuntimeAssignmentV1 } from './runtimeassignment.js';
+import type { IRuntimeSessionBindingV1, TRuntimeObservationAuthorityUseV1 } from './runtimesession.js';
+import { bindRuntimeReporterSessionV1, snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+
+/** Exact value-free native terminal evidence; terminal inspection does not collect addresses. */
+export interface IRuntimeAssignmentTerminalEvidenceV1 {
+  phase: 'stopped' | 'absent';
+  sandboxId: string | null;
+  containerId: string | null;
+  imageConfigDigest: TSha256Digest | null;
+  /** Exactly empty for the qualified native stop/remove path; no route evidence. */
+  ipAddresses: string[];
+  exitCode: number | null;
+}
+
+/**
+ * Qualified only when the named Pallet owner has durably joined this exact native
+ * operation. Structure and digest alone do not prove that join. Pending, unknown
+ * and host-fenced journal entries can never issue this receipt. A new boot permits
+ * a new joined terminal operation; it cannot replace the stop/remove chain.
+ *
+ * This settles only the named Pallet attempt. It grants no readiness, routing,
+ * liveness, storage relocation, whole-host, Docker/Coreflow absence, other
+ * controller or cross-organization authority. It has no authoritative wall clock.
+ */
+export interface IRuntimeAssignmentTerminalReceiptV1 {
+  schemaVersion: 1;
+  /** Exact generation 2 stop or generation 3 remove revision. */
+  assignment: IRuntimeAssignmentReferenceV1;
+  /** Exact immutable generation 1 run revision. */
+  runAssignment: IRuntimeAssignmentReferenceV1;
+  reporterSessionId: string;
+  sequence: 1 | 2;
+  operation: {
+    id: string;
+    action: 'stop' | 'remove';
+    bootId: string;
+    status: 'completed';
+    evidence: IRuntimeAssignmentTerminalEvidenceV1;
+  };
+  /** Null for stop; the exact accepted stop receipt digest for remove. */
+  previousReceiptDigest: TSha256Digest | null;
+  digest: TSha256Digest;
+}
+
+export interface IReportRuntimeAssignmentTerminalReceiptRequestV1 {
+  /** Current physical peer binding, even when the immutable receipt is historical. */
+  session: IRuntimeSessionBindingV1;
+  receipt: IRuntimeAssignmentTerminalReceiptV1;
+}
+
+export interface IReportRuntimeAssignmentTerminalReceiptResponseV1 {
+  /** Exact immutable body after the owning durable receipt transaction. */
+  receipt: IRuntimeAssignmentTerminalReceiptV1;
+  /** Historical recovery never restores active readiness, routes or liveness. */
+  authorityUse: TRuntimeObservationAuthorityUseV1;
+}
+
+export type TRuntimeAssignmentTerminalReceiptDecisionV1 =
+  | { status: 'accept' | 'replay'; receipt: IRuntimeAssignmentTerminalReceiptV1 }
+  | { status: 'reject'; reason: 'invalid' | 'conflict' | 'sequence-gap' | 'predecessor-mismatch' };
+
+export const runtimeAssignmentTerminalReceiptV1Contract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-assignment-terminal-receipt-v1',
+  maximumReceiptCanonicalBytes: 16_384,
+  maximumHistoryCanonicalBytes: 98_304,
+  maximumReceipts: 2,
+  maximumAssignmentRevisions: 3,
+  error: 'Runtime terminal receipt contract rejected.',
+} as const);
+
+const fail = (): never => { throw new Error(runtimeAssignmentTerminalReceiptV1Contract.error); };
+function requireValue(conditionArg: unknown): asserts conditionArg { if (!conditionArg) fail(); }
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+const canonical = (valueArg: unknown): string => canonicalizeStrictJson(valueArg, fail);
+const encoder = new TextEncoder();
+const identifier = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg));
+  return valueArg;
+};
+const digest = (valueArg: unknown): TSha256Digest => {
+  requireValue(typeof valueArg === 'string' && isSha256Digest(valueArg));
+  return valueArg;
+};
+
+/** Bounded inert copy before hashing or calling any nested validator. */
+const capture = (valueArg: unknown, maximumBytesArg: number = runtimeAssignmentTerminalReceiptV1Contract.maximumHistoryCanonicalBytes): unknown => safe(() => {
+  let nodes = 0;
+  let bytes = 0;
+  const ancestors = new Set<object>();
+  const account = (value: string): void => {
+    requireValue(value.length <= maximumBytesArg);
+    bytes += encoder.encode(value).byteLength;
+    requireValue(bytes <= maximumBytesArg);
+  };
+  const copy = (value: unknown, depth: number): unknown => {
+    requireValue(++nodes <= 4096 && depth <= 12);
+    if (typeof value === 'string') { account(value); return value; }
+    if (value === null || typeof value === 'boolean' || typeof value === 'number') return value;
+    requireValue(value !== null && typeof value === 'object' && !ancestors.has(value));
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    requireValue(array ? prototype === Array.prototype : prototype === Object.prototype || prototype === null);
+    ancestors.add(value);
+    try {
+      const keys = Reflect.ownKeys(value);
+      requireValue(keys.length <= 65);
+      if (array) {
+        const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+        requireValue(Number.isSafeInteger(length) && length >= 0 && length <= 64 && keys.length === length + 1);
+        const result: unknown[] = [];
+        for (let index = 0; index < length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+          result.push(copy(descriptor.value, depth + 1));
+        }
+        return result;
+      }
+      const result: Record<string, unknown> = Object.create(null);
+      for (const key of keys) {
+        requireValue(typeof key === 'string'); account(key);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+        result[key] = copy(descriptor.value, depth + 1);
+      }
+      return result;
+    } finally { ancestors.delete(value); }
+  };
+  const serialized = canonical(copy(valueArg, 0));
+  requireValue(encoder.encode(serialized).byteLength <= maximumBytesArg);
+  return JSON.parse(serialized);
+});
+const record = (valueArg: unknown, keysArg: string[]): Record<string, unknown> => {
+  requireValue(valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg));
+  const keys = Object.keys(valueArg);
+  requireValue(keys.length === keysArg.length && keys.every((key) => keysArg.includes(key)));
+  return valueArg as Record<string, unknown>;
+};
+const reference = (valueArg: unknown): IRuntimeAssignmentReferenceV1 => {
+  const value = record(valueArg, ['assignmentId', 'generation', 'digest']);
+  requireValue(typeof value.generation === 'number' && Number.isSafeInteger(value.generation)
+    && value.generation >= 1 && value.generation <= 3);
+  return { assignmentId: identifier(value.assignmentId), generation: value.generation, digest: digest(value.digest) };
+};
+const evidence = (valueArg: unknown): IRuntimeAssignmentTerminalEvidenceV1 => {
+  const value = record(valueArg, ['phase', 'sandboxId', 'containerId', 'imageConfigDigest', 'ipAddresses', 'exitCode']);
+  requireValue(value.phase === 'absent' || value.phase === 'stopped');
+  for (const field of ['sandboxId', 'containerId']) requireValue(value[field] === null
+    || (typeof value[field] === 'string' && /^[a-f0-9]{64}$/.test(value[field])));
+  requireValue(value.imageConfigDigest === null || (typeof value.imageConfigDigest === 'string'
+    && isSha256Digest(value.imageConfigDigest)));
+  requireValue(Array.isArray(value.ipAddresses) && value.ipAddresses.length === 0);
+  requireValue(value.exitCode === null || (typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode)
+    && value.exitCode >= -2_147_483_648 && value.exitCode <= 2_147_483_647));
+  requireValue(value.phase === 'absent'
+    ? value.sandboxId === null && value.containerId === null && value.imageConfigDigest === null && value.exitCode === null
+    : value.sandboxId !== null);
+  requireValue(value.containerId !== null || (value.imageConfigDigest === null && value.exitCode === null));
+  return value as unknown as IRuntimeAssignmentTerminalEvidenceV1;
+};
+
+/** Detached exact-schema assertion only; digest, journal provenance and authority remain unverified. */
+export const snapshotRuntimeAssignmentTerminalReceiptV1 = (valueArg: unknown): IRuntimeAssignmentTerminalReceiptV1 => safe(() => {
+  const value = record(capture(valueArg, runtimeAssignmentTerminalReceiptV1Contract.maximumReceiptCanonicalBytes),
+    ['schemaVersion', 'assignment', 'runAssignment', 'reporterSessionId', 'sequence', 'operation', 'previousReceiptDigest', 'digest']);
+  const assignment = reference(value.assignment);
+  const runAssignment = reference(value.runAssignment);
+  const operation = record(value.operation, ['id', 'action', 'bootId', 'status', 'evidence']);
+  const terminalEvidence = evidence(operation.evidence);
+  requireValue(value.schemaVersion === 1 && (value.sequence === 1 || value.sequence === 2)
+    && operation.status === 'completed' && assignment.generation === value.sequence + 1
+    && runAssignment.generation === 1 && runAssignment.assignmentId === assignment.assignmentId);
+  requireValue(typeof operation.bootId === 'string'
+    && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(operation.bootId));
+  requireValue(value.sequence === 1 ? operation.action === 'stop' && value.previousReceiptDigest === null
+    : operation.action === 'remove' && terminalEvidence.phase === 'absent' && value.previousReceiptDigest !== null);
+  return { schemaVersion: 1, assignment, runAssignment, reporterSessionId: identifier(value.reporterSessionId),
+    sequence: value.sequence, operation: { id: identifier(operation.id), action: operation.action as 'stop' | 'remove',
+      bootId: operation.bootId, status: 'completed', evidence: terminalEvidence },
+    previousReceiptDigest: value.previousReceiptDigest === null ? null : digest(value.previousReceiptDigest), digest: digest(value.digest) };
+});
+
+/** Bounded exact receipt history for synchronous persistence assertions; hashes remain unchecked. */
+export const snapshotRuntimeAssignmentTerminalReceiptHistoryV1 = (valueArg: unknown): IRuntimeAssignmentTerminalReceiptV1[] => safe(() => {
+  const values = capture(valueArg);
+  requireValue(Array.isArray(values) && values.length <= runtimeAssignmentTerminalReceiptV1Contract.maximumReceipts);
+  const receipts = values.map(snapshotRuntimeAssignmentTerminalReceiptV1);
+  for (const [index, receipt] of receipts.entries()) {
+    requireValue(receipt.sequence === index + 1);
+    if (index > 0) requireValue(receipt.previousReceiptDigest === receipts[0].digest
+      && canonical(receipt.runAssignment) === canonical(receipts[0].runAssignment)
+      && receipt.operation.id !== receipts[0].operation.id);
+  }
+  return receipts;
+});
+
+const assignments = (valueArg: unknown): IRuntimeAssignmentV1[] => {
+  const values = capture(valueArg);
+  requireValue(Array.isArray(values) && values.length >= 2
+    && values.length <= runtimeAssignmentTerminalReceiptV1Contract.maximumAssignmentRevisions);
+  return values.map(snapshotRuntimeAssignmentV1);
+};
+const checkAssignmentHistory = async (historyArg: IRuntimeAssignmentV1[]): Promise<void> => {
+  const run = historyArg[0];
+  const scope = { controller: run.controller, organizationId: run.organizationId,
+    nodeId: run.nodeId, runtimeNamespace: run.runtimeNamespace };
+  for (const [index, assignment] of historyArg.entries()) {
+    requireValue(assignment.generation === index + 1
+      && assignment.disposition === ['run', 'stop-preserve', 'remove-runtime-preserve-storage'][index]);
+    requireValue((await evaluateRuntimeAssignmentV1(assignment, index === 0 ? null : historyArg[index - 1], scope)).status === 'accept');
+  }
+};
+const computeSnapshotDigest = async (receiptArg: IRuntimeAssignmentTerminalReceiptV1): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = receiptArg;
+  return `sha256:${await createCanonicalJsonSha256Hex(canonical({
+    domain: runtimeAssignmentTerminalReceiptV1Contract.digestDomain, payload,
+  }), fail)}`;
+};
+/** Domain-separated exact body digest; captures before asynchronous hashing. */
+export const computeRuntimeAssignmentTerminalReceiptV1Digest = async (
+  valueArg: IRuntimeAssignmentTerminalReceiptV1,
+): Promise<TSha256Digest> => {
+  try { return await computeSnapshotDigest(snapshotRuntimeAssignmentTerminalReceiptV1(valueArg)); } catch { return fail(); }
+};
+const checkReceipt = async (
+  receiptArg: IRuntimeAssignmentTerminalReceiptV1, historyArg: IRuntimeAssignmentV1[],
+  previousArg: IRuntimeAssignmentTerminalReceiptV1 | null,
+): Promise<void> => {
+  requireValue(historyArg.length > receiptArg.sequence
+    && canonical(receiptArg.runAssignment) === canonical(getRuntimeAssignmentV1Reference(historyArg[0]))
+    && canonical(receiptArg.assignment) === canonical(getRuntimeAssignmentV1Reference(historyArg[receiptArg.sequence]))
+    && receiptArg.digest === await computeSnapshotDigest(receiptArg));
+  if (receiptArg.sequence === 1) requireValue(previousArg === null);
+  else {
+    requireValue(previousArg !== null && previousArg.sequence === 1);
+    await checkReceipt(previousArg, historyArg, null);
+    requireValue(receiptArg.previousReceiptDigest === previousArg.digest && receiptArg.operation.id !== previousArg.operation.id);
+  }
+};
+
+/** Full immutable run/stop/remove chain and exact prior stop receipt are mandatory for removal. */
+export const validateRuntimeAssignmentTerminalReceiptV1 = async (
+  valueArg: unknown, assignmentHistoryArg: unknown, previousReceiptArg: unknown,
+): Promise<string[]> => {
+  try {
+    const receipt = snapshotRuntimeAssignmentTerminalReceiptV1(valueArg);
+    const history = assignments(assignmentHistoryArg);
+    const previous = previousReceiptArg === null ? null : snapshotRuntimeAssignmentTerminalReceiptV1(previousReceiptArg);
+    await checkAssignmentHistory(history);
+    await checkReceipt(receipt, history, previous);
+    return [];
+  } catch { return [runtimeAssignmentTerminalReceiptV1Contract.error]; }
+};
+
+/**
+ * Pure bounded CAS decision. Persist under the owning transaction and current
+ * credential/peer fence. New acceptance also requires the exact global incumbent;
+ * only a previously persisted exact body can replay after the incumbent changes.
+ * The helper cannot prove either condition. Retain both bodies after removal.
+ */
+export const evaluateRuntimeAssignmentTerminalReceiptV1 = async (
+  valueArg: unknown, acceptedHistoryArg: unknown, assignmentHistoryArg: unknown,
+): Promise<TRuntimeAssignmentTerminalReceiptDecisionV1> => {
+  try {
+    const receipt = snapshotRuntimeAssignmentTerminalReceiptV1(valueArg);
+    const accepted = snapshotRuntimeAssignmentTerminalReceiptHistoryV1(acceptedHistoryArg);
+    const history = assignments(assignmentHistoryArg);
+    await checkAssignmentHistory(history);
+    for (const existing of accepted) await checkReceipt(existing, history, existing.sequence === 1 ? null : accepted[0]);
+    if (receipt.digest !== await computeSnapshotDigest(receipt)
+      || history.length <= receipt.sequence
+      || canonical(receipt.runAssignment) !== canonical(getRuntimeAssignmentV1Reference(history[0]))
+      || canonical(receipt.assignment) !== canonical(getRuntimeAssignmentV1Reference(history[receipt.sequence]))) {
+      return { status: 'reject', reason: 'invalid' };
+    }
+    const existing = accepted[receipt.sequence - 1];
+    if (existing) return canonical(existing) === canonical(receipt)
+      ? { status: 'replay', receipt: existing } : { status: 'reject', reason: 'conflict' };
+    if (receipt.sequence !== accepted.length + 1) return { status: 'reject', reason: 'sequence-gap' };
+    if (receipt.sequence === 2 && (receipt.previousReceiptDigest !== accepted[0].digest
+      || receipt.operation.id === accepted[0].operation.id)) return { status: 'reject', reason: 'predecessor-mismatch' };
+    return { status: 'accept', receipt };
+  } catch { return { status: 'reject', reason: 'invalid' }; }
+};
+
+export const snapshotReportRuntimeAssignmentTerminalReceiptRequestV1 = (
+  valueArg: unknown,
+): IReportRuntimeAssignmentTerminalReceiptRequestV1 => safe(() => {
+  const value = record(capture(valueArg), ['session', 'receipt']);
+  return { session: snapshotRuntimeSessionBindingV1(value.session), receipt: snapshotRuntimeAssignmentTerminalReceiptV1(value.receipt) };
+});
+export const snapshotReportRuntimeAssignmentTerminalReceiptResponseV1 = (
+  valueArg: unknown,
+): IReportRuntimeAssignmentTerminalReceiptResponseV1 => safe(() => {
+  const value = record(capture(valueArg), ['receipt', 'authorityUse']);
+  requireValue(value.authorityUse === 'current-session' || value.authorityUse === 'historical-recovery');
+  return { receipt: snapshotRuntimeAssignmentTerminalReceiptV1(value.receipt), authorityUse: value.authorityUse };
+});
+
+/**
+ * CURRENT physical session and immutable server-indexed reporter history are
+ * trusted owner inputs, never wire claims. The previous stop receipt must also
+ * come from the durable owner. This binds content; it does not authenticate,
+ * prove the local operation join, advance CAS, or admit a replacement.
+ */
+export const bindReportRuntimeAssignmentTerminalReceiptRequestV1 = async (
+  valueArg: unknown, assignmentHistoryArg: unknown, previousReceiptArg: unknown,
+  trustedSessionArg: unknown, reporterHistoryArg: unknown,
+): Promise<{ request: IReportRuntimeAssignmentTerminalReceiptRequestV1; authorityUse: TRuntimeObservationAuthorityUseV1 }> => {
+  try {
+    const request = snapshotReportRuntimeAssignmentTerminalReceiptRequestV1(valueArg);
+    const history = assignments(assignmentHistoryArg);
+    const previous = previousReceiptArg === null ? null : snapshotRuntimeAssignmentTerminalReceiptV1(previousReceiptArg);
+    requireValue(history.length > request.receipt.sequence);
+    const binding = bindRuntimeReporterSessionV1(request.session, request.receipt.reporterSessionId,
+      history[request.receipt.sequence], trustedSessionArg, reporterHistoryArg);
+    await checkAssignmentHistory(history);
+    await checkReceipt(request.receipt, history, previous);
+    return { request, authorityUse: binding.authorityUse };
+  } catch { return fail(); }
+};
+
+/** Exact ACK of the immutable outbox body; no rewritten session, operation or chain. */
+export const bindReportRuntimeAssignmentTerminalReceiptResponseV1 = (
+  valueArg: unknown, requestArg: unknown,
+): IReportRuntimeAssignmentTerminalReceiptResponseV1 => safe(() => {
+  const response = snapshotReportRuntimeAssignmentTerminalReceiptResponseV1(valueArg);
+  const request = snapshotReportRuntimeAssignmentTerminalReceiptRequestV1(requestArg);
+  requireValue(canonical(response.receipt) === canonical(request.receipt)
+    && response.authorityUse === (request.receipt.reporterSessionId === request.session.reporterSessionId
+      ? 'current-session' : 'historical-recovery'));
+  return response;
+});

package/ts/requests/image.ts

@@ -59,7 +59,8 @@ export interface IRequest_PushImageVersion extends plugins.typedrequestInterface
     identity: userInterfaces.IIdentity;
     imageId: string;
     versionString: string;
-    imageStream: plugins.typedrequestInterfaces.IVirtualStream;
+    /** Requester sends archive bytes; TypedHandler receives the opposite endpoint. */
+    imageStream: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
   };
   response: {
     allowed: boolean;
@@ -77,7 +78,8 @@ export interface IRequest_PullImageVersion extends plugins.typedrequestInterface
     versionString: string;
   };
   response: {
-    imageStream: plugins.typedrequestInterfaces.IVirtualStream;
+    /** Requester receives archive bytes; TypedHandler returns a sender endpoint. */
+    imageStream: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
   };
 }
 

package/ts/requests/runtimesession.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../plugins.js';
 import type * as data from '../data/runtimesession.js';
+import type * as terminal from '../data/runtimeterminalreceipt.js';
 
 /** WSS-only Pallet bootstrap. Derive physical peer/process/idempotency server-side. */
 export interface IReq_Pallet_Cloudly_RegisterPalletRuntimeSessionV1 extends plugins.typedrequestInterfaces.implementsTR<
@@ -31,6 +32,16 @@ export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservationV1 ext
   response: data.IReportRuntimeAssignmentObservationResponseV1;
 }
 
+/** Exact joined terminal-operation receipt; observations and boot changes cannot substitute. */
+export interface IReq_Pallet_Controller_ReportRuntimeAssignmentTerminalReceiptV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Pallet_Controller_ReportRuntimeAssignmentTerminalReceiptV1
+> {
+  method: 'reportRuntimeAssignmentTerminalReceiptV1';
+  request: terminal.IReportRuntimeAssignmentTerminalReceiptRequestV1;
+  response: terminal.IReportRuntimeAssignmentTerminalReceiptResponseV1;
+}
+
 /** Current-peer, exact current assignment authorization; response is secret material. */
 export interface IReq_Pallet_Controller_GetRuntimeRegistryCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,