feat(runtime): define host-local inference receipts

src/lib/adapters/container-engine.ts

@@ -8,6 +8,7 @@ import { buildSubprocessEnv } from "../subprocess-env";
 
 export type ContainerEngineOperationScope =
   | "host-doctor"
+  | "host-local-inference"
   | "gateway-inspection"
   | "managed-bootstrap"
   | "sandbox-lifecycle"

src/lib/adapters/podman/index.ts

@@ -15,7 +15,11 @@ import {
 } from "./socket-authority";
 
 export interface PodmanContainerEngineOptions {
-  readonly operation: "host-doctor" | "managed-bootstrap" | "sandbox-lifecycle";
+  readonly operation:
+    | "host-doctor"
+    | "host-local-inference"
+    | "managed-bootstrap"
+    | "sandbox-lifecycle";
   readonly socketAuthority: PodmanSocketAuthority;
   readonly executable?: string;
   readonly capture?: ContainerEngineCommandCapture;

src/lib/onboard/runtime-provider/contract.ts

@@ -29,6 +29,7 @@ export type RuntimeProviderMutationOperation =
   | "workload-cleanup";
 export type RuntimeProviderContainerEngineOperation =
   | "host-doctor"
+  | "host-local-inference"
   | "gateway-inspection"
   | "sandbox-lifecycle"
   | "workload-cleanup";

src/lib/onboard/runtime-provider/host-local-inference.test.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import {
+  type HostLocalInferenceReceipt,
+  normalizeHostLocalInferenceReceipt,
+  parseHostLocalInferenceReceipt,
+  serializeHostLocalInferenceReceipt,
+} from "./host-local-inference";
+
+const ENGINE_AUTHORITY = {
+  schemaVersion: 1,
+  providerId: "mxc",
+  operation: "host-local-inference",
+  engineId: "mxc",
+  authorityId: `mxc-endpoint:${"a".repeat(64)}`,
+  bindingSha256: "b".repeat(64),
+} as const;
+
+function receipt(service: "ollama" | "nim" | "vllm" = "vllm"): HostLocalInferenceReceipt {
+  return {
+    schemaVersion: 1,
+    providerId: "mxc",
+    service,
+    engineAuthority: ENGINE_AUTHORITY,
+    endpoint: {
+      host: "host.openshell.internal",
+      port: service === "ollama" ? 11435 : 8000,
+      networkName: "openshell",
+    },
+    runtime:
+      service === "ollama"
+        ? {
+            kind: "host",
+            probeImageRef: `quay.io/curl/curl@sha256:${"d".repeat(64)}`,
+          }
+        : {
+            kind: "container",
+            runtimeId: "mxc-runtime:alpha",
+            name: `nemoclaw-${service}-alpha`,
+            imageRef: `nvcr.io/nvidia/${service}@sha256:${"c".repeat(64)}`,
+            specSha256: "d".repeat(64),
+            gpu: { vendor: "nvidia", devices: ["nvidia.com/gpu=all"] },
+          },
+  };
+}
+
+describe("host-local inference receipt contract", () => {
+  it.each([
+    "ollama",
+    "nim",
+    "vllm",
+  ] as const)("round-trips %s authority without Podman-specific state", (service) => {
+    const expected = normalizeHostLocalInferenceReceipt(receipt(service));
+    const serialized = serializeHostLocalInferenceReceipt(expected);
+
+    expect(parseHostLocalInferenceReceipt(serialized)).toEqual(expected);
+    expect(expected.providerId).toBe("mxc");
+    expect(Object.isFrozen(expected)).toBe(true);
+    expect(Object.isFrozen(expected.endpoint)).toBe(true);
+    expect(Object.isFrozen(expected.runtime)).toBe(true);
+  });
+
+  it("rejects provider, operation, endpoint, image, and device authority drift", () => {
+    const base = receipt();
+    expect(() => normalizeHostLocalInferenceReceipt({ ...base, providerId: "other" })).toThrow(
+      "does not match engine authority",
+    );
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...base,
+        engineAuthority: { ...ENGINE_AUTHORITY, operation: "sandbox-lifecycle" },
+      }),
+    ).toThrow("wrong operation scope");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...base,
+        endpoint: { ...base.endpoint, port: 0 },
+      }),
+    ).toThrow("endpoint port is malformed");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...base,
+        runtime: { ...base.runtime, imageRef: "nvcr.io/nvidia/vllm:latest" },
+      }),
+    ).toThrow("runtime image reference is malformed");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...base,
+        runtime: {
+          ...base.runtime,
+          gpu: { vendor: "nvidia", devices: ["/dev/nvidia0"] },
+        },
+      }),
+    ).toThrow("GPU device is malformed");
+  });
+
+  it("rejects a host runtime for managed services and container runtime for Ollama", () => {
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...receipt("nim"),
+        runtime: {
+          kind: "host",
+          probeImageRef: `quay.io/curl/curl@sha256:${"d".repeat(64)}`,
+        },
+      }),
+    ).toThrow("only Ollama");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...receipt("ollama"),
+        runtime: receipt("vllm").runtime,
+      }),
+    ).toThrow("Ollama must use host-process authority");
+  });
+
+  it("rejects mutable probe images and malformed managed specification digests", () => {
+    const ollama = receipt("ollama");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...ollama,
+        runtime: { kind: "host", probeImageRef: "curlimages/curl:latest" },
+      }),
+    ).toThrow("runtime image reference is malformed");
+
+    const vllm = receipt("vllm");
+    expect(() =>
+      normalizeHostLocalInferenceReceipt({
+        ...vllm,
+        runtime: { ...vllm.runtime, specSha256: "mutable" },
+      }),
+    ).toThrow("runtime specification digest is malformed");
+  });
+
+  it("rejects extensions and noncanonical serialized receipts", () => {
+    const base = receipt();
+    expect(() => normalizeHostLocalInferenceReceipt({ ...base, extra: true })).toThrow(
+      "receipt schema is unsupported",
+    );
+    expect(() => parseHostLocalInferenceReceipt(JSON.stringify(base))).toThrow("not canonical");
+  });
+});

src/lib/onboard/runtime-provider/host-local-inference.ts

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  normalizePersistedEngineAuthority,
+  type PersistedEngineAuthority,
+} from "./persisted-engine-authority";
+
+export const HOST_LOCAL_INFERENCE_RECEIPT_SCHEMA_VERSION = 1 as const;
+
+export type HostLocalInferenceService = "ollama" | "nim" | "vllm";
+
+export interface HostLocalInferenceEndpointAuthority {
+  readonly host: string;
+  readonly port: number;
+  readonly networkName: string;
+}
+
+export type HostLocalInferenceRuntimeAuthority =
+  | {
+      readonly kind: "host";
+      /** Immutable utility image used to prove endpoint reachability from the runtime network. */
+      readonly probeImageRef: string;
+    }
+  | {
+      readonly kind: "container";
+      readonly runtimeId: string;
+      readonly name: string;
+      readonly imageRef: string;
+      /** Secret-free digest of the complete provider-owned container specification. */
+      readonly specSha256: string;
+      readonly gpu: {
+        readonly vendor: "nvidia";
+        readonly devices: readonly string[];
+      };
+    };
+
+/**
+ * Secret-free durable proof for one host-local inference route. The injected
+ * provider owns command reconstruction; central consumers retain only this
+ * normalized endpoint and runtime authority.
+ */
+export interface HostLocalInferenceReceipt {
+  readonly schemaVersion: typeof HOST_LOCAL_INFERENCE_RECEIPT_SCHEMA_VERSION;
+  readonly providerId: string;
+  readonly service: HostLocalInferenceService;
+  readonly engineAuthority: PersistedEngineAuthority;
+  readonly endpoint: HostLocalInferenceEndpointAuthority;
+  readonly runtime: HostLocalInferenceRuntimeAuthority;
+}
+
+const PROVIDER_ID = /^[a-z][a-z0-9-]{0,62}$/u;
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const SAFE_HOST = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/u;
+const RUNTIME_ID = /^[A-Za-z0-9][A-Za-z0-9._:/=+-]{0,511}$/u;
+const OCI_DIGEST_REFERENCE =
+  /^(?:[A-Za-z0-9._-]+(?::[0-9]+)?\/)*(?:[A-Za-z0-9._-]+)@sha256:[a-f0-9]{64}$/u;
+const CDI_DEVICE = /^nvidia\.com\/gpu=[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const SERVICES = new Set<HostLocalInferenceService>(["ollama", "nim", "vllm"]);
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
+const MAX_SERIALIZED_BYTES = 32 * 1024;
+
+function fail(message: string): never {
+  throw new Error(`Host-local inference receipt is invalid: ${message}`);
+}
+
+function exactRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    fail(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
+  if (Object.keys(value).sort().join(",") !== [...keys].sort().join(",")) {
+    fail(`${label} schema is unsupported`);
+  }
+}
+
+function exactText(value: unknown, pattern: RegExp, label: string): string {
+  if (
+    typeof value !== "string" ||
+    value !== value.trim() ||
+    CONTROL_CHARACTERS.test(value) ||
+    !pattern.test(value)
+  ) {
+    fail(`${label} is malformed`);
+  }
+  return value;
+}
+
+function exactPort(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 65_535) {
+    fail(`${label} is malformed`);
+  }
+  return Number(value);
+}
+
+export function normalizeHostLocalInferenceImageRef(value: unknown): string {
+  return exactText(value, OCI_DIGEST_REFERENCE, "runtime image reference");
+}
+
+function normalizeEndpoint(value: unknown): HostLocalInferenceEndpointAuthority {
+  const endpoint = exactRecord(value, "endpoint authority");
+  exactKeys(endpoint, ["host", "networkName", "port"], "endpoint authority");
+  return Object.freeze({
+    host: exactText(endpoint.host, SAFE_HOST, "endpoint host"),
+    port: exactPort(endpoint.port, "endpoint port"),
+    networkName: exactText(endpoint.networkName, SAFE_NAME, "endpoint network"),
+  });
+}
+
+function normalizeRuntime(
+  service: HostLocalInferenceService,
+  value: unknown,
+): HostLocalInferenceRuntimeAuthority {
+  const runtime = exactRecord(value, "runtime authority");
+  if (runtime.kind === "host") {
+    exactKeys(runtime, ["kind", "probeImageRef"], "host runtime authority");
+    if (service !== "ollama") fail("only Ollama may use host-process authority");
+    return Object.freeze({
+      kind: "host" as const,
+      probeImageRef: normalizeHostLocalInferenceImageRef(runtime.probeImageRef),
+    });
+  }
+  if (runtime.kind !== "container") fail("runtime kind is unsupported");
+  exactKeys(
+    runtime,
+    ["gpu", "imageRef", "kind", "name", "runtimeId", "specSha256"],
+    "container authority",
+  );
+  if (service === "ollama") fail("Ollama must use host-process authority");
+  const gpu = exactRecord(runtime.gpu, "GPU authority");
+  exactKeys(gpu, ["devices", "vendor"], "GPU authority");
+  if (gpu.vendor !== "nvidia" || !Array.isArray(gpu.devices) || gpu.devices.length === 0) {
+    fail("GPU authority must identify NVIDIA devices");
+  }
+  const devices = gpu.devices.map((device) => exactText(device, CDI_DEVICE, "GPU device"));
+  if (new Set(devices).size !== devices.length) fail("GPU devices must be unique");
+  return Object.freeze({
+    kind: "container" as const,
+    runtimeId: exactText(runtime.runtimeId, RUNTIME_ID, "runtime identity"),
+    name: exactText(runtime.name, SAFE_NAME, "runtime name"),
+    imageRef: normalizeHostLocalInferenceImageRef(runtime.imageRef),
+    specSha256: exactText(runtime.specSha256, SHA256, "runtime specification digest"),
+    gpu: Object.freeze({ vendor: "nvidia" as const, devices: Object.freeze(devices) }),
+  });
+}
+
+export function normalizeHostLocalInferenceReceipt(value: unknown): HostLocalInferenceReceipt {
+  const receipt = exactRecord(value, "receipt");
+  exactKeys(
+    receipt,
+    ["endpoint", "engineAuthority", "providerId", "runtime", "schemaVersion", "service"],
+    "receipt",
+  );
+  if (receipt.schemaVersion !== HOST_LOCAL_INFERENCE_RECEIPT_SCHEMA_VERSION) {
+    fail("schema version is unsupported");
+  }
+  if (
+    typeof receipt.service !== "string" ||
+    !SERVICES.has(receipt.service as HostLocalInferenceService)
+  ) {
+    fail("service is unsupported");
+  }
+  const service = receipt.service as HostLocalInferenceService;
+  const engineAuthority = normalizePersistedEngineAuthority(receipt.engineAuthority);
+  if (engineAuthority.operation !== "host-local-inference") {
+    fail("engine authority has the wrong operation scope");
+  }
+  const providerId = exactText(receipt.providerId, PROVIDER_ID, "provider identity");
+  if (engineAuthority.providerId !== providerId) {
+    fail("provider identity does not match engine authority");
+  }
+  return Object.freeze({
+    schemaVersion: HOST_LOCAL_INFERENCE_RECEIPT_SCHEMA_VERSION,
+    providerId,
+    service,
+    engineAuthority,
+    endpoint: normalizeEndpoint(receipt.endpoint),
+    runtime: normalizeRuntime(service, receipt.runtime),
+  });
+}
+
+export function serializeHostLocalInferenceReceipt(receipt: HostLocalInferenceReceipt): string {
+  const serialized = `${JSON.stringify(normalizeHostLocalInferenceReceipt(receipt))}\n`;
+  if (Buffer.byteLength(serialized, "utf8") > MAX_SERIALIZED_BYTES) {
+    fail("serialized receipt exceeds its bounded transport");
+  }
+  return serialized;
+}
+
+export function parseHostLocalInferenceReceipt(serialized: string): HostLocalInferenceReceipt {
+  if (
+    serialized.length === 0 ||
+    serialized.includes("\0") ||
+    Buffer.byteLength(serialized, "utf8") > MAX_SERIALIZED_BYTES
+  ) {
+    fail("serialized receipt is empty or too large");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(serialized);
+  } catch {
+    fail("serialized receipt is not valid JSON");
+  }
+  const receipt = normalizeHostLocalInferenceReceipt(parsed);
+  if (serializeHostLocalInferenceReceipt(receipt) !== serialized) {
+    fail("serialized receipt is not canonical");
+  }
+  return receipt;
+}