@serve.zone/interfaces 30.0.0 → 30.2.0

package/ts/data/runtimesession.ts

@@ -61,6 +61,14 @@ export interface IReportRuntimeAssignmentObservationRequestV1 {
 
 export type TRuntimeObservationAuthorityUseV1 = 'current-session' | 'historical-recovery';
 
+/** Content comparison result only; all supplied authority must come from its trusted owner. */
+export interface IRuntimeReporterSessionBindingV1 {
+  session: IRuntimeSessionBindingV1;
+  assignment: IRuntimeAssignmentV1;
+  reporterHistory: IRuntimeSessionBindingV1;
+  authorityUse: TRuntimeObservationAuthorityUseV1;
+}
+
 export interface IReportRuntimeAssignmentObservationResponseV1 {
   /** Exact request body after a durable sequence/receipt transaction. */
   observation: IRuntimeAssignmentObservationV1;
@@ -343,6 +351,32 @@ export const bindApplyRuntimeAssignmentResponseV1 = (
   return response;
 });
 
+/**
+ * Synchronous detached content binding, not authentication. trustedSessionArg must
+ * be the CURRENT authenticated physical peer; reporterHistoryArg must be immutable
+ * server-indexed Pallet-purpose history. Never obtain either from request fields.
+ * The owning transaction must recheck current credential/peer authority. Assignment
+ * digest validation and report-specific authority remain the caller's responsibility.
+ */
+export const bindRuntimeReporterSessionV1 = (
+  sessionArg: unknown, reporterSessionIdArg: string, assignmentArg: unknown,
+  trustedSessionArg: unknown, reporterHistoryArg: unknown,
+): IRuntimeReporterSessionBindingV1 => safe(() => {
+  const incomingSession = snapshotRuntimeSessionBindingV1(sessionArg);
+  const reporterSessionId = identifier(reporterSessionIdArg);
+  const assignment = snapshotRuntimeAssignmentV1(capture(assignmentArg));
+  const trustedSession = snapshotRuntimeSessionBindingV1(trustedSessionArg);
+  const reporterHistory = snapshotRuntimeSessionBindingV1(reporterHistoryArg);
+  requireValue(sameSession(incomingSession, trustedSession) && matchesAssignment(trustedSession, assignment)
+    && reporterSessionId === reporterHistory.reporterSessionId && sameOwner(trustedSession, reporterHistory));
+  const current = sameSession(reporterHistory, trustedSession);
+  requireValue(current || (reporterHistory.reporterSessionId !== trustedSession.reporterSessionId
+    && reporterHistory.sessionEpoch < trustedSession.sessionEpoch
+    && reporterHistory.credentialGeneration <= trustedSession.credentialGeneration));
+  return { session: incomingSession, assignment, reporterHistory,
+    authorityUse: current ? 'current-session' : 'historical-recovery' };
+});
+
 /**
  * trustedSessionArg is the CURRENT authenticated physical peer. reporterHistoryArg
  * must be server-indexed immutable session history, obtained by the original
@@ -359,18 +393,10 @@ export const bindReportRuntimeAssignmentObservationRequestV1 = async (
 ): Promise<{ request: IReportRuntimeAssignmentObservationRequestV1; authorityUse: TRuntimeObservationAuthorityUseV1 }> => {
   try {
     const request = snapshotReportRuntimeAssignmentObservationRequestV1(valueArg);
-    const assignment = snapshotRuntimeAssignmentV1(capture(assignmentArg));
-    const trustedSession = snapshotRuntimeSessionBindingV1(trustedSessionArg);
-    const reporterHistory = snapshotRuntimeSessionBindingV1(reporterHistoryArg);
-    requireValue(sameSession(request.session, trustedSession) && matchesAssignment(trustedSession, assignment)
-      && request.observation.reporterSessionId === reporterHistory.reporterSessionId
-      && sameOwner(trustedSession, reporterHistory));
-    const current = sameSession(reporterHistory, trustedSession);
-    requireValue(current || (reporterHistory.reporterSessionId !== trustedSession.reporterSessionId
-      && reporterHistory.sessionEpoch < trustedSession.sessionEpoch
-      && reporterHistory.credentialGeneration <= trustedSession.credentialGeneration));
-    requireValue((await validateRuntimeAssignmentObservationV1(request.observation, assignment)).length === 0);
-    return { request, authorityUse: current ? 'current-session' : 'historical-recovery' };
+    const binding = bindRuntimeReporterSessionV1(request.session, request.observation.reporterSessionId,
+      assignmentArg, trustedSessionArg, reporterHistoryArg);
+    requireValue((await validateRuntimeAssignmentObservationV1(request.observation, binding.assignment)).length === 0);
+    return { request, authorityUse: binding.authorityUse };
   } catch { return fail(); }
 };
 

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/data/servicecredential.ts

@@ -0,0 +1,130 @@
+/** Workload permissions are independent of human membership and deployment grants. */
+export type TServiceMachineCapabilityV1 = 'platform:session';
+
+/** Exact existing-service authority. Never infer this grant from an API role. */
+export interface IServiceMachineGrantV1 {
+  organizationId: string;
+  serviceId: string;
+  capabilities: TServiceMachineCapabilityV1[];
+}
+
+/** Public metadata only. The bearer is delivered through the owning service's SecretSet. */
+export interface IServiceMachineCredentialMetadataV1 {
+  schemaVersion: 1;
+  credentialId: string;
+  userId: string;
+  grant: IServiceMachineGrantV1;
+  generation: number;
+  state: 'active' | 'revoked';
+  expiresAt: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Exact immutable encrypted delivery version; null after revocation. */
+  delivery: { secretId: string; secretVersionId: string } | null;
+}
+
+interface IServiceMachineCredentialMutationBaseV1 {
+  schemaVersion: 1;
+  organizationId: string;
+  serviceId: string;
+  /** Retain the complete request and this ID across retries. */
+  mutationId: string;
+}
+
+/** Creation is absent-only; rotation and revocation require the exact current generation. */
+export type TServiceMachineCredentialMutationV1 = IServiceMachineCredentialMutationBaseV1 & (
+  | {
+      operation: 'ensure';
+      expectedGeneration: null;
+      capabilities: TServiceMachineCapabilityV1[];
+      expiresAt: number;
+    }
+  | {
+      operation: 'rotate';
+      expectedGeneration: number;
+      capabilities: TServiceMachineCapabilityV1[];
+      expiresAt: number;
+    }
+  | { operation: 'revoke'; expectedGeneration: number }
+);
+
+export interface IServiceMachineCredentialMutationResultV1 {
+  /** Historical on replay; replay never restores revoked or superseded authority. */
+  credential: IServiceMachineCredentialMetadataV1;
+  replayed: boolean;
+}
+
+const fail = (): never => { throw new Error('Service credential contract rejected.'); };
+function requireValue(value: unknown): asserts value { if (!value) fail(); }
+const object = (value: unknown, keys: string[]): Record<string, unknown> => {
+  requireValue(value !== null && typeof value === 'object' && !Array.isArray(value));
+  requireValue(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+  const actual = Reflect.ownKeys(value);
+  requireValue(actual.length === keys.length && keys.every((key) => actual.includes(key)));
+  const copy: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    requireValue(descriptor && Object.hasOwn(descriptor, 'value') && descriptor.enumerable);
+    copy[key] = descriptor.value;
+  }
+  return copy;
+};
+const identifier = (value: unknown): string => {
+  requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+  return value;
+};
+const counter = (value: unknown): number => {
+  requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value < Number.MAX_SAFE_INTEGER);
+  return value;
+};
+const capabilities = (value: unknown): TServiceMachineCapabilityV1[] => {
+  requireValue(Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype);
+  const keys = Reflect.ownKeys(value);
+  requireValue(keys.length === 2 && keys.includes('length') && keys.includes('0'));
+  const entry = Object.getOwnPropertyDescriptor(value, '0');
+  requireValue(entry && Object.hasOwn(entry, 'value') && entry.enumerable && entry.value === 'platform:session');
+  return ['platform:session'];
+};
+const safe = <T>(operation: () => T): T => { try { return operation(); } catch { return fail(); } };
+
+/** Structural copy only; the backend must fence live service ownership and credential authority. */
+export const snapshotServiceMachineGrantV1 = (value: unknown): IServiceMachineGrantV1 => safe(() => {
+  const grant = object(value, ['organizationId', 'serviceId', 'capabilities']);
+  return { organizationId: identifier(grant.organizationId), serviceId: identifier(grant.serviceId),
+    capabilities: capabilities(grant.capabilities) };
+});
+
+export const snapshotServiceMachineCredentialMutationV1 = (value: unknown): TServiceMachineCredentialMutationV1 => safe(() => {
+  requireValue(value !== null && typeof value === 'object');
+  const operation = Object.getOwnPropertyDescriptor(value, 'operation')?.value;
+  requireValue(operation === 'ensure' || operation === 'rotate' || operation === 'revoke');
+  const request = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'mutationId', 'operation',
+    'expectedGeneration', ...(operation === 'revoke' ? [] : ['capabilities', 'expiresAt'])]);
+  requireValue(request.schemaVersion === 1);
+  const base = { schemaVersion: 1 as const, organizationId: identifier(request.organizationId),
+    serviceId: identifier(request.serviceId), mutationId: identifier(request.mutationId) };
+  if (operation === 'revoke') return { ...base, operation, expectedGeneration: counter(request.expectedGeneration) };
+  const material = { capabilities: capabilities(request.capabilities), expiresAt: counter(request.expiresAt) };
+  if (operation === 'ensure') {
+    requireValue(request.expectedGeneration === null);
+    return { ...base, ...material, operation, expectedGeneration: null };
+  }
+  return { ...base, ...material, operation, expectedGeneration: counter(request.expectedGeneration) };
+});
+
+export const snapshotServiceMachineCredentialMetadataV1 = (value: unknown): IServiceMachineCredentialMetadataV1 => safe(() => {
+  const metadata = object(value, ['schemaVersion', 'credentialId', 'userId', 'grant', 'generation', 'state',
+    'expiresAt', 'createdAt', 'updatedAt', 'delivery']);
+  requireValue(metadata.schemaVersion === 1 && (metadata.state === 'active' || metadata.state === 'revoked'));
+  const createdAt = counter(metadata.createdAt);
+  const updatedAt = counter(metadata.updatedAt);
+  requireValue(updatedAt >= createdAt);
+  let delivery: IServiceMachineCredentialMetadataV1['delivery'] = null;
+  if (metadata.state === 'active') {
+    const version = object(metadata.delivery, ['secretId', 'secretVersionId']);
+    delivery = { secretId: identifier(version.secretId), secretVersionId: identifier(version.secretVersionId) };
+  } else requireValue(metadata.delivery === null);
+  return { schemaVersion: 1, credentialId: identifier(metadata.credentialId), userId: identifier(metadata.userId),
+    grant: snapshotServiceMachineGrantV1(metadata.grant), generation: counter(metadata.generation),
+    state: metadata.state, expiresAt: counter(metadata.expiresAt), createdAt, updatedAt, delivery };
+});

package/ts/requests/admin.ts

@@ -1,5 +1,30 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
+import type {
+  IServiceMachineCredentialMetadataV1, IServiceMachineCredentialMutationResultV1,
+  TServiceMachineCredentialMutationV1,
+} from '../data/servicecredential.js';
+
+export interface IReq_Admin_GetServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredentialV1
+> {
+  method: 'getServiceMachineCredentialV1';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { credential: IServiceMachineCredentialMetadataV1 | null };
+}
+
+/**
+ * The backend authorizes the exact service and mutates hashed credential authority,
+ * encrypted SecretSet delivery and the replay receipt in one fenced transaction.
+ * No bearer is returned. Existing legacy deployment/cluster credentials are separate.
+ */
+export interface IReq_Admin_MutateServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateServiceMachineCredentialV1
+> {
+  method: 'mutateServiceMachineCredentialV1';
+  request: { identity: IIdentityCredential; mutation: TServiceMachineCredentialMutationV1 };
+  response: IServiceMachineCredentialMutationResultV1;
+}
 
 /** Backend-owned human credential metadata; never includes a password verifier. */
 export interface IHumanCredentialMetadata {

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,