@nylorun/runtime 0.24.0-beta → 0.25.0-beta

package/dist/tenant/artifact-tool.js

@@ -1,6 +1,6 @@
 /**
- * Our engine's built-in artifact tools, of the `nylorun.artifacts` capability
- * (`sandbox/session-sandbox.ts`). The Runtime runs them itself, like the sandbox tools.
+ * Our engine's built-in artifact tools, which the Runtime pins in a session agent's `runtime`
+ * block (`sandbox/session-sandbox.ts`). The Runtime runs them itself, like the sandbox tools.
  *
  * `save_artifact` (F8.1), which comes with a session's sandbox, saves a file as an artifact of
  * its session:
@@ -9,23 +9,26 @@
  * The version commits with `artifact.created` (or `artifact.version.created`) on the session's
  * stream, carrying the turn and the tool call.
  *
- * `read_artifact` (R2b C11, Q24), which an agent with a remote MCP server or an HTTP tool has,
- * reads a text artifact of its own session in pages of at most 32 KiB, from a byte `offset`:
- * how the model reads a tool result the Runtime stored because it was too large to show
- * (`tool-results.ts`). An image is shown to a model that reads images, as a file of the result.
- * It reaches only the session's own artifacts, never a Tenant-wide one or another session's.
+ * `read_artifact` (R2b C11, Q24; every agent since protocol 12) reads a text artifact in pages of
+ * at most 32 KiB, from a byte `offset`: how the model reads a tool result the Runtime stored
+ * because it was too large to show (`tool-results.ts`), and a file of an earlier turn again, by
+ * its reference line. Another file is shown as a file of the result when the Tenant's model reads
+ * its type, and refused (`artifact.unsupported`) when it does not. It reaches the session's own
+ * artifacts and the Tenant-wide ones its messages named (`Session.fileArtifacts`), never another
+ * session's. `version` picks a version; the latest by default.
  *
  * Expected problems (no such file, too large, the Tenant's total reached, not text) are failed
  * outcomes the model sees; only infrastructure errors throw.
  */
 import { basename } from "node:path";
-import { READ_ARTIFACT_MAX_BYTES, SANDBOX_CAPABILITY_ID, } from "@nylorun/core/define";
+import { READ_ARTIFACT_MAX_BYTES } from "@nylorun/core/define";
 import { isArtifactId } from "@nylorun/core/compatibility";
 import { readArtifactLimits } from "../artifacts/config.js";
-import { MODEL_FILE_MAX_BYTES, contentTypeFor, essence, isModelImage, isText, normalizeContentType, } from "../artifacts/media-types.js";
+import { contentTypeFor, essence, isText, normalizeContentType, unreadableReason, } from "../artifacts/media-types.js";
+import { currentModelInputs } from "../model/catalog.js";
 import { uploadArtifact } from "../artifacts/service.js";
 import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
-import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { sandboxToolSpec } from "../sandbox/manager.js";
 import { sandboxWorkspaceOf } from "../sandbox/share.js";
 import { sessionOf } from "./context.js";
 import { HttpError } from "./http.js";
@@ -62,15 +65,15 @@ export async function callSaveArtifact(ctx, request, signal) {
     let bytes;
     let fileName;
     if (path !== undefined) {
-        const capability = sandboxCapabilityOf(manifestFor(s.manifest, request.agent), SANDBOX_CAPABILITY_ID, "read");
-        if (!capability)
+        const spec = sandboxToolSpec(manifestFor(s.manifest, request.agent), "read");
+        if (!spec)
             return failed("artifact.no_sandbox", "This session has no sandbox to read a path from.");
         const read = await ctx.sandbox.readBytes({
             id: workspace.ownerId,
             activeTurnId: s.activeTurnId,
             manifest: s.manifest,
             ...(workspace.environmentId === undefined ? {} : { environmentId: workspace.environmentId }),
-        }, capability, path, limits.fileBytes, signal);
+        }, spec, path, limits.fileBytes, signal);
         if (read.kind === "failed")
             return read;
         if (read.kind === "missing")
@@ -128,9 +131,12 @@ export async function callSaveArtifact(ctx, request, signal) {
 export async function callReadArtifact(ctx, request, signal) {
     const input = (request.input ?? {});
     const artifactId = typeof input.artifactId === "string" ? input.artifactId : "";
+    const wanted = input.version;
     const offset = input.offset ?? 0;
     const length = input.length ?? READ_ARTIFACT_MAX_BYTES;
     if (artifactId === "" ||
+        (wanted !== undefined &&
+            (typeof wanted !== "number" || !Number.isSafeInteger(wanted) || wanted < 1)) ||
         typeof offset !== "number" ||
         !Number.isSafeInteger(offset) ||
         offset < 0 ||
@@ -138,20 +144,25 @@ export async function callReadArtifact(ctx, request, signal) {
         !Number.isSafeInteger(length) ||
         length < 1 ||
         length > READ_ARTIFACT_MAX_BYTES)
-        return failed("artifact.invalid_input", `Give artifactId, an offset of 0 or more, and a length of 1 to ${READ_ARTIFACT_MAX_BYTES}.`);
+        return failed("artifact.invalid_input", `Give artifactId, a version of 1 or more if any, an offset of 0 or more, and a length of 1 to ${READ_ARTIFACT_MAX_BYTES}.`);
     const found = await ctx.store.tx(async (t) => {
         const s = await sessionOf(t, request.sessionId);
         if (!isArtifactId(artifactId))
             return undefined;
-        // Only an artifact of this session: never a Tenant-wide one, nor another session's.
+        // An artifact of this session, or a Tenant-wide one its messages named; never another
+        // session's.
         const artifact = await t.artifact(artifactId);
-        if (!artifact || artifact.sessionId !== s.id)
+        if (!artifact ||
+            (artifact.sessionId !== s.id &&
+                !(artifact.sessionId === null && s.fileArtifacts?.includes(artifact.id))))
             return undefined;
-        const version = await t.artifactVersion(artifact.id, artifact.latestVersion);
-        return version ? { artifact, version } : undefined;
+        const version = await t.artifactVersion(artifact.id, typeof wanted === "number" ? wanted : artifact.latestVersion);
+        return { artifact, version };
     });
     if (!found)
         return failed("artifact.not_found", `Artifact ${artifactId} is not an artifact of this session.`);
+    if (!found.version)
+        return failed("artifact.not_found", `Artifact ${artifactId} has no version ${String(wanted)}.`);
     const { artifact, version } = found;
     const about = {
         artifactId: artifact.id,
@@ -162,19 +173,29 @@ export async function callReadArtifact(ctx, request, signal) {
     };
     if (artifact.kind !== "file")
         return failed("artifact.not_text", `${artifact.name} is a folder; read_artifact reads a file.`);
-    if (isModelImage(version.contentType) && version.size <= MODEL_FILE_MAX_BYTES)
+    if (!isText(version.contentType)) {
+        // A file the Tenant's model reads goes to it beside the result (protocol 12). Without a
+        // model in the vault (a test's fake provider), text and images.
+        const inputs = (await currentModelInputs(ctx)) ?? ["text", "image"];
+        const reason = unreadableReason(version.contentType, inputs);
+        if (reason)
+            return failed("artifact.unsupported", `${artifact.name} is ${essence(version.contentType)}: ${reason}.`);
         return {
             kind: "completed",
             output: about,
             files: [
                 {
                     mediaType: version.contentType,
-                    reference: { artifactId: artifact.id, version: version.version, name: artifact.name },
+                    reference: {
+                        artifactId: artifact.id,
+                        version: version.version,
+                        name: artifact.name,
+                        size: version.size,
+                    },
                 },
             ],
         };
-    if (!isText(version.contentType))
-        return failed("artifact.not_text", `${artifact.name} is ${essence(version.contentType)}, not text; read_artifact reads text and shows images.`);
+    }
     if (offset > version.size || (offset === version.size && version.size > 0))
         return failed("artifact.invalid_input", `Offset ${offset} is past the end of ${artifact.name}, which is ${version.size} bytes.`);
     const end = Math.min(offset + length, version.size);

package/dist/tenant/commands.js

@@ -28,6 +28,7 @@ import { checkEnvironmentTurn } from "./environments.js";
 import { turnManifestOf, variantStore } from "./session.js";
 import { slimModelEffects } from "./slim.js";
 import { resolveMessageParts } from "../artifacts/parts.js";
+import { currentModelInputs } from "../model/catalog.js";
 import { endTurn, resumeTurn, startTurn } from "./turn-timing.js";
 /** A command's identity for idempotency: everything but the request id. */
 const semantic = (value) => {
@@ -42,6 +43,11 @@ export async function command(ctx, id, input, scope,
 options = {}) {
     const { store } = ctx;
     const cascadeCancelIds = [];
+    // What the Tenant's model reads, for a message that names a file (protocol 12): read before
+    // the session's transaction. Undefined without a model in the vault: nothing is refused.
+    const inputs = input.type === "message" && "parts" in input && input.parts.some((part) => part.type === "file")
+        ? await currentModelInputs(ctx)
+        : undefined;
     const response = await store.tx(async (t) => {
         const s = await lockedSession(t, id, accessOf(scope));
         const command = input;
@@ -128,9 +134,12 @@ options = {}) {
             }
         }
         else {
-            // A session opened before protocol 11 (migration 0020) keeps its history but takes no turn.
+            // A session opened before protocol 11 (migration 0020) or 13 (migration 0024) keeps its
+            // history but takes no turn.
             if (s.closedReason !== undefined)
-                fail(409, "This session was opened before protocol 11: open a new session that names an Environment.", { code: "session_closed" });
+                fail(409, s.closedReason === "protocol_11"
+                    ? "This session was opened before protocol 11: open a new session that names an Environment."
+                    : "This session was opened before protocol 13, on a manifest the Runtime no longer runs: register the agent again (manifest 7) and open a new session.", { code: "session_closed" });
             if (command.type === "message") {
                 if (!["idle", "completed", "failed", "cancelled"].includes(s.status))
                     fail(409, "Session has active or unresolved work");
@@ -147,10 +156,21 @@ options = {}) {
                     s.turnTrace = options.trace;
                 else
                     delete s.turnTrace;
-                // File parts name artifacts the caller may read; each is pinned to a version now.
+                // File parts name artifacts the caller may read; each is pinned to a version now. An
+                // agent's model must read each one (a workflow passes them on as data).
                 const parts = "parts" in command
-                    ? await resolveMessageParts(t, command.parts, id, accessOf(scope))
+                    ? await resolveMessageParts(t, command.parts, id, accessOf(scope), isWorkflowManifest(s.manifest) ? undefined : inputs)
                     : undefined;
+                if (parts && parts.refused.length > 0)
+                    fail(422, `The model does not read ${parts.refused
+                        .map((part) => `${part.name} (${part.reason})`)
+                        .join(", ")}.`, { code: "attachment_unsupported", details: { parts: parts.refused } });
+                // The files the session's messages named: `read_artifact` reads them again (protocol 12).
+                if (parts) {
+                    const named = parts.pinned.flatMap((part) => (part.type === "file" ? [part.artifactId] : []));
+                    if (named.length > 0)
+                        s.fileArtifacts = [...new Set([...(s.fileArtifacts ?? []), ...named])];
+                }
                 const data = "data" in command ? command.data : undefined;
                 if (isWorkflowManifest(s.manifest)) {
                     const input = "content" in command

package/dist/tenant/context.d.ts

@@ -50,7 +50,7 @@ export interface Session {
     manifestHash: string;
     /**
      * The hash of the definition the session was opened from; `manifestHash` differs when the
-     * Runtime pinned its own capabilities beside it (R2b C11). Absent on older sessions.
+     * Runtime pinned its `runtime` block on it (R2b C11). Absent on older sessions.
      */
     definitionHash?: string;
     /** Validated turn-manifest variants, keyed by hash (loops.md §4.2). */
@@ -115,9 +115,15 @@ export interface Session {
     sandbox?: SandboxManifest;
     /**
      * Why the session takes no new turn: `protocol_11` for a session opened before protocol 11
-     * (migration 0020). Its history stays readable.
+     * (migration 0020), `protocol_13` for one opened before protocol 13 (migration 0024). Its
+     * history stays readable.
      */
     closedReason?: string;
+    /**
+     * The artifacts the session's messages named (protocol 12): `read_artifact` reads these
+     * Tenant-wide ones beside the session's own. Absent until a message names a file.
+     */
+    fileArtifacts?: string[];
 }
 export type AuthScope = {
     kind: "application";
@@ -175,7 +181,7 @@ export interface TenantContext {
      */
     readonly mcp?: McpPool;
     /**
-     * The workspace capability (F6.2): the Tenant's SandboxManager with an in-process harness,
+     * The workspace feature (F6.2): the Tenant's SandboxManager with an in-process harness,
      * else the harness that serves workspaces (`harness-api/workspace.ts`).
      */
     readonly sandbox: WorkspacePort;
@@ -261,7 +267,7 @@ export interface TenantContext {
     abortLocal(sessionId: string, turnId?: string): void;
     /**
      * Sandbox pods (F7.2): the sandboxes service and the Runtime image pods copy the engine from.
-     * Absent without a cluster (`nylorun sandbox enable`): kind `pod` is `environment_unavailable`.
+     * Absent without a cluster (`nylorun local sandbox enable`): kind `pod` is `environment_unavailable`.
      */
     readonly pods?: TenantPods;
     /**

package/dist/tenant/effects.js

@@ -5,7 +5,7 @@ import { sessionCredentials } from "../vault/sources.js";
 import { isRemoteMcpCall } from "../harness/calls.js";
 import { isHttpToolCall } from "../gates/http-tool.js";
 import { sandboxSpecOf } from "../sandbox/share.js";
-import { withPlatformTools, withSandboxCapability } from "../sandbox/session-sandbox.js";
+import { withRuntimeTools, withSandbox } from "../sandbox/session-sandbox.js";
 import { loadSession, ownedSession, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
 import { turnManifestOf } from "./session.js";
@@ -164,8 +164,8 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         const definition = leafDefinition(workflow, body, request);
         // The tree's Environment reaches every agent in it: its sandbox, with its tools, and its vault.
         const inherited = inheritedSandbox(workflow, definition);
-        // Without one, an agent with MCP or HTTP tools still reads its stored results (R2b C11).
-        const pinned = inherited?.manifest ? inherited : platformTools(definition.manifest);
+        // Without one, the agent still gets its runtime block: read_artifact (R2b C11) and its skill tools.
+        const pinned = inherited?.manifest ? inherited : runtimeTools(definition.manifest);
         const created = {
             id: agentSessionId,
             agentId: body.agentId,
@@ -257,18 +257,16 @@ function inheritedSandbox(owner, definition) {
         return undefined;
     if (isWorkflowManifest(definition.manifest))
         return { spec };
-    const sandboxed = withSandboxCapability(definition.manifest, spec);
+    const sandboxed = withSandbox(definition.manifest, spec);
     if (!sandboxed.ok)
         throw new Error(sandboxed.message);
     return { spec, manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
 }
-/** A linked agent session's `read_artifact` without a sandbox (R2b C11); undefined for none. */
-function platformTools(manifest) {
+/** A linked agent session's `runtime` block without a sandbox (R2b C11); undefined for a workflow. */
+function runtimeTools(manifest) {
     if (isWorkflowManifest(manifest))
         return undefined;
-    const pinned = withPlatformTools(manifest);
-    if (pinned === undefined)
-        return undefined;
+    const pinned = withRuntimeTools(manifest);
     if (!pinned.ok)
         throw new Error(pinned.message);
     return { manifest: pinned.manifest, manifestHash: pinned.manifestHash };

package/dist/tenant/environment-manifests.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Environment manifests (protocol 14, D63): `/v1/environment-manifests/{name}`, named and
+ * versioned definitions of a kind of Environment, saved like agents.
+ *
+ * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged;
+ *   any other writes the next version. A version is never changed or deleted alone.
+ * - **No Environment changes.** Saving a version reaches no Environment: an Environment is made
+ *   from one version and keeps it for life (`putEnvironment`). The plan counts those behind.
+ * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
+ *   changes from the latest, every reason the Runtime would refuse it (the Tenant's limits,
+ *   missing artifacts), warnings, and how many Environments stay on older versions.
+ *   `If-Match: <version>` refuses (`412 manifest_changed`) a save whose latest version moved
+ *   since the client read it; `0` asks for a manifest that does not exist yet.
+ * - **Every client is equal** (Q12): a version records who saved it (`savedBy`), and nothing is
+ *   read-only by where it was saved from.
+ */
+import { type EnvironmentManifest, type EnvironmentManifestPlan, type EnvironmentManifestVersions, type EnvironmentManifestView, type PutEnvironmentManifestRequest, type SaveEnvironmentManifestResponse } from "@nylorun/core/contracts";
+import { type RecipeRequest } from "../sandbox/resolve.js";
+import type { AuthScope, TenantContext } from "./context.js";
+/** What an environment manifest asks of an Environment's recipe. */
+export declare function manifestRecipeRequest(manifest: EnvironmentManifest): RecipeRequest;
+/** The hash a manifest's version records: equal manifests hash the same. */
+export declare function environmentManifestHash(manifest: EnvironmentManifest): string;
+/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
+export declare function manifestChanges(before: unknown, after: unknown, path?: string): {
+    path: string;
+    from?: unknown;
+    to?: unknown;
+}[];
+/**
+ * `PUT /v1/environment-manifests/{name}`: saves `body` as manifest `name`'s next version, or
+ * answers the latest unchanged; with `dryRun`, the plan of that save and nothing saved.
+ */
+export declare function saveEnvironmentManifest(ctx: TenantContext, name: string, body: PutEnvironmentManifestRequest, scope: AuthScope, options: {
+    dryRun: true;
+    ifMatch?: number;
+}): Promise<EnvironmentManifestPlan>;
+export declare function saveEnvironmentManifest(ctx: TenantContext, name: string, body: PutEnvironmentManifestRequest, scope: AuthScope, options?: {
+    dryRun?: false;
+    ifMatch?: number;
+}): Promise<SaveEnvironmentManifestResponse>;
+/** `GET /v1/environment-manifests/{name}` (the latest) and `.../versions/{n}`. */
+export declare function getEnvironmentManifest(ctx: TenantContext, name: string, version?: number): Promise<EnvironmentManifestView>;
+/** `GET /v1/environment-manifests`: each manifest's latest version. */
+export declare function listEnvironmentManifests(ctx: TenantContext): Promise<{
+    manifests: EnvironmentManifestView[];
+}>;
+/** `GET /v1/environment-manifests/{name}/versions`: every version, newest first. */
+export declare function environmentManifestVersions(ctx: TenantContext, name: string): Promise<EnvironmentManifestVersions>;
+/**
+ * `DELETE /v1/environment-manifests/{name}`: deletes every version, refused while any Environment
+ * was made from one (`409 manifest_in_use`): the Environment names the version it runs.
+ */
+export declare function deleteEnvironmentManifest(ctx: TenantContext, name: string): Promise<{
+    name: string;
+    deleted: boolean;
+}>;

package/dist/tenant/environment-manifests.js

@@ -0,0 +1,200 @@
+/**
+ * Environment manifests (protocol 14, D63): `/v1/environment-manifests/{name}`, named and
+ * versioned definitions of a kind of Environment, saved like agents.
+ *
+ * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged;
+ *   any other writes the next version. A version is never changed or deleted alone.
+ * - **No Environment changes.** Saving a version reaches no Environment: an Environment is made
+ *   from one version and keeps it for life (`putEnvironment`). The plan counts those behind.
+ * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
+ *   changes from the latest, every reason the Runtime would refuse it (the Tenant's limits,
+ *   missing artifacts), warnings, and how many Environments stay on older versions.
+ *   `If-Match: <version>` refuses (`412 manifest_changed`) a save whose latest version moved
+ *   since the client read it; `0` asks for a manifest that does not exist yet.
+ * - **Every client is equal** (Q12): a version records who saved it (`savedBy`), and nothing is
+ *   read-only by where it was saved from.
+ */
+import {} from "@nylorun/core/contracts";
+import { hashManifest } from "@nylorun/core/compatibility";
+import { canonical } from "../store/canonical.js";
+import { resolveRecipe } from "../sandbox/resolve.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
+import { actorOf, fileErrors } from "./environments.js";
+import { fail } from "./http.js";
+/** What an environment manifest asks of an Environment's recipe. */
+export function manifestRecipeRequest(manifest) {
+    return {
+        ...(manifest.image === undefined ? {} : { image: manifest.image }),
+        ...(manifest.resources === undefined ? {} : { resources: manifest.resources }),
+        ...(manifest.storage === undefined ? {} : { storage: manifest.storage }),
+        ...(manifest.network === undefined ? {} : { network: manifest.network }),
+        ...(manifest.harness === undefined ? {} : { harness: manifest.harness }),
+        ...(manifest.lifecycle === undefined ? {} : { lifecycle: manifest.lifecycle }),
+        ...(manifest.setup === undefined ? {} : { setup: manifest.setup }),
+        ...(manifest.files === undefined ? {} : { files: manifest.files }),
+        ...(manifest.secrets === undefined ? {} : { secrets: manifest.secrets }),
+    };
+}
+/** The hash a manifest's version records: equal manifests hash the same. */
+export function environmentManifestHash(manifest) {
+    return hashManifest(manifest);
+}
+const notFound = (name, version) => fail(404, version === undefined ? `No environment manifest is named ${name}.` : `Environment manifest ${name} has no version ${version}.`, {
+    code: "manifest_not_found",
+});
+function viewOf(row, counts) {
+    return {
+        name: row.name,
+        version: row.version,
+        hash: row.hash,
+        manifest: row.body,
+        savedBy: row.savedBy,
+        createdAt: row.createdAt,
+        environments: counts.get(row.version) ?? 0,
+    };
+}
+/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
+export function manifestChanges(before, after, path = "") {
+    const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+    if (object(before) && object(after)) {
+        const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+        return keys.flatMap((key) => manifestChanges(before[key], after[key], path ? `${path}.${key}` : key));
+    }
+    if (canonical(before) === canonical(after))
+        return [];
+    return [
+        {
+            path,
+            ...(before === undefined ? {} : { from: before }),
+            ...(after === undefined ? {} : { to: after }),
+        },
+    ];
+}
+/** What a save of `manifest` should tell its saver, though it would be saved. */
+function warningsOf(ctx, manifest) {
+    const warnings = [];
+    if (manifest.image !== undefined && !manifest.image.includes("@sha256:"))
+        warnings.push({
+            code: "image_tag",
+            message: `image ${manifest.image} is a tag, not a digest: each Environment pins what its first pod pulls, so two Tenants may run different bytes.`,
+        });
+    if (manifest.kind === "pod" && !ctx.pods)
+        warnings.push({
+            code: "pods_unavailable",
+            message: "kind pod needs sandbox pods, which this Tenant does not have: an Environment made from it is refused until `nylorun local sandbox enable`.",
+        });
+    return warnings;
+}
+/** Every reason the Runtime would refuse `manifest` now: the Tenant's limits and its files. */
+async function errorsOf(t, manifest) {
+    const config = effectiveSandboxConfig(await readSandboxConfig(t));
+    const resolved = resolveRecipe(manifest.kind ?? "virtual", manifestRecipeRequest(manifest), config);
+    return [...(resolved.kind === "error" ? resolved.errors : []), ...(await fileErrors(t, manifest.files))];
+}
+export async function saveEnvironmentManifest(ctx, name, body, scope, options = {}) {
+    const { requestId: _, ...manifest } = body;
+    if (manifest.name !== name)
+        fail(400, `The manifest is named ${manifest.name}, and the path names ${name}: they must match.`);
+    const hash = environmentManifestHash(manifest);
+    const warnings = warningsOf(ctx, manifest);
+    return ctx.store.tx(async (t) => {
+        await t.lockEnvironmentManifest(name);
+        const latest = await t.environmentManifest(name);
+        if (options.ifMatch !== undefined && (latest?.version ?? 0) !== options.ifMatch)
+            fail(412, latest === undefined
+                ? `Environment manifest ${name} does not exist, and If-Match named version ${options.ifMatch}.`
+                : `Environment manifest ${name} is at version ${latest.version}, not ${options.ifMatch}: someone saved it since you read it. Read it again, or save without If-Match to replace it.`, { code: "manifest_changed", details: { latest: latest?.version ?? 0 } });
+        const unchanged = latest?.hash === hash;
+        const to = unchanged ? latest.version : (latest?.version ?? 0) + 1;
+        const counts = await t.environmentsOfManifest(name);
+        const errors = await errorsOf(t, manifest);
+        if (options.dryRun) {
+            let behind = 0;
+            for (const [version, n] of counts)
+                if (version < to)
+                    behind += n;
+            return {
+                name,
+                from: latest?.version ?? null,
+                to,
+                unchanged,
+                changes: unchanged ? [] : manifestChanges(latest?.body ?? {}, manifest),
+                warnings,
+                errors,
+                behind,
+            };
+        }
+        if (errors.length > 0)
+            fail(400, errors.join(" "));
+        if (unchanged)
+            return { manifest: viewOf(latest, counts), unchanged: true, warnings };
+        const row = {
+            name,
+            version: to,
+            body: manifest,
+            hash,
+            savedBy: { actor: actorOf(scope) },
+            createdAt: new Date().toISOString(),
+        };
+        await t.insertEnvironmentManifest(row);
+        // Its files by hash (Q6), recorded as a definition's are, for the sweep that deletes unused ones.
+        const shas = [...new Set((manifest.files ?? []).flatMap((file) => ("files" in file ? Object.values(file.files) : [])))];
+        if (shas.length > 0)
+            await t.insertDefinitionFileUses(`environment-manifest:${name}`, hash, shas);
+        return { manifest: viewOf(row, counts), unchanged: false, warnings };
+    });
+}
+/** `GET /v1/environment-manifests/{name}` (the latest) and `.../versions/{n}`. */
+export async function getEnvironmentManifest(ctx, name, version) {
+    return ctx.store.tx(async (t) => {
+        const row = (await t.environmentManifest(name, version)) ?? notFound(name, version);
+        return viewOf(row, await t.environmentsOfManifest(name));
+    });
+}
+/** `GET /v1/environment-manifests`: each manifest's latest version. */
+export async function listEnvironmentManifests(ctx) {
+    return ctx.store.tx(async (t) => {
+        const manifests = [];
+        for (const row of await t.listEnvironmentManifests())
+            manifests.push(viewOf(row, await t.environmentsOfManifest(row.name)));
+        return { manifests };
+    });
+}
+/** `GET /v1/environment-manifests/{name}/versions`: every version, newest first. */
+export async function environmentManifestVersions(ctx, name) {
+    return ctx.store.tx(async (t) => {
+        const rows = await t.environmentManifestVersions(name);
+        if (rows.length === 0)
+            notFound(name);
+        const counts = await t.environmentsOfManifest(name);
+        return {
+            name,
+            latest: rows[0].version,
+            versions: rows.map((row) => ({
+                version: row.version,
+                hash: row.hash,
+                savedBy: row.savedBy,
+                createdAt: row.createdAt,
+                environments: counts.get(row.version) ?? 0,
+            })),
+        };
+    });
+}
+/**
+ * `DELETE /v1/environment-manifests/{name}`: deletes every version, refused while any Environment
+ * was made from one (`409 manifest_in_use`): the Environment names the version it runs.
+ */
+export async function deleteEnvironmentManifest(ctx, name) {
+    return ctx.store.tx(async (t) => {
+        await t.lockEnvironmentManifest(name);
+        let made = 0;
+        for (const n of (await t.environmentsOfManifest(name)).values())
+            made += n;
+        if (made > 0)
+            fail(409, `${made} Environment(s) were made from environment manifest ${name}: delete them first, or keep the manifest.`, {
+                code: "manifest_in_use",
+                details: { environments: made },
+            });
+        return { name, deleted: (await t.deleteEnvironmentManifest(name)) > 0 };
+    });
+}