@wardby/cli 0.5.3 → 0.6.0

package/dist/native-worker/kubernetes-isolation.js

@@ -0,0 +1,218 @@
+/**
+ * Kubernetes objects for one sandbox-mode native run (docs/native-sandbox.md), as pure builders —
+ * the launcher creates exactly these and attests what the API server stored against them. One pod
+ * per run, with no service-account token, a read-only non-root container holding no credentials,
+ * its WorkerInput (capability included) mounted read-only from a per-run Secret, and a
+ * NetworkPolicy whose only egress is the native gateway's port. Names carry a hash of the run id,
+ * never the id itself.
+ */
+import { createHash } from "node:crypto";
+import { isRepositoryDigest } from "../providers/jobs/docker-isolation.js";
+import { CLOUD_METADATA_PROBES } from "../providers/jobs/metadata-probes.js";
+import { conformResources, GVISOR_RUNTIME_CLASS, platformProfile, } from "../providers/jobs/kubernetes-platform.js";
+import { NATIVE_GATEWAY_DENY_PORT, NATIVE_GATEWAY_PORT, NATIVE_WORKER_TMP_MB, NATIVE_WORKER_UID, nativeWarmWorkerName, } from "./docker-isolation.js";
+export { nativeWarmWorkerName };
+import { WARM_INPUT_FILE } from "./warm-delivery.js";
+export const NATIVE_RUN_COMPONENT_LABEL = { "wardby.io/component": "native-run" };
+export const NATIVE_GATEWAY_POD_LABEL = { "app.kubernetes.io/name": "wardby-native-gateway" };
+const MANAGED_BY_LABEL = { "app.kubernetes.io/managed-by": "wardby" };
+export const NATIVE_RUN_SHA_LABEL = "wardby.io/run-sha256";
+/** The label selector listing every native run pod (the janitor's listing). */
+export const NATIVE_RUN_SELECTOR = "wardby.io/component=native-run";
+export const NATIVE_WORKER_CONTAINER = "worker";
+export const NATIVE_INPUT_MOUNT = "/run/wardby/input";
+export const NATIVE_INPUT_KEY = "input.json";
+export const NATIVE_INPUT_FILE = `${NATIVE_INPUT_MOUNT}/${NATIVE_INPUT_KEY}`;
+/** Room for node's own writes besides /tmp; the root filesystem is read-only. */
+const EPHEMERAL_STORAGE_MI = 128;
+export function nativeKubernetesNames(runId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,199}$/.test(runId))
+        throw new Error("native_sandbox_invalid_run_id");
+    const digest = createHash("sha256").update(runId).digest("hex");
+    const base = `wardby-native-${digest.slice(0, 20)}`;
+    return { runSha: digest.slice(0, 40), pod: base, policy: base, secret: `${base}-input` };
+}
+export function nativeRunLabels(runId) {
+    return {
+        ...MANAGED_BY_LABEL,
+        ...NATIVE_RUN_COMPONENT_LABEL,
+        [NATIVE_RUN_SHA_LABEL]: nativeKubernetesNames(runId).runSha,
+    };
+}
+export function buildNativeInputSecret(input, namespace) {
+    const names = nativeKubernetesNames(input.runId);
+    return {
+        apiVersion: "v1",
+        kind: "Secret",
+        metadata: { name: names.secret, namespace, labels: nativeRunLabels(input.runId) },
+        type: "Opaque",
+        immutable: true,
+        stringData: { [NATIVE_INPUT_KEY]: JSON.stringify(input) },
+    };
+}
+export const NATIVE_SANDBOX_PLATFORM_ERROR = "native_sandbox_platform_unsupported";
+export function buildNativeRunPod(options) {
+    const names = nativeKubernetesNames(options.runId);
+    return buildNativePod(options, {
+        name: names.pod,
+        labels: nativeRunLabels(options.runId),
+        env: [{ name: "NATIVE_WORKER_INPUT_FILE", value: NATIVE_INPUT_FILE }],
+        input: { secretName: names.secret },
+    });
+}
+/** The labels of every warm pool pod: still a native-run pod (the gateway admits it), never a run's. */
+export const NATIVE_WARM_POOL_LABEL = { "wardby.io/pool": "warm" };
+export const NATIVE_WARM_TOKEN_LABEL = "wardby.io/warm-worker";
+/** The label selector listing every warm pool pod. */
+export const NATIVE_WARM_SELECTOR = "wardby.io/component=native-run,wardby.io/pool=warm";
+export function nativeWarmLabels(token) {
+    return {
+        ...MANAGED_BY_LABEL,
+        ...NATIVE_RUN_COMPONENT_LABEL,
+        ...NATIVE_WARM_POOL_LABEL,
+        [NATIVE_WARM_TOKEN_LABEL]: token,
+    };
+}
+/** A warm pool pod (native sandbox phase 6): no input yet; it waits for one delivered by exec. */
+export function buildNativeWarmPod(options) {
+    return buildNativePod(options, {
+        name: nativeWarmWorkerName(options.token),
+        labels: nativeWarmLabels(options.token),
+        env: [
+            { name: "NATIVE_WORKER_INPUT_FILE", value: WARM_INPUT_FILE },
+            { name: "NATIVE_WORKER_INPUT_WAIT_MS", value: String(Math.floor(options.waitMs)) },
+        ],
+    });
+}
+function buildNativePod(options, identity) {
+    const { namespace, image, limits } = options;
+    if (!isRepositoryDigest(image)) {
+        throw new Error("native_sandbox_image_not_pinned: a cluster pulls by registry digest (repo@sha256:...).");
+    }
+    const profile = platformProfile(options.platform ?? "generic");
+    if (profile.requiresGvisor && options.runtimeClassName !== GVISOR_RUNTIME_CLASS) {
+        throw new Error(`${NATIVE_SANDBOX_PLATFORM_ERROR}: platform ${profile.name} runs native workers only under the ${GVISOR_RUNTIME_CLASS} RuntimeClass.`);
+    }
+    // Already legal on the platform, so admission rewrites nothing (attestation compares resources).
+    // Native pods always declare ephemeral storage, which a generic profile would otherwise drop.
+    const conformed = conformResources(profile, {
+        cpuMillicores: Math.round(limits.cpus * 1000),
+        memoryMib: limits.memoryMb,
+        ephemeralStorageMib: EPHEMERAL_STORAGE_MI,
+    });
+    const resources = { ...conformed.requests, "ephemeral-storage": `${EPHEMERAL_STORAGE_MI}Mi` };
+    return {
+        apiVersion: "v1",
+        kind: "Pod",
+        metadata: { name: identity.name, namespace, labels: identity.labels },
+        spec: {
+            restartPolicy: "Never",
+            activeDeadlineSeconds: Math.max(1, Math.floor(options.activeDeadlineSeconds)),
+            automountServiceAccountToken: false,
+            enableServiceLinks: false,
+            hostNetwork: false,
+            hostPID: false,
+            hostIPC: false,
+            terminationGracePeriodSeconds: 5,
+            ...(options.runtimeClassName ? { runtimeClassName: options.runtimeClassName } : {}),
+            ...(options.priorityClassName ? { priorityClassName: options.priorityClassName } : {}),
+            securityContext: {
+                runAsNonRoot: true,
+                runAsUser: NATIVE_WORKER_UID,
+                runAsGroup: NATIVE_WORKER_UID,
+                // Secret files mount root-owned: group ownership lets the non-root worker read its input.
+                fsGroup: NATIVE_WORKER_UID,
+                seccompProfile: { type: "RuntimeDefault" },
+            },
+            containers: [
+                {
+                    name: NATIVE_WORKER_CONTAINER,
+                    image,
+                    imagePullPolicy: "IfNotPresent",
+                    env: identity.env,
+                    resources: { requests: { ...resources }, limits: { ...resources } },
+                    securityContext: {
+                        allowPrivilegeEscalation: false,
+                        privileged: false,
+                        readOnlyRootFilesystem: true,
+                        runAsNonRoot: true,
+                        capabilities: { drop: ["ALL"] },
+                    },
+                    volumeMounts: [
+                        ...(identity.input ? [{ name: "input", mountPath: NATIVE_INPUT_MOUNT, readOnly: true }] : []),
+                        { name: "tmp", mountPath: "/tmp" },
+                    ],
+                },
+            ],
+            volumes: [
+                ...(identity.input
+                    ? [{ name: "input", secret: { secretName: identity.input.secretName, defaultMode: 0o440 } }]
+                    : []),
+                { name: "tmp", emptyDir: { sizeLimit: `${NATIVE_WORKER_TMP_MB}Mi` } },
+            ],
+        },
+    };
+}
+/** Ingress: none. Egress: the native gateway's pods, on the gateway port only. */
+export function buildNativeRunNetworkPolicy(runId, namespace) {
+    return buildNativePolicy(nativeKubernetesNames(runId).policy, namespace, nativeRunLabels(runId));
+}
+/** A warm pool pod's policy: the same egress, selecting the pod by its token. */
+export function buildNativeWarmNetworkPolicy(token, namespace) {
+    return buildNativePolicy(nativeWarmWorkerName(token), namespace, nativeWarmLabels(token));
+}
+function buildNativePolicy(name, namespace, labels) {
+    return {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: { name, namespace, labels },
+        spec: {
+            podSelector: { matchLabels: labels },
+            policyTypes: ["Ingress", "Egress"],
+            ingress: [],
+            egress: [
+                {
+                    to: [{ podSelector: { matchLabels: { ...NATIVE_GATEWAY_POD_LABEL } } }],
+                    ports: [{ protocol: "TCP", port: NATIVE_GATEWAY_PORT }],
+                },
+            ],
+        },
+    };
+}
+/** Exit codes of the in-pod enforcement probe. */
+export const NATIVE_PROBE = { proven: 0, gatewayUnreachable: 3, denyReachable: 4, outsideReachable: 5 };
+/** Addresses a worker must not reach: the internet, and the cloud metadata endpoints (node and workload credentials). */
+export const NATIVE_PROBE_OUTSIDE = [
+    { host: "1.1.1.1", port: 443 },
+    ...CLOUD_METADATA_PROBES,
+];
+/**
+ * Run inside the worker container (exec): proves the pod's egress is the gateway port and nothing
+ * else — the gateway answers, while its deny port (same address, another port) and every outside
+ * address do not. A connection that is refused or times out both count as unreachable.
+ */
+export function nativeEnforcementProbe(gatewayHost, outside = NATIVE_PROBE_OUTSIDE) {
+    const script = [
+        'const net = require("node:net");',
+        "const reach = (host, port) => new Promise((done) => {",
+        "  const s = net.connect({ host, port, timeout: 3000 });",
+        "  s.once('connect', () => { s.destroy(); done(true); });",
+        "  s.once('error', () => done(false));",
+        "  s.once('timeout', () => { s.destroy(); done(false); });",
+        "});",
+        "(async () => {",
+        `  if (!(await reach(${JSON.stringify(gatewayHost)}, ${NATIVE_GATEWAY_PORT}))) process.exit(${NATIVE_PROBE.gatewayUnreachable});`,
+        // The deny port and every outside address run concurrently (each dropped connect waits the full
+        // timeout, so serial probing would eat the exec budget); the verdicts are still read in a fixed
+        // order, so when several fail the exit code is deterministic: deny port first, then outside.
+        `  const deny = reach(${JSON.stringify(gatewayHost)}, ${NATIVE_GATEWAY_DENY_PORT});`,
+        "  const outside = Promise.all([",
+        ...outside.map((o) => `    reach(${JSON.stringify(o.host)}, ${o.port}),`),
+        "  ]);",
+        `  if (await deny) process.exit(${NATIVE_PROBE.denyReachable});`,
+        `  if ((await outside).some(Boolean)) process.exit(${NATIVE_PROBE.outsideReachable});`,
+        `  process.exit(${NATIVE_PROBE.proven});`,
+        "})();",
+    ].join("\n");
+    return ["node", "-e", script];
+}

package/dist/native-worker/kubernetes-launcher.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Launches, watches, stops, and removes native sandbox workers as Kubernetes pods
+ * (docs/native-sandbox.md), from the builders in kubernetes-isolation.ts. Like the Docker
+ * launcher it keeps no state of its own: names derive from the run id, state comes from the pod,
+ * and sessions live in Postgres, so any replica can act on any run.
+ *
+ * A pod's NetworkPolicy takes effect a few seconds after the pod starts (the CNI programs it), so
+ * the session is created not ready (`networkReadyAtLaunch = false`): the gateway refuses the
+ * worker until this launcher has read back the pod and policy it created, then proven from inside
+ * the pod that the gateway port answers while the gateway's deny port and an outside address do
+ * not — and only then marks the session ready.
+ */
+import { type Power } from "../core/power.js";
+import { type KubernetesApi } from "../providers/jobs/kubernetes-api.js";
+import type { KubernetesPlatform } from "../providers/jobs/kubernetes-platform.js";
+import { type NativeWorkerLimits } from "./docker-isolation.js";
+import type { NativeWorkerState } from "./docker-launcher.js";
+import type { WorkerHandle } from "./launch.js";
+import type { WorkerInput } from "./protocol.js";
+import type { ManagedWorkerLauncher } from "./sandbox-executor.js";
+import { type WarmWorkerLauncher } from "./warm-pool.js";
+export declare const NATIVE_SANDBOX_NETWORK_UNENFORCED = "native_sandbox_network_unenforced";
+export declare const NATIVE_SANDBOX_ISOLATION_MISMATCH = "native_sandbox_isolation_mismatch";
+export declare const NATIVE_SANDBOX_CAPACITY = "native_sandbox_capacity";
+/** The API server's refusal of a pod the namespace's ResourceQuota has no room for (403 "exceeded quota"). */
+export declare function isQuotaRejection(err: unknown): boolean;
+export interface KubernetesNativeWorkerLauncherOptions {
+    api: KubernetesApi;
+    namespace: string;
+    image: string;
+    limits: NativeWorkerLimits;
+    /** The native gateway's Service, in the same namespace (NetworkPolicy selects its pods there). */
+    gatewayService: string;
+    runtimeClassName?: string;
+    /** KUBERNETES_PLATFORM: the admission rules native pods are conformed to. */
+    platform?: KubernetesPlatform;
+    /** KUBERNETES_RUN_PRIORITY_CLASS. */
+    priorityClassName?: string;
+    /** NATIVE_GATEWAY_URL: dial this instead of the Service's ClusterIP (its host is also what the probe checks). */
+    gatewayUrl?: string;
+    /** Called once a pod's isolation is proven; the executor marks the run's session ready. */
+    onNetworkProven: (runId: string) => Promise<void>;
+    /** The pod's hard lifetime (its session's deadline). */
+    deadlineSeconds: number;
+    readyTimeoutMs?: number;
+    enforcementTimeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Low-power mode: wakes the (possibly scaled-to-zero) native gateway before a launch. Default `DISABLED_POWER`. */
+    power?: Power;
+}
+/**
+ * An object as the API server would store it, for comparison: keys sorted, and missing, undefined,
+ * and empty arrays alike (it drops an empty `ingress: []`, which `policyTypes` already makes deny-all).
+ */
+export declare function canonical(value: unknown): unknown;
+export declare class KubernetesNativeWorkerLauncher implements ManagedWorkerLauncher, WarmWorkerLauncher {
+    private readonly options;
+    readonly networkReadyAtLaunch = false;
+    private gatewayHost;
+    private readonly power;
+    constructor(options: KubernetesNativeWorkerLauncherOptions);
+    private get api();
+    private get ns();
+    private sleep;
+    /** The gateway Service's ClusterIP: workers dial an address, so they need no DNS egress. */
+    private resolveGatewayHost;
+    resolveGatewayUrl(): Promise<string>;
+    private createIfMissing;
+    launch(input: WorkerInput): Promise<WorkerHandle>;
+    /**
+     * Policy first, so the pod never exists without it; then the pod; then attest and prove it. A
+     * quota rejection becomes native_sandbox_capacity. Any failure removes what was made.
+     */
+    private createIsolated;
+    /** What the API server stored must still be what was built: an admission change voids the run. */
+    private attest;
+    private matches;
+    /** Waits for the pod to run, then proves its egress from inside it (bounded). */
+    private proveIsolation;
+    handle(runId: string): WorkerHandle;
+    private handleByName;
+    inspect(runId: string): Promise<NativeWorkerState>;
+    private inspectByName;
+    kill(runId: string): Promise<void>;
+    remove(runId: string): Promise<void>;
+    listWorkers(): Promise<{
+        name: string;
+        runHash: string;
+    }[]>;
+    removeByWorkerName(name: string): Promise<void>;
+    private warmPod;
+    warmSpecHash(waitMs: number): string;
+    startWarm(token: string, waitMs: number): Promise<void>;
+    reattestWarm(token: string, waitMs: number): Promise<boolean>;
+    deliver(token: string, input: WorkerInput): Promise<void>;
+    warmHandle(token: string): WorkerHandle;
+    inspectWarm(token: string): Promise<NativeWorkerState>;
+    killWarm(token: string): Promise<void>;
+    removeWarm(token: string): Promise<void>;
+    listWarm(): Promise<string[]>;
+}

package/dist/native-worker/kubernetes-launcher.js

@@ -0,0 +1,335 @@
+/**
+ * Launches, watches, stops, and removes native sandbox workers as Kubernetes pods
+ * (docs/native-sandbox.md), from the builders in kubernetes-isolation.ts. Like the Docker
+ * launcher it keeps no state of its own: names derive from the run id, state comes from the pod,
+ * and sessions live in Postgres, so any replica can act on any run.
+ *
+ * A pod's NetworkPolicy takes effect a few seconds after the pod starts (the CNI programs it), so
+ * the session is created not ready (`networkReadyAtLaunch = false`): the gateway refuses the
+ * worker until this launcher has read back the pod and policy it created, then proven from inside
+ * the pod that the gateway port answers while the gateway's deny port and an outside address do
+ * not — and only then marks the session ready.
+ */
+import { logger } from "../core/logger.js";
+import { DISABLED_POWER, wakeTimeoutMs } from "../core/power.js";
+import { KubernetesAlreadyExistsError } from "../providers/jobs/kubernetes-api.js";
+import { canonicalResources } from "../providers/jobs/kubernetes-isolation.js";
+import { NATIVE_GATEWAY_PORT } from "./docker-isolation.js";
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
+import { buildNativeInputSecret, buildNativeRunNetworkPolicy, buildNativeRunPod, buildNativeWarmNetworkPolicy, buildNativeWarmPod, NATIVE_PROBE, NATIVE_RUN_SELECTOR, NATIVE_RUN_SHA_LABEL, NATIVE_WARM_SELECTOR, NATIVE_WARM_TOKEN_LABEL, NATIVE_WORKER_CONTAINER, nativeEnforcementProbe, nativeKubernetesNames, nativeWarmWorkerName, } from "./kubernetes-isolation.js";
+import { warmDeliveryCommand } from "./warm-delivery.js";
+import { NATIVE_SANDBOX_WARM_DELIVERY_FAILED } from "./warm-pool.js";
+const k8sLog = logger.child({ module: "native-kubernetes-launcher" });
+export const NATIVE_SANDBOX_NETWORK_UNENFORCED = "native_sandbox_network_unenforced";
+export const NATIVE_SANDBOX_ISOLATION_MISMATCH = "native_sandbox_isolation_mismatch";
+export const NATIVE_SANDBOX_CAPACITY = "native_sandbox_capacity";
+/** The API server's refusal of a pod the namespace's ResourceQuota has no room for (403 "exceeded quota"). */
+export function isQuotaRejection(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const { code, body, message } = err;
+    const text = `${typeof body === "string" ? body : JSON.stringify(body ?? "")} ${typeof message === "string" ? message : ""}`;
+    return (code === 403 || code === undefined) && /exceeded quota/i.test(text);
+}
+/**
+ * An object as the API server would store it, for comparison: keys sorted, and missing, undefined,
+ * and empty arrays alike (it drops an empty `ingress: []`, which `policyTypes` already makes deny-all).
+ */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return value.length === 0 ? undefined : value.map(canonical);
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const item = canonical(value[key]);
+        if (item !== undefined)
+            out[key] = item;
+    }
+    return out;
+}
+export class KubernetesNativeWorkerLauncher {
+    options;
+    networkReadyAtLaunch = false;
+    gatewayHost;
+    power;
+    constructor(options) {
+        this.options = options;
+        this.power = options.power ?? DISABLED_POWER;
+    }
+    get api() {
+        return this.options.api;
+    }
+    get ns() {
+        return this.options.namespace;
+    }
+    sleep(ms) {
+        return (this.options.sleep ?? ((t) => new Promise((resolve) => setTimeout(resolve, t))))(ms);
+    }
+    /** The gateway Service's ClusterIP: workers dial an address, so they need no DNS egress. */
+    resolveGatewayHost() {
+        if (this.options.gatewayUrl)
+            return Promise.resolve(new URL(this.options.gatewayUrl).hostname);
+        this.gatewayHost ??= (async () => {
+            const service = await this.api.readService(this.ns, this.options.gatewayService);
+            const ip = service?.spec?.clusterIP;
+            if (!ip || ip === "None") {
+                this.gatewayHost = undefined;
+                throw new Error(`native_sandbox_gateway_unavailable: Service "${this.options.gatewayService}" in "${this.ns}" has no ClusterIP.`);
+            }
+            return ip;
+        })();
+        return this.gatewayHost;
+    }
+    async resolveGatewayUrl() {
+        if (this.options.gatewayUrl)
+            return this.options.gatewayUrl;
+        return `http://${await this.resolveGatewayHost()}:${NATIVE_GATEWAY_PORT}/native-gateway/v1/call`;
+    }
+    async createIfMissing(create) {
+        try {
+            await create();
+        }
+        catch (err) {
+            if (!(err instanceof KubernetesAlreadyExistsError))
+                throw err;
+        }
+    }
+    async launch(input) {
+        const runId = input.runId;
+        // Low-power mode: the gateway may be scaled to zero; wake it before anything is created. Guarded
+        // so mode off adds no await.
+        if (this.power.enabled) {
+            await this.power.ensureAwake("gateway", {
+                timeoutMs: wakeTimeoutMs(this.options.readyTimeoutMs ?? 120_000),
+                runId,
+            });
+        }
+        const names = nativeKubernetesNames(runId);
+        if ((await this.inspect(runId)).state === "missing") {
+            const pod = buildNativeRunPod({
+                runId,
+                namespace: this.ns,
+                image: this.options.image,
+                limits: this.options.limits,
+                activeDeadlineSeconds: this.options.deadlineSeconds,
+                runtimeClassName: this.options.runtimeClassName,
+                platform: this.options.platform,
+                priorityClassName: this.options.priorityClassName,
+            });
+            const policy = buildNativeRunNetworkPolicy(runId, this.ns);
+            await this.createIsolated(pod, policy, () => this.remove(runId), {
+                // The Secret before the pod that mounts it.
+                beforePod: () => this.createIfMissing(() => this.api.createSecret(this.ns, buildNativeInputSecret(input, this.ns))),
+            });
+            await this.options.onNetworkProven(runId);
+        }
+        else {
+            k8sLog.info({ pod: names.pod }, "native worker pod already exists: attaching, not relaunching");
+        }
+        return this.handle(runId);
+    }
+    /**
+     * Policy first, so the pod never exists without it; then the pod; then attest and prove it. A
+     * quota rejection becomes native_sandbox_capacity. Any failure removes what was made.
+     */
+    async createIsolated(pod, policy, cleanup, hooks = {}) {
+        await this.createIfMissing(() => this.api.createNetworkPolicy(this.ns, policy));
+        await hooks.beforePod?.();
+        try {
+            await this.createIfMissing(() => this.api.createPod(this.ns, pod));
+        }
+        catch (err) {
+            if (!isQuotaRejection(err))
+                throw err;
+            await cleanup().catch(() => { });
+            throw new Error(`${NATIVE_SANDBOX_CAPACITY}: the namespace's ResourceQuota has no room for another native worker pod.`, { cause: err });
+        }
+        try {
+            await this.attest(pod, policy);
+            await this.proveIsolation(pod.metadata.name);
+        }
+        catch (err) {
+            await cleanup().catch(() => { });
+            throw err;
+        }
+    }
+    /** What the API server stored must still be what was built: an admission change voids the run. */
+    async attest(built, builtPolicy) {
+        if (!(await this.matches(built, builtPolicy))) {
+            throw new Error(`${NATIVE_SANDBOX_ISOLATION_MISMATCH}: the worker pod or its NetworkPolicy as stored differs from what was built.`);
+        }
+    }
+    async matches(built, builtPolicy) {
+        const [pod, policy] = await Promise.all([
+            this.api.readPod(this.ns, built.metadata.name),
+            this.api.readNetworkPolicy(this.ns, builtPolicy.metadata.name),
+        ]);
+        const stored = pod?.spec;
+        const want = built.spec;
+        const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+        const ok = !!stored &&
+            !!policy &&
+            same(policy.spec, builtPolicy.spec) &&
+            stored.automountServiceAccountToken === false &&
+            stored.hostNetwork !== true &&
+            stored.runtimeClassName === want.runtimeClassName &&
+            stored.priorityClassName === want.priorityClassName &&
+            stored.containers.length === 1 &&
+            stored.containers[0].image === want.containers[0].image &&
+            same(stored.containers[0].securityContext, want.containers[0].securityContext) &&
+            same(stored.containers[0].env, want.containers[0].env) &&
+            same(canonicalResources(stored.containers[0].resources), canonicalResources(want.containers[0].resources)) &&
+            (stored.initContainers ?? []).length === 0;
+        return ok;
+    }
+    /** Waits for the pod to run, then proves its egress from inside it (bounded). */
+    async proveIsolation(podName) {
+        const pollMs = this.options.pollMs ?? 1_000;
+        const readyBy = Date.now() + (this.options.readyTimeoutMs ?? 120_000);
+        for (;;) {
+            const pod = await this.api.readPod(this.ns, podName);
+            if (!pod)
+                throw new Error("native_sandbox_worker_lost: the worker pod disappeared before it was ready.");
+            const phase = pod.status?.phase ?? "Pending";
+            if (phase === "Running")
+                break;
+            if (phase === "Succeeded" || phase === "Failed") {
+                throw new Error(`native_sandbox_worker_exited: the worker pod ended before it was ready (${phase}).`);
+            }
+            if (Date.now() >= readyBy)
+                throw new Error("native_sandbox_worker_unready: the worker pod did not start in time.");
+            await this.sleep(pollMs);
+        }
+        const command = nativeEnforcementProbe(await this.resolveGatewayHost());
+        const provenBy = Date.now() + (this.options.enforcementTimeoutMs ?? 30_000);
+        let last;
+        for (;;) {
+            last = await this.api
+                .exec(this.ns, podName, NATIVE_WORKER_CONTAINER, command, { timeoutMs: 20_000 })
+                .catch(() => NATIVE_PROBE.gatewayUnreachable);
+            if (last === NATIVE_PROBE.proven)
+                return;
+            if (Date.now() >= provenBy)
+                break;
+            await this.sleep(pollMs);
+        }
+        const why = last === NATIVE_PROBE.denyReachable
+            ? "the gateway's deny port was reachable"
+            : last === NATIVE_PROBE.outsideReachable
+                ? "an outside address was reachable"
+                : "the gateway was unreachable";
+        throw new Error(`${NATIVE_SANDBOX_NETWORK_UNENFORCED}: the worker pod's isolation could not be proven (${why}).`);
+    }
+    handle(runId) {
+        return this.handleByName(nativeKubernetesNames(runId).pod);
+    }
+    handleByName(podName) {
+        const exited = (async () => {
+            for (;;) {
+                const state = await this.inspectByName(podName);
+                if (state.state === "exited")
+                    return state.exitCode;
+                if (state.state === "missing")
+                    return null;
+                await this.sleep(this.options.pollMs ?? 1_000);
+            }
+        })();
+        return { exited, kill: () => void this.api.deletePod(this.ns, podName, 0) };
+    }
+    async inspect(runId) {
+        return this.inspectByName(nativeKubernetesNames(runId).pod);
+    }
+    async inspectByName(podName) {
+        const pod = await this.api.readPod(this.ns, podName);
+        if (!pod)
+            return { state: "missing" };
+        const phase = pod.status?.phase;
+        if (phase === "Succeeded" || phase === "Failed") {
+            const terminated = pod.status?.containerStatuses?.find((c) => c.name === NATIVE_WORKER_CONTAINER)?.state
+                ?.terminated;
+            return { state: "exited", exitCode: terminated?.exitCode ?? 137 };
+        }
+        return { state: "running" };
+    }
+    async kill(runId) {
+        await this.api.deletePod(this.ns, nativeKubernetesNames(runId).pod, 0);
+    }
+    async remove(runId) {
+        await this.removeByWorkerName(nativeKubernetesNames(runId).pod);
+    }
+    async listWorkers() {
+        const pods = await this.api.listPods(this.ns, NATIVE_RUN_SELECTOR);
+        return pods
+            .map((pod) => ({ name: pod.metadata?.name ?? "", runHash: pod.metadata?.labels?.[NATIVE_RUN_SHA_LABEL] ?? "" }))
+            .filter((worker) => worker.name && worker.runHash);
+    }
+    async removeByWorkerName(name) {
+        if (!/^wardby-native-[0-9a-f]{20}$/.test(name))
+            return;
+        await this.api.deletePod(this.ns, name, 0);
+        await this.api.deleteSecret(this.ns, `${name}-input`);
+        await this.api.deleteNetworkPolicy(this.ns, name);
+    }
+    // --- Warm pool workers (native sandbox phase 6) ---
+    warmPod(token, waitMs) {
+        return buildNativeWarmPod({
+            token,
+            waitMs,
+            namespace: this.ns,
+            image: this.options.image,
+            limits: this.options.limits,
+            // A claimed worker keeps the run's whole deadline however long it waited.
+            activeDeadlineSeconds: Math.ceil(waitMs / 1000) + this.options.deadlineSeconds,
+            runtimeClassName: this.options.runtimeClassName,
+            platform: this.options.platform,
+            priorityClassName: this.options.priorityClassName,
+        });
+    }
+    warmSpecHash(waitMs) {
+        const { image, limits, runtimeClassName, platform, priorityClassName, gatewayService, gatewayUrl } = this.options;
+        const spec = { launcher: "kubernetes", ns: this.ns, image, limits, runtimeClassName, platform, priorityClassName };
+        return createHash("sha256")
+            .update(JSON.stringify({ ...spec, gatewayService, gatewayUrl, waitMs }))
+            .digest("hex");
+    }
+    async startWarm(token, waitMs) {
+        await this.createIsolated(this.warmPod(token, waitMs), buildNativeWarmNetworkPolicy(token, this.ns), () => this.removeWarm(token));
+    }
+    async reattestWarm(token, waitMs) {
+        const pod = await this.api.readPod(this.ns, nativeWarmWorkerName(token));
+        if (pod?.status?.phase !== "Running")
+            return false;
+        return this.matches(this.warmPod(token, waitMs), buildNativeWarmNetworkPolicy(token, this.ns));
+    }
+    async deliver(token, input) {
+        const code = await this.api.exec(this.ns, nativeWarmWorkerName(token), NATIVE_WORKER_CONTAINER, warmDeliveryCommand(), {
+            timeoutMs: 20_000,
+            stdin: Readable.from([`${JSON.stringify(input)}\n`]),
+        });
+        if (code !== 0) {
+            throw new Error(`${NATIVE_SANDBOX_WARM_DELIVERY_FAILED}: delivering the run's input exited ${code}.`);
+        }
+    }
+    warmHandle(token) {
+        return this.handleByName(nativeWarmWorkerName(token));
+    }
+    inspectWarm(token) {
+        return this.inspectByName(nativeWarmWorkerName(token));
+    }
+    async killWarm(token) {
+        await this.api.deletePod(this.ns, nativeWarmWorkerName(token), 0);
+    }
+    async removeWarm(token) {
+        const name = nativeWarmWorkerName(token);
+        await this.api.deletePod(this.ns, name, 0);
+        await this.api.deleteNetworkPolicy(this.ns, name);
+    }
+    async listWarm() {
+        const pods = await this.api.listPods(this.ns, NATIVE_WARM_SELECTOR);
+        return pods
+            .map((pod) => pod.metadata?.labels?.[NATIVE_WARM_TOKEN_LABEL] ?? "")
+            .filter((token) => /^[0-9a-f]{20}$/.test(token));
+    }
+}