@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/sandbox/pods/lifecycle.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A pod sandbox's lifecycle (blueprint D34, D36), as one pure decision: from the row, the
+ * Tenant's lifecycle settings, the Sandbox's status as the sandboxes service sees it and the
+ * clock, what to ask of the service, what to write to the row, which events to record, and
+ * when to look again. `reconcile.ts` gathers the facts, carries the decision out and runs it
+ * again until nothing is left to do; the `Sandbox` object (`execution/`) serializes its runs
+ * per sandbox and keeps its timers.
+ *
+ * - **Create** is eager: a `PUT` of a new pod sandbox asks for `Running` at once. One that is
+ *   not ready within `READY_DEADLINE_MS` is `failed`, with the pod's reason; the next turn
+ *   start tries again.
+ * - **Every change** the Runtime asks for bumps `rev`; the `PUT` carries `opId =
+ *   <name>.r<rev>`, so a repeated apply is a no-op at the service, and a Sandbox whose `opId`
+ *   is not the row's is applied again.
+ * - **Idle** (`trigger: idle`): no turn on an attached session, and none ended within the
+ *   Tenant's `limits.idle` → `Suspended` (`sandbox.suspended`, reason `idle`). The volume is
+ *   kept; the next turn start asks for `Running` again.
+ * - **TTL**: the Sandbox carries `shutdownTime = createdAt + lifecycle.ttl` and the Tenant's
+ *   `onExpiry` as its `shutdownPolicy`. Once it passes, the sandbox is `expired`
+ *   (`sandbox.expired`), its host epoch moves (its tokens stop working) and turns are refused
+ *   (`sandbox_expired`); with `onExpiry: delete` it is deleted. A `PUT` with a longer TTL moves
+ *   `expiresAt`, and the next apply revives it with the later `shutdownTime`.
+ * - **Lost**: an incarnation that has run (a pod joined) whose Sandbox is gone or whose volume
+ *   is missing is `lost` (`sandbox.lost`): its host epoch moves, its Sandbox is deleted, and
+ *   only a reset brings the sandbox back. agent-sandbox recreates a deleted claim empty, so the
+ *   engine's join also checks the id it keeps on the volume (`join.ts`): a new volume is lost
+ *   too. A pod replaced on the same volume is not lost: the new pod's join bumps the epoch
+ *   (`sandbox.relaunched`).
+ * - **Delete** (`desired: deleted`): the Sandbox is deleted, and the row once it is gone.
+ * - **Reset** (`tenant/sandboxes.ts`) bumps the volume generation: a new name, so a new
+ *   Sandbox and volume; the old name is `retiring` and deleted here.
+ */
+import type { SandboxEventPayload, SandboxEventType } from "@nylorun/core/contracts";
+import type { SandboxPodPatch, SandboxPodState, SandboxResource } from "../../store/types.js";
+import type { PodStatus } from "./client.js";
+/** A pod not ready this long after it was asked to run has failed. */
+export declare const READY_DEADLINE_MS: number;
+/** How soon to look again while the pod changes. */
+export declare const POLL_MS = 2000;
+/** How soon to look again when the sandboxes service does not answer. */
+export declare const UNREACHABLE_RETRY_MS = 5000;
+/** The Tenant's lifecycle settings (D36), read each time a decision is made. */
+export interface PodLifecycleConfig {
+    readonly onExpiry: "retain" | "delete";
+    readonly idleMs: number;
+}
+/** Why the decision is made: a reconcile, or one of the sandbox's timers firing. */
+export type PodTrigger = "reconcile" | "idle" | "ttl";
+export type PodTimer = "idle" | "ttl";
+export type PodRow = SandboxResource & {
+    readonly pod: SandboxPodState;
+};
+export interface PodFacts {
+    readonly row: PodRow;
+    readonly config: PodLifecycleConfig;
+    /** The Sandbox's status; undefined when the sandboxes service did not answer. */
+    readonly status: PodStatus | undefined;
+    /** The retiring Sandbox's status, when the row names one. */
+    readonly retiring?: PodStatus | undefined;
+    /** A session attached to the sandbox has a turn running. */
+    readonly busy: boolean;
+    readonly now: number;
+    readonly trigger: PodTrigger;
+}
+export interface PodEvent<T extends SandboxEventType = SandboxEventType> {
+    readonly type: T;
+    readonly payload: SandboxEventPayload<T>;
+}
+export interface PodDecision {
+    /** Apply the row's spec (after `patch`) in this mode; `rotateJoin` mints a new join token. */
+    readonly apply?: {
+        readonly mode: "Running" | "Suspended";
+        readonly rotateJoin: boolean;
+    };
+    /** Sandboxes to delete, by name. */
+    readonly delete: readonly string[];
+    readonly patch: SandboxPodPatch;
+    readonly events: readonly PodEvent[];
+    /** The Sandbox is gone and the sandbox deleted: remove the row. */
+    readonly removeRow?: true;
+    /** Look again this soon. */
+    readonly retryAfterMs?: number;
+    /** Timers to (re)arm, at ms since the epoch. */
+    readonly arm: readonly {
+        readonly timer: PodTimer;
+        readonly at: number;
+    }[];
+}
+/** The service's operation id of the row's current spec. */
+export declare function opIdOf(pod: Pick<SandboxPodState, "k8sName" | "rev">): string;
+export declare function decide(facts: PodFacts): PodDecision;

package/dist/sandbox/pods/lifecycle.js

@@ -0,0 +1,178 @@
+/** A pod not ready this long after it was asked to run has failed. */
+export const READY_DEADLINE_MS = 5 * 60_000;
+/** How soon to look again while the pod changes. */
+export const POLL_MS = 2_000;
+/** How soon to look again when the sandboxes service does not answer. */
+export const UNREACHABLE_RETRY_MS = 5_000;
+/** The service's operation id of the row's current spec. */
+export function opIdOf(pod) {
+    return `${pod.k8sName}.r${pod.rev}`;
+}
+/** No Sandbox, pod or volume is left. */
+function gone(status) {
+    return !status.exists && !status.podPhase && status.volume === "missing";
+}
+const event = (type, payload) => ({ type, payload });
+export function decide(facts) {
+    const { row, status, now } = facts;
+    const pod = row.pod;
+    const patch = {};
+    const events = [];
+    const arm = [];
+    const deletes = [];
+    let retryAfterMs;
+    const again = (ms) => {
+        retryAfterMs = retryAfterMs === undefined ? ms : Math.min(retryAfterMs, ms);
+    };
+    const done = (extra = {}) => ({
+        ...extra,
+        delete: deletes,
+        patch,
+        events,
+        arm,
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    });
+    // An earlier incarnation's Sandbox (reset, loss) is deleted until it is gone.
+    if (pod.retiring !== undefined) {
+        const retiring = facts.retiring;
+        if (retiring === undefined)
+            again(UNREACHABLE_RETRY_MS);
+        else if (gone(retiring))
+            patch.retiring = null;
+        else {
+            if (retiring.exists && !retiring.deleting)
+                deletes.push(pod.retiring);
+            again(POLL_MS);
+        }
+    }
+    if (status === undefined) {
+        again(UNREACHABLE_RETRY_MS);
+        return done();
+    }
+    if (pod.desired === "deleted") {
+        if (gone(status) && (pod.retiring === undefined || patch.retiring === null))
+            return done({ removeRow: true });
+        if (status.exists && !status.deleting)
+            deletes.push(pod.k8sName);
+        if (pod.observed !== "deleting")
+            patch.observed = "deleting";
+        again(POLL_MS);
+        return done();
+    }
+    // Lost is terminal: only a reset (a new name) leaves it.
+    if (pod.observed === "lost") {
+        if (status.exists && !status.deleting)
+            deletes.push(pod.k8sName);
+        if (status.exists)
+            again(POLL_MS);
+        return done();
+    }
+    const expiresAt = pod.expiresAt === undefined ? undefined : Date.parse(pod.expiresAt);
+    if (expiresAt !== undefined && now >= expiresAt) {
+        if (pod.observed !== "expired") {
+            patch.observed = "expired";
+            patch.hostEpoch = pod.hostEpoch + 1;
+            events.push(event("sandbox.expired", { onExpiry: facts.config.onExpiry }));
+        }
+        if (facts.config.onExpiry === "delete") {
+            patch.desired = "deleted";
+            patch.rev = pod.rev + 1;
+            if (status.exists && !status.deleting)
+                deletes.push(pod.k8sName);
+            again(POLL_MS);
+        }
+        return done();
+    }
+    if (expiresAt !== undefined)
+        arm.push({ timer: "ttl", at: expiresAt });
+    let desired = pod.desired;
+    let rev = pod.rev;
+    if (facts.trigger === "idle" && desired === "running" && !facts.busy) {
+        const last = Date.parse(pod.lastActiveAt ?? row.createdAt);
+        const due = last + facts.config.idleMs;
+        if (now >= due) {
+            desired = "suspended";
+            rev += 1;
+            patch.desired = desired;
+            patch.rev = rev;
+            patch.hostEpoch = pod.hostEpoch + 1;
+            events.push(event("sandbox.suspended", { reason: "idle" }));
+        }
+        else
+            arm.push({ timer: "idle", at: due });
+    }
+    // An incarnation a pod has joined, whose Sandbox or volume is gone: lost.
+    if (pod.podUid !== undefined && (!status.exists || status.deleting || status.volume === "missing")) {
+        const reason = !status.exists
+            ? "The sandbox's pod and volume were deleted outside the Runtime"
+            : status.deleting
+                ? "The sandbox is being deleted outside the Runtime"
+                : "The sandbox's volume is gone";
+        patch.observed = "lost";
+        patch.reason = reason;
+        patch.hostEpoch = (patch.hostEpoch ?? pod.hostEpoch) + 1;
+        events.push(event("sandbox.lost", { reason }));
+        if (status.exists && !status.deleting)
+            deletes.push(pod.k8sName);
+        if (status.exists)
+            again(POLL_MS);
+        return done();
+    }
+    if (status.deleting) {
+        // The previous incarnation of this name is still going (a sandbox deleted and created again).
+        again(POLL_MS);
+        return done();
+    }
+    const opId = opIdOf({ k8sName: pod.k8sName, rev });
+    if (desired === "suspended" && !status.exists) {
+        if (pod.observed !== "suspended")
+            patch.observed = "suspended";
+        return done();
+    }
+    if (status.opId !== opId) {
+        if (desired === "running" && (pod.observed !== "creating" || pod.startedAt === undefined)) {
+            patch.observed = "creating";
+            patch.startedAt = new Date(now).toISOString();
+            patch.reason = null;
+        }
+        // A pod started by this apply (a create, a resume) is the sandbox's first, not a relaunch.
+        if (desired === "running" && pod.podUid !== undefined)
+            patch.podUid = null;
+        again(POLL_MS);
+        return done({
+            apply: { mode: desired === "running" ? "Running" : "Suspended", rotateJoin: !status.exists },
+        });
+    }
+    if (desired === "running") {
+        if (status.ready) {
+            if (pod.observed !== "running") {
+                patch.observed = "running";
+                patch.reason = null;
+            }
+            return done();
+        }
+        const startedAt = Date.parse(pod.startedAt ?? row.updatedAt);
+        if (pod.observed === "failed")
+            return done();
+        if (now - startedAt >= READY_DEADLINE_MS) {
+            const reason = [status.reason, status.message].filter(Boolean).join(": ") ||
+                `The pod was not ready within ${READY_DEADLINE_MS / 60_000} minutes`;
+            patch.observed = "failed";
+            patch.reason = reason;
+            events.push(event("sandbox.failed", { reason }));
+            return done();
+        }
+        if (pod.observed !== "creating")
+            patch.observed = "creating";
+        again(POLL_MS);
+        return done();
+    }
+    // Suspended, applied: suspended once its pod is gone.
+    if (status.suspended || !status.podPhase) {
+        if (pod.observed !== "suspended")
+            patch.observed = "suspended";
+        return done();
+    }
+    again(POLL_MS);
+    return done();
+}

package/dist/sandbox/pods/name.d.ts

@@ -0,0 +1 @@
+export declare function podName(tenantId: string, sandboxId: string, volumeGen: number): string;

package/dist/sandbox/pods/name.js

@@ -0,0 +1,28 @@
+/**
+ * The Kubernetes name of a pod sandbox's incarnation: `sbx-<lowercase base32(sha256(
+ * "<tenant>/<id>"))[:16]>-g<volumeGen>`, as the sandboxes service computes it (`driver.Name` in
+ * Go; `podName("shop", "sbx_01", 0)` is `sbx-ub6g5m7mvjlct6r7-g0`). A reset bumps the volume
+ * generation, so each volume belongs to one name.
+ */
+import { createHash } from "node:crypto";
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+function base32(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const byte of bytes) {
+        value = ((value << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += ALPHABET[(value << (5 - bits)) & 31];
+    return out;
+}
+export function podName(tenantId, sandboxId, volumeGen) {
+    const digest = createHash("sha256").update(`${tenantId}/${sandboxId}`).digest();
+    return `sbx-${base32(digest).slice(0, 16)}-g${volumeGen}`;
+}

package/dist/sandbox/pods/network-gate.d.ts

@@ -0,0 +1,25 @@
+export interface BlockedAddress {
+    readonly host: string;
+    readonly port: number;
+}
+/** Consecutive failed connections that prove an address blocked. */
+export declare const CONFIRMATIONS = 3;
+/** The addresses a pod's NetworkPolicy must block: the API server's service address. */
+export declare function blockedAddresses(env: Readonly<Record<string, string | undefined>>): BlockedAddress[];
+/** Whether a TCP connection to `address` opens within `timeoutMs`. */
+export declare function opens(address: BlockedAddress, timeoutMs: number): Promise<boolean>;
+export interface NetworkGateOptions {
+    readonly addresses: readonly BlockedAddress[];
+    /** Give up after this long. Default 120 s. */
+    readonly timeoutMs?: number;
+    /** One connection attempt. Default 1 s. */
+    readonly attemptMs?: number;
+    /** Between attempts after a connection opened. Default 250 ms. */
+    readonly pauseMs?: number;
+    readonly confirmations?: number;
+    readonly log?: (message: string, fields: Record<string, unknown>) => void;
+}
+/** Resolves once every address is blocked; rejects past the timeout. */
+export declare function awaitNetworkPolicy(options: NetworkGateOptions): Promise<{
+    waitedMs: number;
+}>;

package/dist/sandbox/pods/network-gate.js

@@ -0,0 +1,71 @@
+/**
+ * The engine in a pod sandbox stays off the network until the pod's NetworkPolicy is in force
+ * (F7.2). kindnet applies a new pod's policy asynchronously: a fresh pod reached the API server
+ * (`10.96.0.1:443`) for 0.5 to 5 s after it started (8a). So before the engine joins, or runs
+ * anything, it connects to addresses the policy must block (the API server's service address,
+ * `KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT`, which the kubelet always sets) until each
+ * fails `CONFIRMATIONS` times in a row (refused, unreachable or timed out). A connection that
+ * succeeds starts the count again. Past `timeoutMs` the engine exits, and the pod restarts it.
+ */
+import { connect } from "node:net";
+/** Consecutive failed connections that prove an address blocked. */
+export const CONFIRMATIONS = 3;
+/** The addresses a pod's NetworkPolicy must block: the API server's service address. */
+export function blockedAddresses(env) {
+    const override = env.NYLORUN_SANDBOX_BLOCKED_PROBE;
+    if (override) {
+        return override
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .map((entry) => {
+            const at = entry.lastIndexOf(":");
+            return { host: entry.slice(0, at).replace(/^\[|\]$/g, ""), port: Number(entry.slice(at + 1)) };
+        });
+    }
+    const host = env.KUBERNETES_SERVICE_HOST ?? "10.96.0.1";
+    const port = Number(env.KUBERNETES_SERVICE_PORT ?? "443");
+    return [{ host, port }];
+}
+/** Whether a TCP connection to `address` opens within `timeoutMs`. */
+export function opens(address, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: address.host, port: address.port });
+        const done = (open) => {
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            socket.on("error", () => undefined);
+            socket.destroy();
+            resolve(open);
+        };
+        const timer = setTimeout(() => done(false), timeoutMs);
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+/** Resolves once every address is blocked; rejects past the timeout. */
+export async function awaitNetworkPolicy(options) {
+    const started = Date.now();
+    const deadline = started + (options.timeoutMs ?? 120_000);
+    const needed = options.confirmations ?? CONFIRMATIONS;
+    for (const address of options.addresses) {
+        let failures = 0;
+        let opened = 0;
+        while (failures < needed) {
+            if (Date.now() > deadline)
+                throw new Error(`The pod's NetworkPolicy is not in force: ${address.host}:${address.port} still answered ${opened} time(s)`);
+            if (await opens(address, options.attemptMs ?? 1_000)) {
+                failures = 0;
+                opened += 1;
+                await new Promise((resolve) => setTimeout(resolve, options.pauseMs ?? 250));
+            }
+            else
+                failures += 1;
+        }
+        options.log?.("sandbox_network_policy_checked", {
+            address: `${address.host}:${address.port}`,
+            openedBefore: opened,
+        });
+    }
+    return { waitedMs: Date.now() - started };
+}

package/dist/sandbox/pods/reconcile.d.ts

@@ -0,0 +1,11 @@
+import type { TenantContext } from "../../tenant/context.js";
+import { type PodTimer, type PodTrigger } from "./lifecycle.js";
+/** What a reconcile asks of the `Sandbox` object next. */
+export interface SandboxReconcileResult {
+    readonly retryAfterMs?: number;
+    readonly arm?: readonly {
+        readonly timer: PodTimer;
+        readonly at: number;
+    }[];
+}
+export declare function reconcileSandbox(ctx: TenantContext, sandboxId: string, trigger: PodTrigger): Promise<SandboxReconcileResult>;

package/dist/sandbox/pods/reconcile.js

@@ -0,0 +1,152 @@
+/**
+ * One reconcile of a pod sandbox (S5): the `Sandbox` object's handler
+ * (`WorkerHandlers.sandbox`, serialized per sandbox). It reads the row and the Tenant's
+ * settings, asks the sandboxes service for the Sandbox's status, decides (`lifecycle.ts`),
+ * then carries the decision out:
+ *
+ * 1. a join token rotation is written first (its hash and a new `rev`), so the token the
+ *    service writes to the join Secret is always the one the row names;
+ * 2. deletes and the apply go to the service, outside any transaction;
+ * 3. the row's patch and the events are written under the row's lock, unless the row changed
+ *    since it was read (an API call or a join): then nothing is written and the reconcile runs
+ *    again at once. A host epoch the decision moves is recomputed from the locked row.
+ *
+ * It answers when to look again (`retryAfterMs`) and the timers to arm (idle, TTL). Only
+ * infrastructure errors throw; Restate retries those.
+ */
+import { randomBytes } from "node:crypto";
+import { readSandboxConfig } from "../tenant-config.js";
+import { sha256Hex } from "../join.js";
+import { decide } from "./lifecycle.js";
+import { podLifecycleConfig, podSpecOf } from "./spec.js";
+export async function reconcileSandbox(ctx, sandboxId, trigger) {
+    const pods = ctx.pods;
+    if (!pods || ctx.closed)
+        return {};
+    const read = await ctx.store.tx(async (t) => {
+        const row = await t.sandboxResource(sandboxId);
+        if (!row || row.kind !== "pod" || !row.pod)
+            return undefined;
+        const config = await readSandboxConfig(t);
+        const busy = (await t.sessionsOnSandbox(sandboxId)).some((session) => session.activeTurnId != null);
+        return { row: row, config, busy };
+    });
+    if (!read)
+        return {};
+    const { row, config } = read;
+    const status = async (name) => {
+        try {
+            return await pods.client.status(name);
+        }
+        catch (error) {
+            ctx.config.logger.warn("sandboxes service status failed", {
+                sandboxId,
+                name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    };
+    const lifecycle = podLifecycleConfig(config);
+    const decision = decide({
+        row,
+        config: lifecycle,
+        status: await status(row.pod.k8sName),
+        ...(row.pod.retiring ? { retiring: await status(row.pod.retiring) } : {}),
+        busy: read.busy,
+        now: Date.now(),
+        trigger,
+    });
+    let patch = { ...decision.patch };
+    const unchanged = (current) => current !== undefined &&
+        current.rev === row.pod.rev &&
+        current.k8sName === row.pod.k8sName &&
+        current.desired === row.pod.desired;
+    // A new join token is recorded before the service writes it to the Sandbox's Secret.
+    let joinToken;
+    let rev = patch.rev ?? row.pod.rev;
+    if (decision.apply?.rotateJoin) {
+        joinToken = randomBytes(32).toString("base64url");
+        rev += 1;
+        const recorded = await ctx.store.tx(async (t) => {
+            const current = await t.sandboxResource(sandboxId, { lock: true });
+            if (!unchanged(current?.pod))
+                return false;
+            await t.updateSandboxPod(sandboxId, { joinTokenHash: sha256Hex(joinToken), rev }, new Date().toISOString());
+            return true;
+        });
+        if (!recorded)
+            return { retryAfterMs: 0 };
+        row.pod.rev = rev;
+        row.pod.joinTokenHash = sha256Hex(joinToken);
+        patch = { ...patch, rev };
+    }
+    for (const name of decision.delete) {
+        try {
+            await pods.client.delete(name, `${name}.delete`);
+        }
+        catch (error) {
+            ctx.config.logger.warn("sandboxes service delete failed", {
+                sandboxId,
+                name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (decision.apply) {
+        const spec = podSpecOf({
+            sandboxId,
+            spec: row.spec,
+            pod: { ...row.pod, rev },
+            config,
+            mode: decision.apply.mode,
+            harnessImage: pods.harnessImage,
+            ...(joinToken ? { joinToken } : {}),
+        });
+        try {
+            await pods.client.put(row.pod.k8sName, spec);
+        }
+        catch (error) {
+            ctx.config.logger.warn("sandboxes service apply failed", {
+                sandboxId,
+                name: row.pod.k8sName,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            // Nothing of the decision is written: the next reconcile decides again.
+            return { retryAfterMs: decision.retryAfterMs ?? 5_000 };
+        }
+    }
+    const written = await ctx.store.tx(async (t) => {
+        const current = await t.sandboxResource(sandboxId, { lock: true });
+        if (!current?.pod)
+            return { kind: "gone" };
+        if (!unchanged(current.pod))
+            return { kind: "changed" };
+        if (decision.removeRow) {
+            await t.deleteSandboxResource(sandboxId);
+            return { kind: "removed" };
+        }
+        const epochMoved = patch.hostEpoch !== undefined && patch.hostEpoch !== null;
+        const finalPatch = {
+            ...patch,
+            ...(epochMoved ? { hostEpoch: current.pod.hostEpoch + 1 } : {}),
+        };
+        if (Object.keys(finalPatch).length > 0)
+            await t.updateSandboxPod(sandboxId, finalPatch, new Date().toISOString());
+        for (const item of decision.events)
+            await t.sandboxEvent(sandboxId, item.type, item.payload);
+        return { kind: "written", epoch: epochMoved ? current.pod.hostEpoch + 1 : undefined };
+    });
+    if (written.kind === "changed")
+        return { retryAfterMs: 0 };
+    if (written.kind === "removed") {
+        await ctx.sandbox.removeSandbox(sandboxId).catch(() => undefined);
+        return {};
+    }
+    if (written.kind === "written" && written.epoch !== undefined)
+        ctx.harness.revokeHost(sandboxId, written.epoch);
+    return {
+        ...(decision.retryAfterMs === undefined ? {} : { retryAfterMs: decision.retryAfterMs }),
+        ...(decision.arm.length > 0 ? { arm: decision.arm } : {}),
+    };
+}

package/dist/sandbox/pods/spec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * settings (D36, read at every apply) and the incarnation's fences. The pod shape itself is
+ * rendered only by the sandboxes service.
+ */
+import { type SandboxManifest } from "@nylorun/core/define";
+import type { TenantSandboxConfig } from "@nylorun/core/contracts";
+import type { SandboxPodState } from "../../store/types.js";
+import type { PodSpec } from "./client.js";
+import { type PodLifecycleConfig } from "./lifecycle.js";
+/** The pod's grace period to stop when the Tenant sets none (D34). */
+export declare const DEFAULT_STOP_GRACE_SECONDS = 10;
+/** The volume's size when the sandbox asks for none. */
+export declare const DEFAULT_STORAGE_GIB = 5;
+/** Where the engine in the pod keeps its records, plugin data and home (on the volume). */
+export declare const POD_HARNESS_ROOT = "/harness";
+/** What a pod sandbox's spec holds beyond a virtual one's. */
+export type PodSandboxSpec = SandboxManifest & {
+    readonly storage?: string;
+    readonly lifecycle?: {
+        readonly ttl?: string;
+    };
+};
+/** The Tenant's lifecycle settings with their defaults. */
+export declare function podLifecycleConfig(config: TenantSandboxConfig): PodLifecycleConfig & {
+    readonly stopGraceSeconds: number;
+};
+/** The volume's size in GiB. */
+export declare function storageGiBOf(spec: PodSandboxSpec): number;
+/** The Tenant's default image, when its default sandbox names one. */
+export declare function tenantDefaultImage(config: TenantSandboxConfig): string | undefined;
+export interface PodSpecInput {
+    readonly sandboxId: string;
+    readonly spec: PodSandboxSpec;
+    readonly pod: SandboxPodState;
+    readonly config: TenantSandboxConfig;
+    readonly mode: "Running" | "Suspended";
+    /** The Runtime image the engine is copied from. */
+    readonly harnessImage: string;
+    /** The join token, when this apply rotates it. */
+    readonly joinToken?: string;
+}
+export declare function podSpecOf(input: PodSpecInput): PodSpec;
+/** When a sandbox with this TTL, created at `createdAt`, expires. */
+export declare function expiresAtOf(createdAt: string, ttl: string | undefined): string | undefined;

package/dist/sandbox/pods/spec.js

@@ -0,0 +1,62 @@
+/**
+ * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * settings (D36, read at every apply) and the incarnation's fences. The pod shape itself is
+ * rendered only by the sandboxes service.
+ */
+import { parseSandboxDuration, parseSandboxSize } from "@nylorun/core/define";
+import { memoryMiBOf } from "../policy.js";
+import { opIdOf } from "./lifecycle.js";
+/** The pod's grace period to stop when the Tenant sets none (D34). */
+export const DEFAULT_STOP_GRACE_SECONDS = 10;
+/** The volume's size when the sandbox asks for none. */
+export const DEFAULT_STORAGE_GIB = 5;
+/** Where the engine in the pod keeps its records, plugin data and home (on the volume). */
+export const POD_HARNESS_ROOT = "/harness";
+/** The Tenant's lifecycle settings with their defaults. */
+export function podLifecycleConfig(config) {
+    const stopGrace = config.lifecycle?.stopGrace;
+    return {
+        onExpiry: config.lifecycle?.onExpiry ?? "retain",
+        idleMs: parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000,
+        stopGraceSeconds: stopGrace === undefined
+            ? DEFAULT_STOP_GRACE_SECONDS
+            : Math.max(1, Math.min(30, Math.round((parseSandboxDuration(stopGrace) ?? 10_000) / 1000))),
+    };
+}
+/** The volume's size in GiB. */
+export function storageGiBOf(spec) {
+    const bytes = spec.storage === undefined ? undefined : parseSandboxSize(spec.storage);
+    return bytes === undefined ? DEFAULT_STORAGE_GIB : Math.max(1, Math.ceil(bytes / 1024 ** 3));
+}
+/** The Tenant's default image, when its default sandbox names one. */
+export function tenantDefaultImage(config) {
+    const fallback = config.default;
+    return typeof fallback === "object" ? fallback.image : undefined;
+}
+export function podSpecOf(input) {
+    const { spec, pod, config } = input;
+    const lifecycle = podLifecycleConfig(config);
+    const image = spec.image ?? tenantDefaultImage(config);
+    return {
+        opId: opIdOf(pod),
+        mode: input.mode,
+        ...(image ? { image } : {}),
+        harnessImage: input.harnessImage,
+        cpus: spec.resources?.cpus ?? 1,
+        memoryMiB: memoryMiBOf(spec),
+        storageGiB: storageGiBOf(spec),
+        stopGraceSeconds: lifecycle.stopGraceSeconds,
+        ...(pod.expiresAt ? { shutdownTime: new Date(pod.expiresAt).toISOString().replace(/\.\d{3}Z$/, "Z") } : {}),
+        shutdownPolicy: lifecycle.onExpiry === "delete" ? "Delete" : "Retain",
+        env: {
+            NYLORUN_SANDBOX_ID: input.sandboxId,
+            NYLORUN_HARNESS_ROOT: POD_HARNESS_ROOT,
+        },
+        ...(input.joinToken ? { joinToken: input.joinToken } : {}),
+    };
+}
+/** When a sandbox with this TTL, created at `createdAt`, expires. */
+export function expiresAtOf(createdAt, ttl) {
+    const ms = ttl === undefined ? undefined : parseSandboxDuration(ttl);
+    return ms === undefined ? undefined : new Date(Date.parse(createdAt) + ms).toISOString();
+}