@nylorun/runtime 0.23.0-beta → 0.25.0-beta

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

@@ -1,5 +1,5 @@
 /**
- * A pod sandbox's lifecycle (blueprint D34, D36), as one pure decision: from the row, the
+ * A pod Environment'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
@@ -12,42 +12,51 @@
  * - **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`.
+ * - **Idle** (`trigger: idle`): no turn on a session that names it, and none ended within its
+ *   `lifecycle.idle` (at most the Tenant's `limits.idle`) → `Suspended` (`environment.suspended`,
+ *   reason `idle`). The volume is kept; the next turn start asks for `Running` again.
  * - **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`).
+ *   is missing is `lost` (`environment.lost`): its host epoch moves, its Sandbox is deleted, and
+ *   only a reset brings the Environment 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
+ *   (`environment.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
+ * - **Reset** (`tenant/environments.ts`) bumps the volume generation: a new name, so a new
  *   Sandbox and volume; the old name is `retiring` and deleted here.
+ *
+ * - **Setup** (R2d step 2): a failed setup (`sandbox/setup.ts`) leaves the pod `failed` with a
+ *   reason that starts `setup:`, even while the pod is ready, until a turn start asks it to run.
+ * - **Image** (Q14): the first ready pod's workload image is recorded by digest (`imageDigest`),
+ *   and every later apply runs that digest, so a stop, relaunch or reset never pulls another
+ *   image under the same tag. An image id with no repository (a locally loaded image) pins nothing.
+ *
+ * An unused Environment is deleted by the Tenant sweep (`lifecycle.deleteAfter`), not here.
  */
-import type { SandboxEventPayload, SandboxEventType } from "@nylorun/core/contracts";
-import type { SandboxPodPatch, SandboxPodState, SandboxResource } from "../../store/types.js";
+import type { EnvironmentEventPayload, EnvironmentEventType } from "@nylorun/core/contracts";
+import type { Environment, SandboxPodPatch, SandboxPodState } from "../../store/types.js";
 import type { PodStatus } from "./client.js";
+/**
+ * The pullable reference of the image id a container status names (`repo@sha256:…`), or
+ * undefined for one without a repository, such as an image loaded onto the node.
+ */
+export declare function imageDigestOf(imageID: string | undefined): string | undefined;
+/** A setup failure's `reason` starts with this (`sandbox/setup.ts`); it is sticky. */
+export declare const SETUP_FAILED = "setup:";
 /** 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. */
+/** The 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 & {
+/** Why the decision is made: a reconcile, or the idle timer firing. */
+export type PodTrigger = "reconcile" | "idle";
+export type PodTimer = "idle";
+export type PodRow = Environment & {
     readonly pod: SandboxPodState;
 };
 export interface PodFacts {
@@ -57,14 +66,14 @@ export interface PodFacts {
     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. */
+    /** A session that names the Environment has a turn running. */
     readonly busy: boolean;
     readonly now: number;
     readonly trigger: PodTrigger;
 }
-export interface PodEvent<T extends SandboxEventType = SandboxEventType> {
+export interface PodEvent<T extends EnvironmentEventType = EnvironmentEventType> {
     readonly type: T;
-    readonly payload: SandboxEventPayload<T>;
+    readonly payload: EnvironmentEventPayload<T>;
 }
 export interface PodDecision {
     /** Apply the row's spec (after `patch`) in this mode; `rotateJoin` mints a new join token. */
@@ -76,7 +85,7 @@ export interface PodDecision {
     readonly delete: readonly string[];
     readonly patch: SandboxPodPatch;
     readonly events: readonly PodEvent[];
-    /** The Sandbox is gone and the sandbox deleted: remove the row. */
+    /** The Sandbox is gone and the Environment deleted: remove the row. */
     readonly removeRow?: true;
     /** Look again this soon. */
     readonly retryAfterMs?: number;

package/dist/sandbox/pods/lifecycle.js

@@ -1,3 +1,16 @@
+/**
+ * The pullable reference of the image id a container status names (`repo@sha256:…`), or
+ * undefined for one without a repository, such as an image loaded onto the node.
+ */
+export function imageDigestOf(imageID) {
+    const id = imageID?.replace(/^docker-pullable:\/\//, "");
+    if (!id)
+        return undefined;
+    const at = id.indexOf("@sha256:");
+    return at > 0 && /^[0-9a-f]{64}$/.test(id.slice(at + 8)) ? id : undefined;
+}
+/** A setup failure's `reason` starts with this (`sandbox/setup.ts`); it is sticky. */
+export const SETUP_FAILED = "setup:";
 /** 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. */
@@ -67,24 +80,6 @@ export function decide(facts) {
             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) {
@@ -96,7 +91,7 @@ export function decide(facts) {
             patch.desired = desired;
             patch.rev = rev;
             patch.hostEpoch = pod.hostEpoch + 1;
-            events.push(event("sandbox.suspended", { reason: "idle" }));
+            events.push(event("environment.suspended", { reason: "idle" }));
         }
         else
             arm.push({ timer: "idle", at: due });
@@ -104,14 +99,14 @@ export function decide(facts) {
     // 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"
+            ? "The Environment'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";
+                ? "The Environment's pod is being deleted outside the Runtime"
+                : "The Environment's volume is gone";
         patch.observed = "lost";
         patch.reason = reason;
         patch.hostEpoch = (patch.hostEpoch ?? pod.hostEpoch) + 1;
-        events.push(event("sandbox.lost", { reason }));
+        events.push(event("environment.lost", { reason }));
         if (status.exists && !status.deleting)
             deletes.push(pod.k8sName);
         if (status.exists)
@@ -119,7 +114,7 @@ export function decide(facts) {
         return done();
     }
     if (status.deleting) {
-        // The previous incarnation of this name is still going (a sandbox deleted and created again).
+        // The previous incarnation of this name is still going (an Environment deleted and created again).
         again(POLL_MS);
         return done();
     }
@@ -135,7 +130,7 @@ export function decide(facts) {
             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.
+        // A pod started by this apply (a create, a resume) is the Environment's first, not a relaunch.
         if (desired === "running" && pod.podUid !== undefined)
             patch.podUid = null;
         again(POLL_MS);
@@ -144,11 +139,19 @@ export function decide(facts) {
         });
     }
     if (desired === "running") {
+        // A failed setup (R2d step 2) stays failed until a turn start asks the pod to run again,
+        // though the pod itself is ready: its engine takes no turn meanwhile.
+        if (pod.observed === "failed" && pod.reason?.startsWith(SETUP_FAILED))
+            return done();
         if (status.ready) {
             if (pod.observed !== "running") {
                 patch.observed = "running";
                 patch.reason = null;
             }
+            // The image it runs, pinned by digest from now on (Q14).
+            const digest = pod.imageDigest === undefined ? imageDigestOf(status.imageID) : undefined;
+            if (digest !== undefined)
+                patch.imageDigest = digest;
             return done();
         }
         const startedAt = Date.parse(pod.startedAt ?? row.updatedAt);
@@ -159,7 +162,7 @@ export function decide(facts) {
                 `The pod was not ready within ${READY_DEADLINE_MS / 60_000} minutes`;
             patch.observed = "failed";
             patch.reason = reason;
-            events.push(event("sandbox.failed", { reason }));
+            events.push(event("environment.failed", { reason }));
             return done();
         }
         if (pod.observed !== "creating")

package/dist/sandbox/pods/reconcile.js

@@ -15,8 +15,10 @@
  * infrastructure errors throw; Restate retries those.
  */
 import { randomBytes } from "node:crypto";
-import { readSandboxConfig } from "../tenant-config.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../tenant-config.js";
+import { podSandboxSpecOf } from "../resolve.js";
 import { sha256Hex } from "../join.js";
+import { recoverLostVolume } from "../../artifacts/disk.js";
 import { decide } from "./lifecycle.js";
 import { podLifecycleConfig, podSpecOf } from "./spec.js";
 export async function reconcileSandbox(ctx, sandboxId, trigger) {
@@ -24,11 +26,11 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
     if (!pods || ctx.closed)
         return {};
     const read = await ctx.store.tx(async (t) => {
-        const row = await t.sandboxResource(sandboxId);
+        const row = await t.environment(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);
+        const busy = (await t.sessionsOnEnvironment(sandboxId)).some((session) => session.activeTurnId != null);
         return { row: row, config, busy };
     });
     if (!read)
@@ -47,7 +49,7 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             return undefined;
         }
     };
-    const lifecycle = podLifecycleConfig(config);
+    const lifecycle = podLifecycleConfig(config, row.recipe);
     const decision = decide({
         row,
         config: lifecycle,
@@ -69,10 +71,10 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         joinToken = randomBytes(32).toString("base64url");
         rev += 1;
         const recorded = await ctx.store.tx(async (t) => {
-            const current = await t.sandboxResource(sandboxId, { lock: true });
+            const current = await t.environment(sandboxId, { lock: true });
             if (!unchanged(current?.pod))
                 return false;
-            await t.updateSandboxPod(sandboxId, { joinTokenHash: sha256Hex(joinToken), rev }, new Date().toISOString());
+            await t.updateEnvironmentPod(sandboxId, { joinTokenHash: sha256Hex(joinToken), rev }, new Date().toISOString());
             return true;
         });
         if (!recorded)
@@ -95,12 +97,13 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
     }
     if (decision.apply) {
         const spec = podSpecOf({
-            sandboxId,
-            spec: row.spec,
+            environmentId: sandboxId,
+            spec: podSandboxSpecOf(row.applied, effectiveSandboxConfig(config).limits.idle),
             pod: { ...row.pod, rev },
             config,
             mode: decision.apply.mode,
             harnessImage: pods.harnessImage,
+            harness: row.applied.harness,
             ...(joinToken ? { joinToken } : {}),
         });
         try {
@@ -117,13 +120,13 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         }
     }
     const written = await ctx.store.tx(async (t) => {
-        const current = await t.sandboxResource(sandboxId, { lock: true });
+        const current = await t.environment(sandboxId, { lock: true });
         if (!current?.pod)
             return { kind: "gone" };
         if (!unchanged(current.pod))
             return { kind: "changed" };
         if (decision.removeRow) {
-            await t.deleteSandboxResource(sandboxId);
+            await t.deleteEnvironment(sandboxId);
             return { kind: "removed" };
         }
         const epochMoved = patch.hostEpoch !== undefined && patch.hostEpoch !== null;
@@ -132,9 +135,9 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             ...(epochMoved ? { hostEpoch: current.pod.hostEpoch + 1 } : {}),
         };
         if (Object.keys(finalPatch).length > 0)
-            await t.updateSandboxPod(sandboxId, finalPatch, new Date().toISOString());
+            await t.updateEnvironmentPod(sandboxId, finalPatch, new Date().toISOString());
         for (const item of decision.events)
-            await t.sandboxEvent(sandboxId, item.type, item.payload);
+            await t.environmentEvent(sandboxId, item.type, item.payload);
         if (epochMoved)
             await t.signal({ type: "host.revoked", sandboxId, epoch: finalPatch.hostEpoch });
         return { kind: "written" };
@@ -145,6 +148,9 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         await ctx.sandbox.removeSandbox(sandboxId).catch(() => undefined);
         return {};
     }
+    // A lost volume with a disk version starts again from the latest one (R2d step 3).
+    if (patch.observed === "lost" && (await recoverLostVolume(ctx, sandboxId).catch(() => false)))
+        return { retryAfterMs: 0 };
     return {
         ...(decision.retryAfterMs === undefined ? {} : { retryAfterMs: decision.retryAfterMs }),
         ...(decision.arm.length > 0 ? { arm: decision.arm } : {}),

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

@@ -1,10 +1,11 @@
 /**
- * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * The `PUT /v1/pods/{name}` body of a pod Environment: its applied recipe, 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 EnvironmentRecipe } from "@nylorun/core/contracts";
+import type { TenantSandboxConfig } from "../tenant-config.js";
 import type { SandboxPodState } from "../../store/types.js";
 import type { PodSpec } from "./client.js";
 import { type PodLifecycleConfig } from "./lifecycle.js";
@@ -14,32 +15,33 @@ export declare const DEFAULT_STOP_GRACE_SECONDS = 10;
 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. */
+/** What a pod's spec holds beyond a virtual sandbox'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 & {
+/**
+ * The lifecycle settings with their defaults: the Tenant's (D36), and the Environment's
+ * `lifecycle.idle` within the Tenant's `limits.idle` when `recipe` is given.
+ */
+export declare function podLifecycleConfig(config: TenantSandboxConfig, recipe?: Pick<EnvironmentRecipe, "lifecycle">): 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 environmentId: 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 harness the pod runs (R4.4): ours, copied in from `harnessImage`, or a custom one, which
+     * is the workload image itself and runs as its entrypoint.
+     */
+    readonly harness?: 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

@@ -1,9 +1,10 @@
 /**
- * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * The `PUT /v1/pods/{name}` body of a pod Environment: its applied recipe, 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 { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { memoryMiBOf } from "../policy.js";
 import { opIdOf } from "./lifecycle.js";
 /** The pod's grace period to stop when the Tenant sets none (D34). */
@@ -12,12 +13,16 @@ export const DEFAULT_STOP_GRACE_SECONDS = 10;
 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) {
+/**
+ * The lifecycle settings with their defaults: the Tenant's (D36), and the Environment's
+ * `lifecycle.idle` within the Tenant's `limits.idle` when `recipe` is given.
+ */
+export function podLifecycleConfig(config, recipe) {
     const stopGrace = config.lifecycle?.stopGrace;
+    const tenantIdle = parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000;
+    const own = recipe?.lifecycle.idle === undefined ? undefined : parseSandboxDuration(recipe.lifecycle.idle);
     return {
-        onExpiry: config.lifecycle?.onExpiry ?? "retain",
-        idleMs: parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000,
+        idleMs: own === undefined ? tenantIdle : Math.min(own, tenantIdle),
         stopGraceSeconds: stopGrace === undefined
             ? DEFAULT_STOP_GRACE_SECONDS
             : Math.max(1, Math.min(30, Math.round((parseSandboxDuration(stopGrace) ?? 10_000) / 1000))),
@@ -28,35 +33,27 @@ 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);
+    // Pinned by digest once a pod ran it (Q14).
+    const image = pod.imageDigest ?? spec.image;
+    const ours = (input.harness ?? DEFAULT_HARNESS) === DEFAULT_HARNESS;
     return {
         opId: opIdOf(pod),
         mode: input.mode,
         ...(image ? { image } : {}),
-        harnessImage: input.harnessImage,
+        // A custom harness is its image: the pod runs the image's entrypoint, nothing copied in.
+        ...(ours ? { harnessImage: input.harnessImage } : { entrypoint: "image" }),
         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",
+        shutdownPolicy: "Retain",
         env: {
-            NYLORUN_SANDBOX_ID: input.sandboxId,
+            NYLORUN_SANDBOX_ID: input.environmentId,
             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();
-}

package/dist/sandbox/records.d.ts

@@ -16,10 +16,10 @@ export declare function workspacePrefix(scope: string): string;
 /** The key of session `sessionId`'s own workspace. */
 export declare function sessionWorkspaceKey(scope: string, sessionId: string): string;
 /**
- * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * The key of sandbox resource `environmentId`'s workspace: apart from every session key (16 hex
  * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
  */
-export declare function sandboxWorkspaceKey(scope: string, sandboxId: string): string;
+export declare function sandboxWorkspaceKey(scope: string, environmentId: string): string;
 /** The records in the Tenant's `sandboxes` table. */
 export declare function storeSandboxRecords(store: SessionStore): SandboxRecords;
 /**

package/dist/sandbox/records.js

@@ -21,11 +21,11 @@ export function sessionWorkspaceKey(scope, sessionId) {
     return workspacePrefix(scope) + createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
 }
 /**
- * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * The key of sandbox resource `environmentId`'s workspace: apart from every session key (16 hex
  * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
  */
-export function sandboxWorkspaceKey(scope, sandboxId) {
-    return `${workspacePrefix(scope)}sbx-${createHash("sha256").update(sandboxId).digest("hex").slice(0, 16)}`;
+export function sandboxWorkspaceKey(scope, environmentId) {
+    return `${workspacePrefix(scope)}sbx-${createHash("sha256").update(environmentId).digest("hex").slice(0, 16)}`;
 }
 /** The records in the Tenant's `sandboxes` table. */
 export function storeSandboxRecords(store) {

package/dist/sandbox/resolve.d.ts

@@ -1,37 +1,47 @@
 /**
- * Resolves the sandbox a session asks for when it is opened against its Tenant's configuration.
- * Pure: the caller supplies the configuration and who is asking. Every problem is
- * reported, not only the first, so one response lists all of them.
+ * Resolves an Environment's recipe (`PUT /v1/environments/{id}`) against its Tenant's limits,
+ * and the sandbox spec a recipe gives a session's pinned manifest (its `runtime` block) and the pod. Pure: the
+ * caller supplies the configuration. Every problem is reported, not only the first, so one
+ * response lists all of them.
  */
-import type { SandboxInlineRequest } from "@nylorun/core/contracts";
-import type { SandboxManifest } from "@nylorun/core/define";
+import type { EnvironmentFile, EnvironmentKind, EnvironmentLifecycle, EnvironmentRecipe, EnvironmentSecretSlots, EnvironmentSetupCommand } from "@nylorun/core/contracts";
+import { type SandboxManifest } from "@nylorun/core/define";
+import type { PodSandboxSpec } from "./pods/spec.js";
 import { type EffectiveSandboxConfig } from "./tenant-config.js";
-export type SandboxSource = "default" | "inline";
-export type SandboxResolution = {
-    readonly kind: "none";
-} | {
-    readonly kind: "sandbox";
-    readonly spec: SandboxManifest;
-    readonly source: SandboxSource;
+/** What a `PUT` asks of the recipe: the request's fields, over the existing recipe's. */
+export interface RecipeRequest {
+    readonly image?: string;
+    readonly resources?: {
+        readonly cpus?: number;
+        readonly memory?: string;
+    };
+    readonly storage?: string;
+    readonly network?: {
+        readonly allowedHosts?: readonly string[];
+    };
+    readonly harness?: string;
+    readonly lifecycle?: EnvironmentLifecycle;
+    readonly setup?: readonly EnvironmentSetupCommand[];
+    readonly files?: readonly EnvironmentFile[];
+    /** The secret slots (D64): passed through for every kind. */
+    readonly secrets?: EnvironmentSecretSlots;
+}
+export type RecipeResolution = {
+    readonly kind: "recipe";
+    readonly recipe: EnvironmentRecipe;
 } | {
     readonly kind: "error";
-    readonly status: 400 | 403;
     readonly errors: readonly string[];
 };
-export interface ResolveSandboxInput {
-    /** `PutSessionRequest.sandbox` other than `{ session }`, which the caller handles. */
-    readonly request: false | SandboxInlineRequest | undefined;
-    readonly config: EffectiveSandboxConfig;
-    /** The request acts for a subject (`Nylorun-Subject`) rather than as the application. */
-    readonly actingForSubject: boolean;
-    /**
-     * The sandbox's kind. Default `virtual`, which runs no images and allows exact host names
-     * only; a `pod` (F7.2) takes an image and `*.suffix` hosts.
-     */
-    readonly kind?: "virtual" | "pod";
-}
-export declare const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
-export declare function resolveSandbox(input: ResolveSandboxInput): SandboxResolution;
+/** The recipe `request` asks for an Environment of `kind`, or every reason it cannot have it. */
+export declare function resolveRecipe(kind: EnvironmentKind, request: RecipeRequest, config: EffectiveSandboxConfig): RecipeResolution;
+/**
+ * The sandbox spec of a recipe: what a session's `runtime` block pins and the virtual
+ * workspace runs. Idle is the Environment's `lifecycle.idle`, else the Tenant's.
+ */
+export declare function sandboxSpecOf(recipe: EnvironmentRecipe, tenantIdle: string): SandboxManifest;
+/** The pod's spec of a recipe: its sandbox spec and its volume's size. */
+export declare function podSandboxSpecOf(recipe: EnvironmentRecipe, tenantIdle: string): PodSandboxSpec;
 /** Whether `host` (a name or `*.suffix` pattern) is inside one of the ceiling's patterns. */
 export declare function withinCeiling(host: string, ceiling: readonly string[]): boolean;
 /** Problems with a Tenant configuration, checked when an operator saves it. */