@serve.zone/interfaces 32.35.0 → 32.36.1

package/ts/data/runtimeassignmentexec.ts

@@ -0,0 +1,271 @@
+import type { IRuntimeAssignment, IRuntimeAssignmentReference } from './runtimeassignment.js';
+import { getRuntimeAssignmentReference, snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import {
+  captureNetwork, networkCounter, networkDigest, networkEqual, networkId, networkRecord, requireNetwork,
+} from '../private/networkcontract.js';
+
+/** A terminal's size in character cells. */
+export interface IRuntimeTerminalSize {
+  columns: number;
+  rows: number;
+}
+
+/**
+ * A controller's request to run one command inside one running attempt's container.
+ *
+ * `command` is the argument vector the runtime executes directly: no shell parses it unless its
+ * first element names one. With `tty` the process runs on a terminal of `terminalSize`, which is
+ * stated exactly then; its output arrives on one stream. Without it stdout and stderr arrive on
+ * separate streams. Standard input is the optional stream the TypedRequest carries beside this
+ * body; its end is the process's end of input.
+ */
+export interface IOpenRuntimeAssignmentExecRequest {
+  session: IRuntimeSessionBinding;
+  /** The exact current revision of a `run` assignment on this node. */
+  assignment: IRuntimeAssignmentReference;
+  command: string[];
+  tty: boolean;
+  terminalSize: IRuntimeTerminalSize | null;
+}
+
+/**
+ * The node's answer once the process runs. `execId` names the session in later requests;
+ * `idleTimeoutMs` is how long the session may carry no byte in either direction before the node
+ * ends it.
+ */
+export interface IOpenRuntimeAssignmentExecResponse {
+  execId: string;
+  assignment: IRuntimeAssignmentReference;
+  tty: boolean;
+  idleTimeoutMs: number;
+}
+
+/** A new terminal size for a `tty` session. */
+export interface IResizeRuntimeAssignmentExecRequest {
+  session: IRuntimeSessionBinding;
+  execId: string;
+  terminalSize: IRuntimeTerminalSize;
+}
+
+export interface IResizeRuntimeAssignmentExecResponse {
+  execId: string;
+}
+
+/** Ends a session and releases its slot, whether or not its process has exited. */
+export interface ICloseRuntimeAssignmentExecRequest {
+  session: IRuntimeSessionBinding;
+  execId: string;
+}
+
+/**
+ * Why the node ended a process before it exited: `closed` by this request, `idle-timeout` after
+ * `idleTimeoutMs` without a byte, `container-stopped` because its container stopped.
+ */
+export type TRuntimeAssignmentExecTermination = 'closed' | 'idle-timeout' | 'container-stopped';
+
+/**
+ * How the session ended. `exited` carries the process's `exitCode`, 128 plus the signal number
+ * for a process a signal ended; `terminated` states why the node ended it and carries no code.
+ */
+export interface ICloseRuntimeAssignmentExecResponse {
+  execId: string;
+  outcome: 'exited' | 'terminated';
+  exitCode: number | null;
+  termination: TRuntimeAssignmentExecTermination | null;
+}
+
+/**
+ * Exec runs only for a controller on the node's own host (`controller.kind: 'onebox'`, which only a
+ * local controller binding carries), and only on the connection that holds its session. A session
+ * lives until it is closed, or until the node ends it: after `idleTimeoutMs` without a byte, when
+ * its container stops, or when the controller session it was opened under ends, in which case its
+ * `execId` is gone with it. An ended session keeps its slot and its outcome until it is closed.
+ */
+export const runtimeAssignmentExecContract = Object.freeze({
+  error: 'Runtime assignment exec contract rejected.',
+  controllerKind: 'onebox',
+  /** Open sessions per node, ended ones not yet closed included; one more is refused. */
+  maximumSessions: 4,
+  idleTimeoutMs: 900_000,
+  maximumCommandArguments: 256,
+  /** The UTF-8 bytes of every argument together. */
+  maximumCommandBytes: 65_536,
+  /** The largest terminal dimension, the width of the runtime's own size field. */
+  maximumTerminalDimension: 65_535,
+  maximumExitCode: 255,
+} as const);
+
+const fail = (): never => { throw new Error(runtimeAssignmentExecContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+const encoder = new TextEncoder();
+const terminations = ['closed', 'idle-timeout', 'container-stopped'] as const;
+
+const referenceOf = (valueArg: unknown): IRuntimeAssignmentReference => {
+  const value = networkRecord(valueArg, ['assignmentId', 'generation', 'digest']);
+  return {
+    assignmentId: networkId(value.assignmentId), generation: networkCounter(value.generation),
+    digest: networkDigest(value.digest),
+  };
+};
+const terminalSizeOf = (valueArg: unknown): IRuntimeTerminalSize => {
+  const value = networkRecord(valueArg, ['columns', 'rows']);
+  return {
+    columns: networkCounter(value.columns, runtimeAssignmentExecContract.maximumTerminalDimension),
+    rows: networkCounter(value.rows, runtimeAssignmentExecContract.maximumTerminalDimension),
+  };
+};
+const commandOf = (valueArg: unknown): string[] => {
+  requireNetwork(Array.isArray(valueArg) && valueArg.length > 0
+    && valueArg.length <= runtimeAssignmentExecContract.maximumCommandArguments);
+  let bytes = 0;
+  const command = (valueArg as unknown[]).map((argumentArg) => {
+    requireNetwork(typeof argumentArg === 'string' && !argumentArg.includes('\0'));
+    bytes += encoder.encode(argumentArg).byteLength;
+    return argumentArg;
+  });
+  requireNetwork(command[0].length > 0 && bytes <= runtimeAssignmentExecContract.maximumCommandBytes);
+  return command;
+};
+
+export const snapshotOpenRuntimeAssignmentExecRequest = (
+  valueArg: unknown,
+): IOpenRuntimeAssignmentExecRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'assignment', 'command', 'tty', 'terminalSize']);
+  requireNetwork(typeof value.tty === 'boolean' && (value.tty === (value.terminalSize !== null)));
+  return {
+    session: snapshotRuntimeSessionBinding(value.session), assignment: referenceOf(value.assignment),
+    command: commandOf(value.command), tty: value.tty,
+    terminalSize: value.terminalSize === null ? null : terminalSizeOf(value.terminalSize),
+  };
+});
+
+export const snapshotOpenRuntimeAssignmentExecResponse = (
+  valueArg: unknown,
+): IOpenRuntimeAssignmentExecResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['execId', 'assignment', 'tty', 'idleTimeoutMs']);
+  requireNetwork(typeof value.tty === 'boolean'
+    && value.idleTimeoutMs === runtimeAssignmentExecContract.idleTimeoutMs);
+  return {
+    execId: networkId(value.execId), assignment: referenceOf(value.assignment), tty: value.tty,
+    idleTimeoutMs: runtimeAssignmentExecContract.idleTimeoutMs,
+  };
+});
+
+export const snapshotResizeRuntimeAssignmentExecRequest = (
+  valueArg: unknown,
+): IResizeRuntimeAssignmentExecRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'execId', 'terminalSize']);
+  return {
+    session: snapshotRuntimeSessionBinding(value.session), execId: networkId(value.execId),
+    terminalSize: terminalSizeOf(value.terminalSize),
+  };
+});
+
+export const snapshotResizeRuntimeAssignmentExecResponse = (
+  valueArg: unknown,
+): IResizeRuntimeAssignmentExecResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['execId']);
+  return { execId: networkId(value.execId) };
+});
+
+export const snapshotCloseRuntimeAssignmentExecRequest = (
+  valueArg: unknown,
+): ICloseRuntimeAssignmentExecRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'execId']);
+  return { session: snapshotRuntimeSessionBinding(value.session), execId: networkId(value.execId) };
+});
+
+export const snapshotCloseRuntimeAssignmentExecResponse = (
+  valueArg: unknown,
+): ICloseRuntimeAssignmentExecResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['execId', 'outcome', 'exitCode', 'termination']);
+  const execId = networkId(value.execId);
+  if (value.outcome === 'exited') {
+    requireNetwork(typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode)
+      && value.exitCode >= 0 && !Object.is(value.exitCode, -0)
+      && value.exitCode <= runtimeAssignmentExecContract.maximumExitCode && value.termination === null);
+    return { execId, outcome: 'exited', exitCode: value.exitCode, termination: null };
+  }
+  requireNetwork(value.outcome === 'terminated' && value.exitCode === null
+    && (terminations as readonly unknown[]).includes(value.termination));
+  return {
+    execId, outcome: 'terminated', exitCode: null,
+    termination: value.termination as TRuntimeAssignmentExecTermination,
+  };
+});
+
+/** Exec is a local controller's alone; `trustedSessionArg` decides, never a request field. */
+const requireLocalSession = (requestSessionArg: IRuntimeSessionBinding, trustedSessionArg: unknown): void => {
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  safe(() => requireNetwork(networkEqual(requestSessionArg, trustedSession)
+    && trustedSession.controller.kind === runtimeAssignmentExecContract.controllerKind));
+};
+
+/**
+ * Node-side content binding, not authentication. `trustedSessionArg` is the node's CURRENT
+ * session, the request must have arrived on that session's own connection, and that session must
+ * be a local controller's. `assignmentArg` is the node's current admitted revision of the named
+ * assignment: the request must name exactly it, it must be a `run` assignment, and it must belong
+ * to the session's controller, node and runtime namespace. Whether its container runs is the
+ * node's own check.
+ */
+export const bindOpenRuntimeAssignmentExecRequest = async (
+  valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IOpenRuntimeAssignmentExecRequest; assignment: IRuntimeAssignment }> => {
+  const request = snapshotOpenRuntimeAssignmentExecRequest(valueArg);
+  requireLocalSession(request.session, trustedSessionArg);
+  const assignment = safe(() => snapshotRuntimeAssignment(assignmentArg));
+  if ((await validateRuntimeAssignment(assignment)).length) fail();
+  safe(() => requireNetwork(assignment.disposition === 'run'
+    && networkEqual(assignment.controller, request.session.controller)
+    && assignment.nodeId === request.session.nodeId
+    && assignment.runtimeNamespace === request.session.runtimeNamespace
+    && networkEqual(request.assignment, getRuntimeAssignmentReference(assignment))));
+  return { request, assignment };
+};
+
+/** Matches an opened session to the request: the same assignment revision and terminal mode. */
+export const bindOpenRuntimeAssignmentExecResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IOpenRuntimeAssignmentExecResponse => safe(() => {
+  const response = snapshotOpenRuntimeAssignmentExecResponse(valueArg);
+  const request = snapshotOpenRuntimeAssignmentExecRequest(requestArg);
+  requireNetwork(networkEqual(response.assignment, request.assignment) && response.tty === request.tty);
+  return response;
+});
+
+/** Node-side content binding of a resize; which sessions exist and are `tty` is the node's check. */
+export const bindResizeRuntimeAssignmentExecRequest = (
+  valueArg: unknown, trustedSessionArg: unknown,
+): IResizeRuntimeAssignmentExecRequest => {
+  const request = snapshotResizeRuntimeAssignmentExecRequest(valueArg);
+  requireLocalSession(request.session, trustedSessionArg);
+  return request;
+};
+
+export const bindResizeRuntimeAssignmentExecResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IResizeRuntimeAssignmentExecResponse => safe(() => {
+  const response = snapshotResizeRuntimeAssignmentExecResponse(valueArg);
+  requireNetwork(response.execId === snapshotResizeRuntimeAssignmentExecRequest(requestArg).execId);
+  return response;
+});
+
+/** Node-side content binding of a close; which sessions exist is the node's check. */
+export const bindCloseRuntimeAssignmentExecRequest = (
+  valueArg: unknown, trustedSessionArg: unknown,
+): ICloseRuntimeAssignmentExecRequest => {
+  const request = snapshotCloseRuntimeAssignmentExecRequest(valueArg);
+  requireLocalSession(request.session, trustedSessionArg);
+  return request;
+};
+
+export const bindCloseRuntimeAssignmentExecResponse = (
+  valueArg: unknown, requestArg: unknown,
+): ICloseRuntimeAssignmentExecResponse => safe(() => {
+  const response = snapshotCloseRuntimeAssignmentExecResponse(valueArg);
+  requireNetwork(response.execId === snapshotCloseRuntimeAssignmentExecRequest(requestArg).execId);
+  return response;
+});

package/ts/data/runtimeassignmentlogs.ts

@@ -0,0 +1,249 @@
+import type { IRuntimeAssignment } from './runtimeassignment.js';
+import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import type { IRuntimeConfigLogPolicy } from './runtimeconfig.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import {
+  captureNetwork, networkCounter, networkEqual, networkId, networkList, networkRecord, requireNetwork,
+} from '../private/networkcontract.js';
+import { isRuntimeLogPolicy } from '../private/runtimepolicy.js';
+
+/** The container output a log line was written to. */
+export type TRuntimeAssignmentLogStream = 'stdout' | 'stderr';
+
+/**
+ * One piece of one line a container wrote, as the runtime captured it.
+ *
+ * `text` holds no line terminator and no `\n`; the node decodes the captured bytes as UTF-8 and
+ * replaces an invalid sequence with U+FFFD. A line longer than one entry travels as consecutive
+ * entries of the same stream: every piece but the last states `partial: true`, and the receiver
+ * joins them. The joined line is at most the config's `logs.maximumLineBytes` UTF-8 bytes; the node
+ * cuts a longer one there and follows its last piece with a `line-cut` loss of the same stream.
+ */
+export interface IRuntimeAssignmentLogLine {
+  kind: 'line';
+  stream: TRuntimeAssignmentLogStream;
+  /** When the runtime captured the piece, in nanoseconds since the Unix epoch, as decimal digits. */
+  timestampNs: string;
+  text: string;
+  /** The line continues in the next `line` entry of the same stream. */
+  partial: boolean;
+}
+
+/**
+ * Why output did not reach the controller.
+ *
+ * - `buffer-overflow`: the node's buffer held `logs.maximumBufferedBytes` unacknowledged bytes and
+ *   the oldest were dropped to keep capturing;
+ * - `line-cut`: the rest of a line beyond `logs.maximumLineBytes`;
+ * - `capture-restart`: the node's capture restarted without its buffer, for example after a reboot
+ *   emptied its disposable capture directory; how much was lost is unknown;
+ * - `not-captured`: the container was started without output capture, so none of its output is
+ *   available; how much there was is unknown.
+ */
+export type TRuntimeAssignmentLogLossReason = 'buffer-overflow' | 'line-cut' | 'capture-restart' | 'not-captured';
+
+/**
+ * Evidence of output that was lost, in the position of the stream where it was lost.
+ *
+ * `bytes` and `lines` count exactly what was dropped; both are `null` for `capture-restart` and
+ * `not-captured`, whose extent the node cannot know, and both are stated for the other reasons.
+ * A `line-cut` counts the cut bytes and no line, because the line itself was delivered; it names
+ * the stream of that line. A `buffer-overflow` counts the dropped bytes and the whole lines among
+ * them, and names a stream only when every dropped byte came from it.
+ */
+export interface IRuntimeAssignmentLogLoss {
+  kind: 'lost';
+  reason: TRuntimeAssignmentLogLossReason;
+  stream: TRuntimeAssignmentLogStream | null;
+  /** When the node detected the loss, in nanoseconds since the Unix epoch, as decimal digits. */
+  timestampNs: string;
+  bytes: number | null;
+  lines: number | null;
+}
+
+export type TRuntimeAssignmentLogEntry = IRuntimeAssignmentLogLine | IRuntimeAssignmentLogLoss;
+
+/**
+ * One delivery of one attempt's captured output, in capture order.
+ *
+ * `captureId` names one capture of the attempt on its node: the node starts a new capture, with a
+ * new id and `sequence` 1, whenever it cannot continue the previous one, and opens it with a
+ * `capture-restart` loss. Within a capture `sequence` counts batches from 1 without gaps, and the
+ * node sends the next batch only after the controller acknowledged the previous one, so a batch is
+ * the one unit of retry. `final` states that no batch follows in this capture: the container is gone
+ * and its output is drained. Only a final batch may be empty.
+ */
+export interface IRuntimeAssignmentLogBatch {
+  assignmentId: string;
+  attemptId: string;
+  captureId: string;
+  sequence: number;
+  entries: TRuntimeAssignmentLogEntry[];
+  final: boolean;
+}
+
+/** Pallet push over its current authenticated session. */
+export interface IReportRuntimeAssignmentLogsRequest {
+  session: IRuntimeSessionBinding;
+  batch: IRuntimeAssignmentLogBatch;
+}
+
+/**
+ * The controller holds the batch durably. `replay` answers a batch it already holds, which it does
+ * not store again. It never refuses a batch for a gap in `sequence`: the node discards only what
+ * was acknowledged, so a missing batch can only be the controller's own loss, which it records.
+ */
+export interface IReportRuntimeAssignmentLogsResponse {
+  status: 'accepted' | 'replay';
+  assignmentId: string;
+  captureId: string;
+  sequence: number;
+}
+
+export const runtimeAssignmentLogContract = Object.freeze({
+  error: 'Runtime assignment log contract rejected.',
+  /** Pallet pushes; the controller persists metadata and payloads and acknowledges by sequence. */
+  delivery: 'node-pushes-controller-acknowledges-each-batch',
+  /** The most entries in one batch. */
+  maximumEntriesPerBatch: 1024,
+  /** The most UTF-8 bytes of `text` in one entry; a longer line travels as `partial` pieces. */
+  maximumEntryTextBytes: 65_536,
+  /**
+   * The canonical JSON of a whole report is at most one mebibyte, the bound every runtime network
+   * contract captures with; the node closes a batch before the next entry would cross it.
+   */
+  maximumReportCanonicalBytes: 1_048_576,
+} as const);
+
+const fail = (): never => { throw new Error(runtimeAssignmentLogContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+const encoder = new TextEncoder();
+const streams = ['stdout', 'stderr'] as const;
+const lossReasons = ['buffer-overflow', 'line-cut', 'capture-restart', 'not-captured'] as const;
+const statuses = ['accepted', 'replay'] as const;
+
+const literalOf = <TLiteral extends string>(valueArg: unknown, allowedArg: readonly TLiteral[]): TLiteral => {
+  requireNetwork((allowedArg as readonly unknown[]).includes(valueArg));
+  return valueArg as TLiteral;
+};
+/** Nanoseconds since the Unix epoch as canonical decimal digits: no sign, no leading zero. */
+const timestampOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && /^[1-9][0-9]{0,19}$/.test(valueArg)
+    && BigInt(valueArg) <= 18_446_744_073_709_551_615n);
+  return valueArg;
+};
+const countOf = (valueArg: unknown): number => {
+  requireNetwork(typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0
+    && !Object.is(valueArg, -0));
+  return valueArg;
+};
+
+const lineOf = (valueArg: unknown): IRuntimeAssignmentLogLine => {
+  const value = networkRecord(valueArg, ['kind', 'stream', 'timestampNs', 'text', 'partial']);
+  requireNetwork(value.kind === 'line' && typeof value.text === 'string' && !value.text.includes('\n')
+    && encoder.encode(value.text).byteLength <= runtimeAssignmentLogContract.maximumEntryTextBytes
+    && typeof value.partial === 'boolean');
+  return {
+    kind: 'line', stream: literalOf(value.stream, streams), timestampNs: timestampOf(value.timestampNs),
+    text: value.text, partial: value.partial,
+  };
+};
+
+const lossOf = (valueArg: unknown): IRuntimeAssignmentLogLoss => {
+  const value = networkRecord(valueArg, ['kind', 'reason', 'stream', 'timestampNs', 'bytes', 'lines']);
+  requireNetwork(value.kind === 'lost');
+  const reason = literalOf(value.reason, lossReasons);
+  const stream = value.stream === null ? null : literalOf(value.stream, streams);
+  const unknownExtent = reason === 'capture-restart' || reason === 'not-captured';
+  if (unknownExtent) {
+    requireNetwork(value.bytes === null && value.lines === null && stream === null);
+    return { kind: 'lost', reason, stream, timestampNs: timestampOf(value.timestampNs), bytes: null, lines: null };
+  }
+  const bytes = networkCounter(value.bytes);
+  const lines = countOf(value.lines);
+  requireNetwork(reason !== 'line-cut' || (stream !== null && lines === 0));
+  return { kind: 'lost', reason, stream, timestampNs: timestampOf(value.timestampNs), bytes, lines };
+};
+
+const entryOf = (valueArg: unknown): TRuntimeAssignmentLogEntry => {
+  requireNetwork(valueArg !== null && typeof valueArg === 'object');
+  return (valueArg as Record<string, unknown>).kind === 'lost' ? lossOf(valueArg) : lineOf(valueArg);
+};
+
+const batchOf = (valueArg: unknown): IRuntimeAssignmentLogBatch => {
+  const value = networkRecord(valueArg, ['assignmentId', 'attemptId', 'captureId', 'sequence', 'entries', 'final']);
+  const entries = networkList(value.entries, runtimeAssignmentLogContract.maximumEntriesPerBatch, entryOf);
+  requireNetwork(typeof value.final === 'boolean' && (entries.length > 0 || value.final));
+  return {
+    assignmentId: networkId(value.assignmentId), attemptId: networkId(value.attemptId),
+    captureId: networkId(value.captureId), sequence: networkCounter(value.sequence), entries, final: value.final,
+  };
+};
+
+/** Detached exact-schema snapshot of one batch, bounded like a whole report. */
+export const snapshotRuntimeAssignmentLogBatch = (valueArg: unknown): IRuntimeAssignmentLogBatch =>
+  safe(() => batchOf(captureNetwork(valueArg)));
+
+export const snapshotReportRuntimeAssignmentLogsRequest = (
+  valueArg: unknown,
+): IReportRuntimeAssignmentLogsRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'batch']);
+  return { session: snapshotRuntimeSessionBinding(value.session), batch: batchOf(value.batch) };
+});
+
+export const snapshotReportRuntimeAssignmentLogsResponse = (
+  valueArg: unknown,
+): IReportRuntimeAssignmentLogsResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['status', 'assignmentId', 'captureId', 'sequence']);
+  return {
+    status: literalOf(value.status, statuses), assignmentId: networkId(value.assignmentId),
+    captureId: networkId(value.captureId), sequence: networkCounter(value.sequence),
+  };
+});
+
+/**
+ * Controller-side content binding, not authentication. `trustedSessionArg` is the controller's
+ * CURRENT session with the node the report arrived on, never read from the request. `assignmentArg`
+ * is the controller's own record of the batch's assignment, any generation of it, and
+ * `logPolicyArg` the `logs` policy of the config it runs with. The request's session must equal the
+ * trusted one, the assignment must be this node's and carry the batch's attempt, and every line
+ * the batch holds, its pieces joined, must fit the policy's `maximumLineBytes`. A line whose first
+ * pieces travelled in an earlier batch is judged by the pieces this batch holds.
+ */
+export const bindReportRuntimeAssignmentLogsRequest = async (
+  valueArg: unknown, assignmentArg: unknown, logPolicyArg: IRuntimeConfigLogPolicy, trustedSessionArg: unknown,
+): Promise<{ request: IReportRuntimeAssignmentLogsRequest; assignment: IRuntimeAssignment }> => {
+  const request = snapshotReportRuntimeAssignmentLogsRequest(valueArg);
+  const assignment = safe(() => snapshotRuntimeAssignment(assignmentArg));
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  if ((await validateRuntimeAssignment(assignment)).length) fail();
+  safe(() => {
+    requireNetwork(isRuntimeLogPolicy(logPolicyArg));
+    requireNetwork(networkEqual(request.session, trustedSession)
+      && networkEqual(assignment.controller, trustedSession.controller)
+      && assignment.nodeId === trustedSession.nodeId
+      && assignment.runtimeNamespace === trustedSession.runtimeNamespace
+      && assignment.assignmentId === request.batch.assignmentId
+      && assignment.attemptId === request.batch.attemptId);
+    const joined: Record<TRuntimeAssignmentLogStream, number> = { stdout: 0, stderr: 0 };
+    for (const entry of request.batch.entries) {
+      if (entry.kind !== 'line') continue;
+      joined[entry.stream] += encoder.encode(entry.text).byteLength;
+      requireNetwork(joined[entry.stream] <= logPolicyArg.maximumLineBytes);
+      if (!entry.partial) joined[entry.stream] = 0;
+    }
+  });
+  return { request, assignment };
+};
+
+/** Matches an acknowledgement to the exact batch that was sent. */
+export const bindReportRuntimeAssignmentLogsResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IReportRuntimeAssignmentLogsResponse => safe(() => {
+  const response = snapshotReportRuntimeAssignmentLogsResponse(valueArg);
+  const { batch } = snapshotReportRuntimeAssignmentLogsRequest(requestArg);
+  requireNetwork(response.assignmentId === batch.assignmentId && response.captureId === batch.captureId
+    && response.sequence === batch.sequence);
+  return response;
+});

package/ts/data/runtimeassignmentstats.ts

@@ -0,0 +1,149 @@
+import type { IRuntimeAssignment, IRuntimeAssignmentReference } from './runtimeassignment.js';
+import { getRuntimeAssignmentReference, snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import {
+  captureNetwork, networkCounter, networkDigest, networkEqual, networkId, networkRecord, requireNetwork,
+} from '../private/networkcontract.js';
+
+/** Bytes the workload's network namespace received and sent since the sandbox started. */
+export interface IRuntimeAssignmentNetworkStats {
+  receivedBytes: number;
+  transmittedBytes: number;
+}
+
+/**
+ * One resource sample of one running attempt, as the runtime reports it.
+ *
+ * `cpuUsageCoreNanoseconds` is cumulative CPU time across every core since the container started,
+ * as decimal digits because it outgrows a JSON number; a reader derives utilisation from two
+ * samples and their `timestampNs`. `memoryLimitBytes` is the limit the node enforces, the sealed
+ * config's `memoryBytes`. `network` is `null` when the runtime reports no interface of the
+ * sandbox, and `writableLayerBytes` is `null` when it reports no usage of the container's writable
+ * layer.
+ */
+export interface IRuntimeAssignmentStatsSample {
+  /** When the runtime took the sample, in nanoseconds since the Unix epoch, as decimal digits. */
+  timestampNs: string;
+  cpuUsageCoreNanoseconds: string;
+  memoryWorkingSetBytes: number;
+  memoryLimitBytes: number;
+  network: IRuntimeAssignmentNetworkStats | null;
+  writableLayerBytes: number | null;
+}
+
+/** Controller read over the node's current authenticated session. */
+export interface IReadRuntimeAssignmentStatsRequest {
+  session: IRuntimeSessionBinding;
+  /** The exact current revision of an assignment on this node. */
+  assignment: IRuntimeAssignmentReference;
+}
+
+/**
+ * `sampled` carries one sample; `not-running` states that the attempt has no running container to
+ * sample, and carries none.
+ */
+export interface IReadRuntimeAssignmentStatsResponse {
+  status: 'sampled' | 'not-running';
+  assignment: IRuntimeAssignmentReference;
+  sample: IRuntimeAssignmentStatsSample | null;
+}
+
+export const runtimeAssignmentStatsContract = Object.freeze({
+  error: 'Runtime assignment stats contract rejected.',
+  /** The node answers one read per assignment at a time and refuses a concurrent one. */
+  concurrency: 'one-read-per-assignment',
+} as const);
+
+const fail = (): never => { throw new Error(runtimeAssignmentStatsContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+/** An unsigned 64-bit counter as canonical decimal digits: no sign, no leading zero. */
+const decimalOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && /^(0|[1-9][0-9]{0,19})$/.test(valueArg)
+    && BigInt(valueArg) <= 18_446_744_073_709_551_615n);
+  return valueArg;
+};
+const bytesOf = (valueArg: unknown): number => {
+  requireNetwork(typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0
+    && !Object.is(valueArg, -0));
+  return valueArg;
+};
+const referenceOf = (valueArg: unknown): IRuntimeAssignmentReference => {
+  const value = networkRecord(valueArg, ['assignmentId', 'generation', 'digest']);
+  return {
+    assignmentId: networkId(value.assignmentId), generation: networkCounter(value.generation),
+    digest: networkDigest(value.digest),
+  };
+};
+
+const sampleOf = (valueArg: unknown): IRuntimeAssignmentStatsSample => {
+  const value = networkRecord(valueArg, ['timestampNs', 'cpuUsageCoreNanoseconds', 'memoryWorkingSetBytes',
+    'memoryLimitBytes', 'network', 'writableLayerBytes']);
+  const timestampNs = decimalOf(value.timestampNs);
+  requireNetwork(timestampNs !== '0');
+  let network: IRuntimeAssignmentNetworkStats | null = null;
+  if (value.network !== null) {
+    const item = networkRecord(value.network, ['receivedBytes', 'transmittedBytes']);
+    network = { receivedBytes: bytesOf(item.receivedBytes), transmittedBytes: bytesOf(item.transmittedBytes) };
+  }
+  return {
+    timestampNs,
+    cpuUsageCoreNanoseconds: decimalOf(value.cpuUsageCoreNanoseconds),
+    memoryWorkingSetBytes: bytesOf(value.memoryWorkingSetBytes),
+    memoryLimitBytes: networkCounter(value.memoryLimitBytes),
+    network,
+    writableLayerBytes: value.writableLayerBytes === null ? null : bytesOf(value.writableLayerBytes),
+  };
+};
+
+export const snapshotReadRuntimeAssignmentStatsRequest = (
+  valueArg: unknown,
+): IReadRuntimeAssignmentStatsRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'assignment']);
+  return { session: snapshotRuntimeSessionBinding(value.session), assignment: referenceOf(value.assignment) };
+});
+
+export const snapshotReadRuntimeAssignmentStatsResponse = (
+  valueArg: unknown,
+): IReadRuntimeAssignmentStatsResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['status', 'assignment', 'sample']);
+  requireNetwork((value.status === 'sampled' && value.sample !== null)
+    || (value.status === 'not-running' && value.sample === null));
+  return {
+    status: value.status as IReadRuntimeAssignmentStatsResponse['status'],
+    assignment: referenceOf(value.assignment),
+    sample: value.sample === null ? null : sampleOf(value.sample),
+  };
+});
+
+/**
+ * Node-side content binding, not authentication. `trustedSessionArg` is the node's CURRENT
+ * session, and the request must have arrived on that session's own connection. `assignmentArg` is
+ * the node's current admitted revision of the named assignment: the request must name exactly it,
+ * and it must belong to the session's controller, node and runtime namespace.
+ */
+export const bindReadRuntimeAssignmentStatsRequest = async (
+  valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IReadRuntimeAssignmentStatsRequest; assignment: IRuntimeAssignment }> => {
+  const request = snapshotReadRuntimeAssignmentStatsRequest(valueArg);
+  const assignment = safe(() => snapshotRuntimeAssignment(assignmentArg));
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  if ((await validateRuntimeAssignment(assignment)).length) fail();
+  safe(() => requireNetwork(networkEqual(request.session, trustedSession)
+    && networkEqual(assignment.controller, trustedSession.controller)
+    && assignment.nodeId === trustedSession.nodeId
+    && assignment.runtimeNamespace === trustedSession.runtimeNamespace
+    && networkEqual(request.assignment, getRuntimeAssignmentReference(assignment))));
+  return { request, assignment };
+};
+
+/** Matches a sample to the exact assignment revision the read named. */
+export const bindReadRuntimeAssignmentStatsResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IReadRuntimeAssignmentStatsResponse => safe(() => {
+  const response = snapshotReadRuntimeAssignmentStatsResponse(valueArg);
+  const request = snapshotReadRuntimeAssignmentStatsRequest(requestArg);
+  requireNetwork(networkEqual(response.assignment, request.assignment));
+  return response;
+});