@sigrun/sigrun 0.1.4 → 0.1.6

package/dist/server/conversation-ops.js

@@ -17,24 +17,31 @@
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { accessOf, isSharing, } from "@sigrun/shared/access";
+import { extname } from "node:path";
 import { touchActivity } from "../harness/activity.js";
 import { resolveServedModelRefreshing } from "../harness/providers/refresh.js";
-import { parseSubmissionInput, resolveParts } from "./content-parts.js";
+import { isSuperuser } from "./auth/principal.js";
+import { isConfinedPath, parseSubmissionInput, resolveParts } from "./content-parts.js";
 import { CommandUsageError, expandInput, EXPANDED_ENTRY_KIND, } from "../commands/expand.js";
-import { conversationEnv, readView, SCAN_PAGE_SIZE, storeAgentChange, WHEN_BUSY_MODES, } from "./helpers.js";
-import { DEFAULT_SESSION_META, SessionMetaDoc, } from "./session-meta.js";
+import { conversationEnv, readView, SCAN_PAGE_SIZE, storeAgentChange, THINKING_LEVELS, WHEN_BUSY_MODES, } from "./helpers.js";
+import { applySessionMetaPatch, DEFAULT_SESSION_META, SessionMetaDoc, validateSessionMetaPatch, } from "./session-meta.js";
 /**
- * One client error from a conversation op: the exact 400 body the routes
- * serve (`{error: "invalid_input"}`, `{error: "invalid_field", field}`),
- * so the HTTP route maps it verbatim and the bridge caller sees the
- * same fail-loud vocabulary.
+ * One client error from a conversation op: the exact body the routes
+ * serve (`{error: "invalid_input"}`, `{error: "invalid_field", field}`)
+ * plus the HTTP status it maps to — 400 for the validation vocabulary,
+ * 404 for `no_active_submission`, 403 for the sharing gate — so one
+ * route-side mapping (`reply.code(err.status).send(err.body)`) covers
+ * every op error, and the bridge caller sees the same fail-loud
+ * vocabulary.
  */
 export class ConversationOpError extends Error {
     body;
-    constructor(body) {
+    status;
+    constructor(body, status = 400) {
         super(body.error);
         this.body = body;
         this.name = "ConversationOpError";
+        this.status = status;
     }
 }
 /** The §7.1 ceiling for `?waitMs` — a positive integer at most this. */
@@ -66,6 +73,57 @@ async function waitForSubmission(submission, waitMs) {
             clearTimeout(timer);
     }
 }
+/**
+ * Validate + resolve the `agent` selection (gateway C4): shape first
+ * (an object whose members are string arrays — non-object →
+ * `invalid_field` `agent`, a non-array member or non-string entry →
+ * `invalid_field` naming `agent.<member>`), then names against the
+ * registry snapshot (`extension(name)` for extensions; `tools()`
+ * entries' `tool` for tools — `AgentChange.tools` takes
+ * ToolRegistration OBJECTS, not names). An unknown name throws
+ * `invalid_field` naming `agent.<member>`.
+ */
+function resolveAgentSelection(ctx, agent) {
+    const snapshot = ctx.opened.registry.snapshot();
+    const resolved = {};
+    if (agent.extensions !== undefined) {
+        const extensions = [];
+        for (const name of agent.extensions) {
+            const extension = snapshot.extension(name);
+            if (extension === undefined) {
+                throw new ConversationOpError({
+                    error: "invalid_field",
+                    field: "agent.extensions",
+                });
+            }
+            extensions.push(extension);
+        }
+        resolved.extensions = extensions;
+    }
+    if (agent.tools !== undefined) {
+        // Tools may repeat across extensions (RegistrySnapshot.tools); a
+        // name selects the FIRST registered tool with that name — the same
+        // resolution `resolveAgent`'s composed map applies.
+        const byName = new Map();
+        for (const entry of snapshot.tools()) {
+            if (!byName.has(entry.tool.name))
+                byName.set(entry.tool.name, entry.tool);
+        }
+        const tools = [];
+        for (const name of agent.tools) {
+            const tool = byName.get(name);
+            if (tool === undefined) {
+                throw new ConversationOpError({
+                    error: "invalid_field",
+                    field: "agent.tools",
+                });
+            }
+            tools.push(tool);
+        }
+        resolved.tools = tools;
+    }
+    return resolved;
+}
 /**
  * Create one conversation the server-create way: ownerless ownership, the
  * boot default model plus the store's agent settings (re-read per create),
@@ -87,14 +145,47 @@ export async function createConversationOp(ctx, input = {}) {
     if (input.source !== undefined && typeof input.source !== "string") {
         throw new ConversationOpError({ error: "invalid_field", field: "source" });
     }
+    // The agent selection (gateway C4): shape fail-loud first, then name
+    // resolution against the registry snapshot (unknown names throw).
+    if (input.agent !== undefined) {
+        if (typeof input.agent !== "object" ||
+            input.agent === null ||
+            Array.isArray(input.agent)) {
+            throw new ConversationOpError({ error: "invalid_field", field: "agent" });
+        }
+        for (const member of ["extensions", "tools"]) {
+            const value = input.agent[member];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) ||
+                value.some((name) => typeof name !== "string")) {
+                throw new ConversationOpError({
+                    error: "invalid_field",
+                    field: `agent.${member}`,
+                });
+            }
+        }
+    }
+    const selection = input.agent === undefined
+        ? undefined
+        : resolveAgentSelection(ctx, input.agent);
     const conversation = await opened.harness.createConversation({
         ownership: { kind: "ownerless" },
         // A conversation with no agent model cannot generate (no_model):
         // server-created conversations start on the boot default model,
         // like the root conversation, and carry the store's
         // defaultTools/perModelThinking — re-read per create, so PATCHes
-        // reach new conversations without a restart.
-        agent: storeAgentChange(opened, opened.defaultModel),
+        // reach new conversations without a restart. The C4 `agent`
+        // selection rides alongside: `extensions`/`tools` pin the stored
+        // filters by name while the store's `modelTools` narrowing still
+        // applies (both come from storeAgentChange + the spread).
+        agent: {
+            ...storeAgentChange(opened, opened.defaultModel),
+            ...(selection?.extensions === undefined
+                ? {}
+                : { extensions: selection.extensions }),
+            ...(selection?.tools === undefined ? {} : { tools: selection.tools }),
+        },
     }, BACKGROUND_CONTEXT);
     // Creation IS activity: stamp lastActivityAt now, or the sidebar's
     // recency sort puts a never-submitted conversation at the BOTTOM of
@@ -306,3 +397,384 @@ export async function readMetaOp(opened, id) {
     return ((await opened.harness.snapshot(SessionMetaDoc, id, BACKGROUND_CONTEXT)) ??
         DEFAULT_SESSION_META);
 }
+/**
+ * Configure one conversation's model and/or thinking level (the
+ * configure route's body, verbatim): EXACTLY `model` + `thinking` — any
+ * other key is `invalid_field`; a body changing neither is
+ * `invalid_body`; `model` is `"provider/modelId"` split on the FIRST
+ * `/` (a modelId may itself contain slashes) with both parts non-empty;
+ * `thinking` must be a pi-ai level. A model change re-applies the
+ * store's `perModelThinking` override for the NEW model unless the
+ * request pins `thinking` (the store is the deployment default, the
+ * explicit field the caller's win — re-read here so a PATCH reaches
+ * later configures). Returns the configured surface projection
+ * (`{model?, thinkingLevel}`).
+ */
+export async function configureOp(ctx, conversation, body) {
+    const { opened } = ctx;
+    if (body === undefined ||
+        body === null ||
+        typeof body !== "object" ||
+        Array.isArray(body)) {
+        throw new ConversationOpError({ error: "invalid_body" });
+    }
+    const record = body;
+    const unknownKey = Object.keys(record).find((key) => key !== "model" && key !== "thinking");
+    if (unknownKey !== undefined) {
+        throw new ConversationOpError({
+            error: "invalid_field",
+            field: unknownKey,
+        });
+    }
+    const model = record.model;
+    const thinking = record.thinking;
+    if (model === undefined && thinking === undefined) {
+        // A configure that changes nothing is a client error, not a no-op.
+        throw new ConversationOpError({ error: "invalid_body" });
+    }
+    let parsedModel;
+    if (model !== undefined) {
+        if (typeof model !== "string" || !model.includes("/")) {
+            throw new ConversationOpError({ error: "invalid_field", field: "model" });
+        }
+        const slash = model.indexOf("/");
+        const provider = model.slice(0, slash);
+        const modelId = model.slice(slash + 1);
+        if (provider.length === 0 || modelId.length === 0) {
+            throw new ConversationOpError({ error: "invalid_field", field: "model" });
+        }
+        parsedModel = { provider, modelId };
+    }
+    if (thinking !== undefined &&
+        (typeof thinking !== "string" || !THINKING_LEVELS.includes(thinking))) {
+        throw new ConversationOpError({ error: "invalid_field", field: "thinking" });
+    }
+    // perModelThinking: a model change re-applies the store's override for
+    // the NEW model unless the request pins `thinking` — the map is the
+    // deployment default, the explicit field the caller's win.
+    const storeThinking = storeThinkingFor(opened, parsedModel);
+    await conversation.configure({
+        ...(parsedModel === undefined ? {} : { model: parsedModel }),
+        ...(thinking !== undefined
+            ? { thinkingLevel: thinking }
+            : storeThinking === undefined
+                ? {}
+                : { thinkingLevel: storeThinking }),
+    }, BACKGROUND_CONTEXT);
+    // Read the agent back and project the configured surface only —
+    // resolved extensions/tools/sections stay server-side.
+    const agent = await conversation.agent(BACKGROUND_CONTEXT);
+    return {
+        ...(agent.model === undefined ? {} : { model: agent.model }),
+        thinkingLevel: agent.thinkingLevel,
+    };
+}
+/** The store's per-model thinking override for `model` (re-read per call). */
+function storeThinkingFor(opened, model) {
+    if (model === undefined)
+        return undefined;
+    return opened.settings.read().perModelThinking?.[`${model.provider}/${model.modelId}`];
+}
+/**
+ * Withdraw/settle the conversation's active submission (the abort
+ * route's body, verbatim): `inspect()` is the read-only union of placed
+ * run inputs and queued inbox items (all conversations); filtered to
+ * this conversation, the LOWEST id is the active one — anything queued
+ * behind a busy conversation was admitted later and has a higher id.
+ * Nothing active is the 404 `no_active_submission`; a `not_found` abort
+ * result (the record vanished between inspect and abort) is the same
+ * honest answer. `already_placed`/`settled` still report which state
+ * the submission was found in (abort is idempotent).
+ */
+export async function abortOp(ctx, conversation) {
+    const { opened } = ctx;
+    const inspection = await opened.harness.inspect(BACKGROUND_CONTEXT);
+    // Lowest live id = oldest admitted = the placed run input over later-
+    // queued inbox items. reduce() with a first-element seed is ordering-
+    // independent (a future pi-durable inspect() ordering change cannot
+    // silently target the wrong submission); empty → undefined.
+    const active = inspection.submissions
+        .filter((s) => s.conversationId === conversation.id)
+        .reduce((min, s) => (min === undefined || s.id < min.id ? s : min), undefined);
+    if (active === undefined) {
+        throw new ConversationOpError({ error: "no_active_submission" }, 404);
+    }
+    const result = await opened.harness.abortSubmission(active.id, BACKGROUND_CONTEXT, conversation.id);
+    // `not_found` means the submission's record vanished between `inspect`
+    // and `abort` — the conversation is no longer busy, so the honest answer
+    // is the same as nothing-active.
+    if (result === "not_found") {
+        throw new ConversationOpError({ error: "no_active_submission" }, 404);
+    }
+    return { result, submissionId: active.id };
+}
+/**
+ * Admit one manual compaction (the compact route's op): `instructions`
+ * is validated here — a non-string is `invalid_field`, an empty string
+ * reads as none (the route's normalization) — and `Conversation.compact`
+ * creates the conversation-owned durable task with `reason: "manual"`:
+ * it compacts even when idle and places its summary through a write
+ * submission. Manual compaction ignores the policy's `enabled`; the
+ * task id is handed back (the SSE stream carries the `pi.compaction`
+ * entry when the summary lands). Returns the admit shape `{taskId}`;
+ * the caller owns the 202.
+ */
+export async function compactOp(ctx, conversation, instructions) {
+    // The route's instructions validation, moved in: the HTTP caller's
+    // raw value and the host's typed value take the SAME check (host
+    // inputs are typed, but the op still validates).
+    if (instructions !== undefined && typeof instructions !== "string") {
+        throw new ConversationOpError({
+            error: "invalid_field",
+            field: "instructions",
+        });
+    }
+    const normalized = instructions === "" ? undefined : instructions;
+    const taskId = await conversation.compact(normalized, BACKGROUND_CONTEXT);
+    return { taskId };
+}
+/**
+ * Fork one conversation's history at a visible entry (the fork route's
+ * body, verbatim): absent `at` defaults to the newest entry (400
+ * `empty_conversation` when the parent has no history at all); an
+ * explicit `at` must be an id the parent actually had (400
+ * `invalid_field` — never a silent empty fork). The fork inherits the
+ * parent's agent model (falling back to the boot default like create),
+ * and ONE commit resets the copied meta: name/autoName/attempts/sharing
+ * dropped, the owner re-stamped from `opts.owner` (undefined = the key
+ * removed), the autoName seeded `"<source> (fork)"` when the source had
+ * a display name, and activity stamped so the fork sorts where it
+ * happened. Returns the create shape `{id, view}`.
+ */
+export async function forkOp(ctx, conversation, opts = {}) {
+    const { opened } = ctx;
+    // The route's `at` type check, verbatim: absent body = newest entry;
+    // a present `at` must be a number (the host's typed EntryId passes).
+    if (opts.at !== undefined && typeof opts.at !== "number") {
+        throw new ConversationOpError({ error: "invalid_field", field: "at" });
+    }
+    let at = opts.at;
+    if (at === undefined) {
+        // The entries query is newest-first: the first item of the first
+        // page is the newest entry. An empty page means there is nothing
+        // to fork — the parent conversation has no history at all.
+        const page = await conversation.entries({}, 1, undefined, BACKGROUND_CONTEXT);
+        if (page.items.length === 0) {
+            throw new ConversationOpError({ error: "empty_conversation" });
+        }
+        at = page.items[0].id;
+    }
+    else {
+        // Validate `at` against the parent's own history: `fork()` accepts
+        // any EntryId, but an id this conversation never had is a client
+        // error, not a silent empty fork.
+        const page = await conversation.entries({ maxEntryId: at }, 1, undefined, BACKGROUND_CONTEXT);
+        const newest = page.items[0];
+        if (newest === undefined || newest.id !== at) {
+            throw new ConversationOpError({ error: "invalid_field", field: "at" });
+        }
+    }
+    // The fork inherits the parent's agent model — read the resolved
+    // agent, fall back to the boot default like create.
+    const agent = await conversation.agent(BACKGROUND_CONTEXT);
+    const fork = await conversation.fork(at, {
+        ownership: { kind: "ownerless" },
+        agent: { model: agent.model ?? opened.defaultModel },
+    }, BACKGROUND_CONTEXT);
+    // The fork's sidebar identity: the copied meta doc carries the
+    // source's name/autoName and the namer's attempt count; ONE commit
+    // drops all three (a fork is a new conversation, not the source's
+    // name — and it starts naming-fresh: inheriting an exhausted attempt
+    // count would make the fork forever unnameable), re-seeds it with
+    // "<source display name> (fork)" as its AUTO name when the source
+    // had one, and stamps activity so the fresh fork sorts where it
+    // happened. §5.9 (Review Focus 3): the doc copied the source's
+    // `owner` and `sharing` (fork: "current") — the SAME commit resets
+    // them: a fork is the FORKER's private copy (owner = the caller,
+    // sharing deleted; an ownerless caller means no owner at all — the
+    // key is removed).
+    const sourceMeta = await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT);
+    const sourceName = sourceMeta?.name ?? sourceMeta?.autoName;
+    await fork.commit(async (tx) => {
+        const draft = await tx.doc(SessionMetaDoc, fork.id);
+        delete draft.name;
+        delete draft.autoName;
+        delete draft.autoNameAttempts;
+        delete draft.sharing;
+        if (opts.owner === undefined)
+            delete draft.owner;
+        else
+            draft.owner = opts.owner;
+        if (sourceName !== undefined)
+            draft.autoName = `${sourceName} (fork)`;
+        draft.lastActivityAt = opened.now().toISOString();
+    }, BACKGROUND_CONTEXT);
+    const view = await readView(fork);
+    return { id: fork.id, view };
+}
+/**
+ * Patch one conversation's session meta (the meta PATCH route's body,
+ * verbatim): validate FIRST (a rejected patch never touches the doc),
+ * then — when a principal is given and the patch carries `sharing` —
+ * the owner-or-superuser gate (403 `forbidden`), then the
+ * read-modify-write merge inside ONE commit callback (concurrent
+ * patches cannot lose each other's fields; the mutation line
+ * serializes commits). The response is a FRESH post-commit snapshot —
+ * reading a newly-SET nested draft value trips chord's settled-overlay
+ * rule, so the reply must never read the mutated draft.
+ */
+export async function patchMetaOp(ctx, conversation, body, opts = {}) {
+    const { opened } = ctx;
+    // Validate FIRST — a rejected patch never touches the doc.
+    const validated = validateSessionMetaPatch(body);
+    if ("error" in validated) {
+        throw new ConversationOpError(validated);
+    }
+    // §5.9: `sharing` additionally requires the OWNER or a superuser —
+    // write access (granted by a share) must not let a recipient re-share
+    // the resource. Host callers pass no principal (trusted).
+    if (opts.principal !== undefined && validated.sharing !== undefined) {
+        const meta = await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT);
+        const isOwner = opts.principal.user !== undefined &&
+            opts.principal.user === meta?.owner;
+        if (!isOwner && !isSuperuser(opts.principal)) {
+            throw new ConversationOpError({ error: "forbidden" }, 403);
+        }
+    }
+    // Read-modify-write inside ONE commit: tx.doc materializes the doc
+    // (initial()) when absent and the patch mutates the tracked draft.
+    await conversation.commit(async (tx) => {
+        const draft = await tx.doc(SessionMetaDoc, conversation.id);
+        applySessionMetaPatch(draft, validated);
+    }, BACKGROUND_CONTEXT);
+    // The response is a FRESH snapshot, not a draft projection (see the
+    // doc comment).
+    return ((await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT)) ?? DEFAULT_SESSION_META);
+}
+// ─── Upload + raw read (gateway C4b — the files routes' ops) ───────────────
+/**
+ * The one upload-name rule (gateway C4b): no `/` or `\`, not `.` or
+ * `..`, non-empty. The single validator BOTH upload routes and the host
+ * `conversations.upload` op share — the routes pre-validate with it to
+ * keep their exact `{error: "invalid_body"}` wire bodies while the op
+ * throws the host-side `invalid_field` `name` vocabulary.
+ */
+export function validUploadName(name) {
+    return (name.length > 0 &&
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..");
+}
+/**
+ * The extension→mime map (spec §7.8): the common workspace-file
+ * extensions a client renders inline; an absent extension serves
+ * `application/octet-stream`. The KEY is the LOWERCASE extension
+ * including the dot (the lookup lowercases, so `Photo.PNG` maps too).
+ * One map for the raw route AND the host `readFile` op (its `mime`
+ * field) — never two.
+ */
+export const MIME_BY_EXTENSION = new Map([
+    [".png", "image/png"],
+    [".jpg", "image/jpeg"],
+    [".jpeg", "image/jpeg"],
+    [".gif", "image/gif"],
+    [".webp", "image/webp"],
+    [".svg", "image/svg+xml"],
+    [".pdf", "application/pdf"],
+    [".txt", "text/plain"],
+    [".md", "text/markdown"],
+    [".json", "application/json"],
+    [".html", "text/html"],
+    [".css", "text/css"],
+    [".js", "text/javascript"],
+]);
+/**
+ * Write one upload into the conversation's upload namespace (gateway
+ * C4b, the raw-upload/base64 routes' shared core): validates the NAME
+ * (the one rule — a bad name throws `invalid_field` `name`; the routes
+ * pre-validate with `validUploadName` to keep their `invalid_body`
+ * bodies byte-identical), writes `uploads/<conversationId>/<name>`
+ * through the conversation's workspace env (correct for remote
+ * workspaces), and returns the path exactly as a content part takes it.
+ * A failed env write is a server-side fault: fail loud.
+ */
+export async function uploadOp(ctx, conversation, file) {
+    if (!validUploadName(file.name)) {
+        throw new ConversationOpError({ error: "invalid_field", field: "name" });
+    }
+    // `mime` is validated (never persisted — the workspace write is the
+    // file's own bytes; a content part carries its own mime) because JS
+    // extensions cross this signature untyped at runtime: the op is the
+    // host caller's only validation point, like compactOp's instructions.
+    if (file.mime !== undefined && typeof file.mime !== "string") {
+        throw new ConversationOpError({ error: "invalid_field", field: "mime" });
+    }
+    // v1 namespaces uploads per conversation (workspaces are static and
+    // shared in v1, so un-namespaced names would clobber across
+    // conversations).
+    const path = `uploads/${conversation.id}/${file.name}`;
+    const env = await conversationEnv(ctx.opened, conversation);
+    const written = await env.writeFile(path, file.bytes, BACKGROUND_CONTEXT);
+    if (!written.ok) {
+        throw written.error;
+    }
+    return { path };
+}
+/**
+ * Read one workspace file raw (gateway C4b, the files/raw route's op):
+ * the route's confinement + cap vocabulary as op errors — non-confined/
+ * empty/`.`/directory → `invalid_path` (400), absent → `not_found`
+ * (404), over `server.maxFileReadBytes` → `too_large` (413; the HTTP
+ * route keeps its own `file_too_large` + `maxBytes` body). The read is
+ * `readBinaryFile` (the op buffers — the host caller wants the bytes;
+ * the ROUTE keeps its chunked streaming through `readFileMetaOp`'s env
+ * so it never buffers) with the extension-derived mime from the shared
+ * map (unknown extensions read as `application/octet-stream`, the raw
+ * route's own default — one behavior, never two).
+ */
+export async function readFileOp(ctx, conversation, path) {
+    const { env, mime } = await readFileMetaOp(ctx, conversation, path);
+    const read = await env.readBinaryFile(path, BACKGROUND_CONTEXT);
+    if (!read.ok) {
+        if (read.error.code === "not_found") {
+            throw new ConversationOpError({ error: "not_found" }, 404);
+        }
+        throw read.error;
+    }
+    return { bytes: read.value, mime };
+}
+/**
+ * The raw-read pre-checks (gateway C4b): the shared validation BOTH the
+ * `files/raw` route and the host `readFileOp` run — the content route's
+ * confinement rule (`isConfinedPath`; empty and `.` rejected too), the
+ * directory rejection, and the `server.maxFileReadBytes` cap — plus the
+ * size/mime the caller needs to serve the file and the conversation env
+ * it serves through (one env build per read, never two). The route maps
+ * `too_large` onto its own `file_too_large` + `maxBytes` body; every
+ * other op error maps 1:1 onto the route's existing responses.
+ */
+export async function readFileMetaOp(ctx, conversation, path) {
+    if (!isConfinedPath(path) || path.length === 0 || path === ".") {
+        throw new ConversationOpError({ error: "invalid_path" });
+    }
+    const env = await conversationEnv(ctx.opened, conversation);
+    const info = await env.fileInfo(path, BACKGROUND_CONTEXT);
+    if (!info.ok) {
+        if (info.error.code === "not_found") {
+            throw new ConversationOpError({ error: "not_found" }, 404);
+        }
+        throw info.error;
+    }
+    if (info.value.kind === "directory") {
+        throw new ConversationOpError({ error: "invalid_path" });
+    }
+    if (info.value.size > ctx.config.maxFileReadBytes) {
+        throw new ConversationOpError({ error: "too_large" }, 413);
+    }
+    return {
+        env,
+        size: info.value.size,
+        mime: MIME_BY_EXTENSION.get(extname(path).toLowerCase()) ?? "application/octet-stream",
+    };
+}

package/dist/server/gateway.js

@@ -0,0 +1,122 @@
+/**
+ * The gateway engine lifecycle (gateway C2, spec §8.0).
+ *
+ * `startGateway` wraps the ONE loaded engine (boot's
+ * `OpenedHarness.gatewayEngine` — first declarer wins) in a
+ * {@link GatewayHandle}: the serve composition creates the handle BEFORE
+ * `createServer` (threaded through `ServerContext.gateway` so the meta
+ * route reaches it) and starts it after `app.listen`.
+ *
+ * The no-engine deploy (core ships no engine) gets a degenerate handle:
+ * every method resolves, `health()` reads "ok" but is NEVER consulted —
+ * the meta route keys `health.gateway` on `opened.gatewayEngine`, not on
+ * the handle, so a deploy with channel adapters and no engine reports NO
+ * gateway health (the adapters are inert; the extensions inventory marks
+ * their rows `inert: "no gateway"`).
+ *
+ * Failure posture (the spec's Review Focus 1): a `start` rejection is
+ * logged once (`gateway: engine start failed`) and LATCHES degraded —
+ * `started` still RESOLVES (a failed engine must not wedge boot or the
+ * ordered shutdown); a throwing `health()` reads "degraded" and logs
+ * once per process (never per call). Health stays degraded until
+ * restart — recovery is a new process, never a live re-start.
+ */
+/**
+ * The degenerate no-engine handle: everything resolves, health reads
+ * "ok" (never consulted — the meta route keys on
+ * `opened.gatewayEngine`, not the handle).
+ */
+function noEngineHandle() {
+    return {
+        started: Promise.resolve(),
+        health: () => "ok",
+        stopIntake: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    };
+}
+/**
+ * The once-per-process no-engine warning flag: adapters contributed
+ * channels but no engine loaded, so the adapters are INERT (the
+ * `/v1/extensions` inventory marks their rows `inert: "no gateway"`).
+ * Logged once per process — `startGateway` may be called more than once
+ * over one boot (tests), and a deploy reboot re-runs it legitimately
+ * only on a new process.
+ */
+let noEngineWarned = false;
+/** Start the loaded gateway engine, wrapping it in the shutdown-side handle. */
+export function startGateway(opened) {
+    const binding = opened.gatewayEngine;
+    if (binding === undefined) {
+        if (opened.channelBindings.length > 0 && !noEngineWarned) {
+            noEngineWarned = true;
+            console.warn("channels contributed but no gateway engine is loaded");
+        }
+        return noEngineHandle();
+    }
+    const engine = binding.engine;
+    // The shutdown signal: `stop()` aborts the controller the engine's
+    // start ctx carried — receive loops observe it (the same contract as a
+    // `ChannelContext.signal`).
+    const abort = new AbortController();
+    const ctx = {
+        channels: opened.channelBindings.flatMap((binding) => binding.channels.map((channel) => ({
+            extension: binding.extension,
+            channel,
+        }))),
+        signal: abort.signal,
+    };
+    // Latched by a start rejection: health reads degraded until restart.
+    let startFailed = false;
+    // LAZY start: the handle is created BEFORE `createServer` (the meta
+    // route needs it at construction) but the ENGINE starts on the first
+    // `started` read — the serve composition reads it after `app.listen`
+    // (gateway C2's lifecycle: start after listen). One promise forever
+    // (re-reads join the same start).
+    let startPromise;
+    const beginStart = () => {
+        startPromise ??= engine
+            .start(ctx)
+            .catch((error) => {
+            startFailed = true;
+            console.error("gateway: engine start failed", error);
+        });
+        return startPromise;
+    };
+    // IDEMPOTENT stop, the mirror of beginStart: the FIRST call runs
+    // `abort.abort()` + `engine.stop()`; every later call (and any racing
+    // the first) joins the SAME promise — a double-stop never calls
+    // `engine.stop()` twice (the interface documents that contract).
+    let stopPromise;
+    const stopOnce = () => {
+        stopPromise ??= (async () => {
+            abort.abort();
+            await engine.stop();
+        })();
+        return stopPromise;
+    };
+    // A throwing health() logs ONCE per process — the meta route calls
+    // health per request, and a persistently-throwing engine would spam
+    // the log on every poll otherwise.
+    let healthFailureLogged = false;
+    return {
+        get started() {
+            return beginStart();
+        },
+        health: () => {
+            if (startFailed)
+                return "degraded";
+            try {
+                return engine.health();
+            }
+            catch (error) {
+                if (!healthFailureLogged) {
+                    healthFailureLogged = true;
+                    console.error("gateway: engine health failed", error);
+                }
+                return "degraded";
+            }
+        },
+        stopIntake: () => engine.stopIntake(),
+        stop: stopOnce,
+    };
+}