@serve.zone/interfaces 32.34.0 → 32.36.0

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;
+});

package/ts/data/runtimelocalvolumearchive.ts

@@ -0,0 +1,207 @@
+import type * as plugins from '../plugins.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeLocalStorageClaim } from './runtimelocalstorageclaim.js';
+import {
+  getRuntimeLocalStorageClaimReference, snapshotRuntimeLocalStorageClaim, validateRuntimeLocalStorageClaim,
+} from './runtimelocalstorageclaim.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import {
+  captureNetwork, networkDigest, networkEqual, networkRecord, networkReference, requireNetwork,
+} from '../private/networkcontract.js';
+
+/**
+ * The one archive format a volume travels in: a POSIX.1-2001 pax archive of the volume's tree.
+ *
+ * The first entry is the volume's root, `./`, and every other name is relative below it. An entry is
+ * a directory, a regular file, a symbolic link (stored, never followed), a hard link to an earlier
+ * entry of the same archive, or a FIFO. Ownership is numeric: `uid` and `gid`, never user or group
+ * names, so the tree means the same on every host. Mode bits, including setuid, setgid and sticky,
+ * and the modification time travel exactly. A socket carries no bytes and belongs to the process
+ * that created it, so it is omitted; a device node, extended attributes and ACLs are not part of
+ * the format, and a volume that holds a device node is refused. The archive ends with the format's
+ * two zero blocks, so its length is a whole number of 512-byte blocks.
+ */
+export type TRuntimeLocalVolumeArchiveFormat = 'pax';
+
+/**
+ * A local controller reads one volume as an archive. The node refuses while a running container
+ * holds the volume: it reads a volume no container holds, or one whose holding container is
+ * stopped, which a node never restarts, and no container is granted the volume while it reads.
+ */
+export interface IReadRuntimeLocalVolumeArchiveRequest {
+  session: IRuntimeSessionBinding;
+  /** The reference of the node's current generation of a bound `directory` claim. */
+  claim: IRuntimeAuthorityReference;
+}
+
+/**
+ * The archive arrives on the stream the TypedRequest answers beside this body. `holder` states
+ * whether the volume was read unheld or under a stopped holder. The stream carries no integrity:
+ * the node learns the archive's length and digest only while it writes it.
+ */
+export interface IReadRuntimeLocalVolumeArchiveResponse {
+  claim: IRuntimeAuthorityReference;
+  format: TRuntimeLocalVolumeArchiveFormat;
+  holder: 'none' | 'stopped';
+}
+
+/**
+ * A local controller writes one archive as the bytes of an `import` claim that waits in
+ * `import-required`: the online form of an operator's offline import. The node receives the stream
+ * beside this body, whose integrity must be exactly `byteLength` and `digest`, unpacks it into a
+ * private staging tree, and publishes that tree as the volume only after the whole archive
+ * verified. The tree keeps the ownership the archive carries, as every imported tree does.
+ */
+export interface IWriteRuntimeLocalVolumeArchiveRequest {
+  session: IRuntimeSessionBinding;
+  claim: IRuntimeAuthorityReference;
+  format: TRuntimeLocalVolumeArchiveFormat;
+  byteLength: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * `receiving` permits sending and confirms nothing more. The stream's acceptance receipt is what
+ * confirms that the node published the volume as `ready`; a rejected or aborted stream leaves the
+ * claim in `import-required` with nothing published.
+ */
+export interface IWriteRuntimeLocalVolumeArchiveResponse {
+  claim: IRuntimeAuthorityReference;
+  status: 'receiving';
+}
+
+/**
+ * Volume archives are a local controller's alone (`controller.kind: 'onebox'`), on the connection
+ * that holds its session, and a node moves one archive per volume at a time: a read or write of a
+ * volume that is already moving one is refused.
+ */
+export const runtimeLocalVolumeArchiveContract = Object.freeze({
+  error: 'Runtime local volume archive contract rejected.',
+  controllerKind: 'onebox',
+  format: 'pax',
+  entryKinds: ['directory', 'file', 'symlink', 'hardlink', 'fifo'],
+  omittedEntryKinds: ['socket'],
+  ownership: 'numeric-uid-gid',
+  blockBytes: 512,
+  /** The shortest archive: the root directory's header and the two closing zero blocks. */
+  minimumArchiveBytes: 1536,
+  concurrency: 'one-archive-per-volume',
+} as const);
+
+const fail = (): never => { throw new Error(runtimeLocalVolumeArchiveContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+const archiveBytesOf = (valueArg: unknown): number => {
+  requireNetwork(typeof valueArg === 'number' && Number.isSafeInteger(valueArg)
+    && valueArg >= runtimeLocalVolumeArchiveContract.minimumArchiveBytes
+    && valueArg % runtimeLocalVolumeArchiveContract.blockBytes === 0);
+  return valueArg;
+};
+
+export const snapshotReadRuntimeLocalVolumeArchiveRequest = (
+  valueArg: unknown,
+): IReadRuntimeLocalVolumeArchiveRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim']);
+  return { session: snapshotRuntimeSessionBinding(value.session), claim: networkReference(value.claim) };
+});
+
+export const snapshotReadRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown,
+): IReadRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claim', 'format', 'holder']);
+  requireNetwork(value.format === 'pax' && (value.holder === 'none' || value.holder === 'stopped'));
+  return { claim: networkReference(value.claim), format: 'pax', holder: value.holder };
+});
+
+export const snapshotWriteRuntimeLocalVolumeArchiveRequest = (
+  valueArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['session', 'claim', 'format', 'byteLength', 'digest']);
+  requireNetwork(value.format === 'pax');
+  return {
+    session: snapshotRuntimeSessionBinding(value.session), claim: networkReference(value.claim), format: 'pax',
+    byteLength: archiveBytesOf(value.byteLength), digest: networkDigest(value.digest),
+  };
+});
+
+export const snapshotWriteRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claim', 'status']);
+  requireNetwork(value.status === 'receiving');
+  return { claim: networkReference(value.claim), status: 'receiving' };
+});
+
+/** The exact integrity the write's stream must carry: the request's length and digest. */
+export const getRuntimeLocalVolumeArchiveIntegrity = (
+  requestArg: unknown,
+): plugins.typedrequestInterfaces.IVirtualStreamIntegrity => {
+  const request = snapshotWriteRuntimeLocalVolumeArchiveRequest(requestArg);
+  return { algorithm: 'sha256', byteLength: request.byteLength, digest: request.digest };
+};
+
+/**
+ * The claim a request names must be the node's current generation of a bound `directory` claim of
+ * the session's controller, cluster, node and runtime namespace, and the session must be a local
+ * controller's current one.
+ */
+const bindClaim = async (
+  requestArg: { session: IRuntimeSessionBinding; claim: IRuntimeAuthorityReference },
+  claimArg: unknown, trustedSessionArg: unknown,
+): Promise<IRuntimeLocalStorageClaim> => {
+  const trustedSession = safe(() => snapshotRuntimeSessionBinding(trustedSessionArg));
+  const claim = safe(() => snapshotRuntimeLocalStorageClaim(claimArg));
+  if ((await validateRuntimeLocalStorageClaim(claim)).length) fail();
+  safe(() => requireNetwork(networkEqual(requestArg.session, trustedSession)
+    && trustedSession.controller.kind === runtimeLocalVolumeArchiveContract.controllerKind
+    && networkEqual(requestArg.claim, getRuntimeLocalStorageClaimReference(claim))
+    && claim.lifecycle === 'bound' && claim.source.kind === 'directory'
+    && networkEqual(claim.controller, trustedSession.controller)
+    && claim.clusterId === trustedSession.clusterId
+    && claim.nodeId === trustedSession.nodeId
+    && claim.runtimeNamespace === trustedSession.runtimeNamespace));
+  return claim;
+};
+
+/**
+ * Node-side content binding, not authentication. `claimArg` is the node's current generation of the
+ * named claim and `trustedSessionArg` its CURRENT session, on whose own connection the request must
+ * have arrived. Whether the volume is `ready` and who holds it are the node's ledger checks.
+ */
+export const bindReadRuntimeLocalVolumeArchiveRequest = async (
+  valueArg: unknown, claimArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IReadRuntimeLocalVolumeArchiveRequest; claim: IRuntimeLocalStorageClaim }> => {
+  const request = snapshotReadRuntimeLocalVolumeArchiveRequest(valueArg);
+  return { request, claim: await bindClaim(request, claimArg, trustedSessionArg) };
+};
+
+/**
+ * As the read binding, and the claim must be an `import` claim. That it still waits in
+ * `import-required` is the node's ledger check.
+ */
+export const bindWriteRuntimeLocalVolumeArchiveRequest = async (
+  valueArg: unknown, claimArg: unknown, trustedSessionArg: unknown,
+): Promise<{ request: IWriteRuntimeLocalVolumeArchiveRequest; claim: IRuntimeLocalStorageClaim }> => {
+  const request = snapshotWriteRuntimeLocalVolumeArchiveRequest(valueArg);
+  const claim = await bindClaim(request, claimArg, trustedSessionArg);
+  if (claim.initialization !== 'import') fail();
+  return { request, claim };
+};
+
+export const bindReadRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IReadRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const response = snapshotReadRuntimeLocalVolumeArchiveResponse(valueArg);
+  requireNetwork(networkEqual(response.claim, snapshotReadRuntimeLocalVolumeArchiveRequest(requestArg).claim));
+  return response;
+});
+
+export const bindWriteRuntimeLocalVolumeArchiveResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IWriteRuntimeLocalVolumeArchiveResponse => safe(() => {
+  const response = snapshotWriteRuntimeLocalVolumeArchiveResponse(valueArg);
+  requireNetwork(networkEqual(response.claim, snapshotWriteRuntimeLocalVolumeArchiveRequest(requestArg).claim));
+  return response;
+});

package/ts/data/user.ts

@@ -13,6 +13,11 @@ export type TServiceDeploymentCapability =
   | 'deployment:adopt-existing'
   | 'deployment:status'
   | 'deployment:create-greenfield'
+  /**
+   * Reserve a greenfield successor whose image Cloudly imports from an attested legacy service,
+   * and have Cloudly import it. Granted on an organization-service-slot grant only.
+   */
+  | 'deployment:import-legacy'
   | 'deployment:promote-route'
   | 'deployment:rollback-image'
   | 'deployment:rollback-route'
@@ -53,6 +58,7 @@ const serviceDeploymentCapabilities = new Set<TServiceDeploymentCapability>([
   'deployment:adopt-existing',
   'deployment:status',
   'deployment:create-greenfield',
+  'deployment:import-legacy',
   'deployment:promote-route',
   'deployment:rollback-image',
   'deployment:rollback-route',
@@ -106,6 +112,10 @@ export const validateServiceDeploymentGrant = (
     && capabilities.includes('deployment:adopt-existing')) {
     errors.push('deployment:adopt-existing requires an existing-service grant');
   }
+  if (capabilities && grant.scope !== 'organization-service-slot'
+    && capabilities.includes('deployment:import-legacy')) {
+    errors.push('deployment:import-legacy requires an organization-service-slot grant');
+  }
   return errors;
 };