@nylorun/runtime 0.14.0-beta → 0.15.0-beta

package/dist/tenant/effects.js

@@ -3,9 +3,8 @@ import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowTo
 import { mayDispatchMore } from "../core/limits.js";
 import { canonical } from "../store/canonical.js";
 import { isOwnershipLost } from "../store/ownership.js";
-import { piModel } from "../model/pi-model.js";
 import { scrub } from "../redact.js";
-import { serversOf } from "../mcp/pool.js";
+import { findServer, serversOf } from "../mcp/pool.js";
 import { sandboxCapabilityOf } from "../sandbox/manager.js";
 import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
 import { withSandboxCapability } from "../sandbox/session-sandbox.js";
@@ -28,22 +27,24 @@ export async function invokeModel(ctx, request, signal, model) {
             return await model(request, signal);
         if (!ctx.useVaultModel)
             return await ctx.modelProvider(request, signal);
-        const adapter = piModel({
-            root: ctx.config.paths.home,
-            readHostModel: () => ctx.vault.readHostModel(),
-            writeHostCredential: (credential) => ctx.vault.updateHostCredential(credential),
-            ...(ctx.config.modelCall ? { settings: ctx.config.modelCall } : {}),
-        });
-        return await adapter(request.input, {
-            request: request.context.request,
+        return await ctx.modelGate.call({
+            tenantId: ctx.config.tenantId,
+            sessionId: request.sessionId,
+            turnId: request.turnId,
+            agentId: request.agentId,
+            effectId: request.effectId,
             invocationId: String(request.context.invocationId),
-            signal,
-            reportPreparedCall() { },
-        });
+            call: request.input,
+        }, signal);
     }
     catch (error) {
-        if (signal.aborted)
+        if (signal.aborted) {
+            // A call that outlives this process stops only when told to: on a user cancel. After a
+            // shutdown or a lost lease the next owner re-sends it and picks up its outcome (P1.2).
+            if (!model && ctx.useVaultModel && abortKind(signal) === "cancel" && ctx.modelGate.cancel)
+                await ctx.modelGate.cancel({ tenantId: ctx.config.tenantId, effectId: request.effectId });
             throw error;
+        }
         return classifyThrown(error);
     }
 }
@@ -68,6 +69,32 @@ async function linkedOutcome(t, effect, agent) {
         },
     };
 }
+/**
+ * True when this Tenant's remote MCP calls outlive the process that sent them (the gates
+ * service, F4.1 G3): after a takeover or a shutdown, the journaled call is re-sent and joins
+ * the running call or gets its answer, instead of becoming `uncertain`.
+ */
+export function recoversMcpCalls(ctx) {
+    return ctx.toolGate.recovers === true;
+}
+/** True when `request` calls a tool of a remote (`streamable-http` or `sse`) MCP server. */
+export function isRemoteMcpEffect(s, request) {
+    if (request.kind !== "tool")
+        return false;
+    const tool = mcpToolOf(s, request);
+    if (!tool)
+        return false;
+    const declared = findServer(s.manifest, tool.agentId, tool.capabilityId, tool.serverName);
+    return declared !== undefined && declared.server.type !== "stdio";
+}
+/**
+ * True when this Tenant's vault-backed model calls outlive the process that sent them (the
+ * gates service, P1.2): after a takeover or a shutdown, the journaled call is re-sent and joins
+ * the running call or gets its outcome, instead of becoming `uncertain`.
+ */
+export function recoversModelCalls(ctx) {
+    return ctx.useVaultModel && ctx.modelGate.recovers === true;
+}
 /**
  * What an effect's journal row must match on replay. A delegation's context carries only the
  * parent's tool call id, for its events; rows journaled before it existed still match.
@@ -100,6 +127,22 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
                 throw new Error("Effect identity request drift");
             if (existing.status === "completed")
                 return resolved({ status: "completed", outcome: existing.outcome });
+            // A model call its previous owner left running at the gate: re-send it, same key and
+            // request, to join it or collect its outcome.
+            if (existing.status === "invoking" &&
+                request.kind === "model" &&
+                recoversModelCalls(ctx))
+                return { kind: "invoke", invoke: "model", journaled: existing.request };
+            // A remote MCP call its previous owner left running at the gate: the same, by effect id.
+            if (existing.status === "invoking" &&
+                recoversMcpCalls(ctx) &&
+                isRemoteMcpEffect(s, existing.request))
+                return {
+                    kind: "invoke",
+                    invoke: "mcp",
+                    journaled: existing.request,
+                    remote: true,
+                };
             if (request.kind === "agent" && existing.status === "pending") {
                 const agentSessionId = existing.agentSessionId;
                 if (agentSessionId) {
@@ -159,6 +202,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             return {
                 kind: "invoke",
                 invoke: mcpTool ? "mcp" : sandboxTool ? "sandbox" : "model",
+                ...(mcpTool && isRemoteMcpEffect(s, request) ? { remote: true } : {}),
             };
         const tool = request.kind === "tool"
             ? pinnedTool(agentManifest, request.capabilityId, request.toolName)
@@ -216,10 +260,10 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
     try {
         // The intent is committed; the call itself runs outside any transaction.
         const value = invoke === "mcp"
-            ? await callMcpTool(ctx, request)
+            ? await callMcpTool(ctx, journaled.journaled ?? request, abortOn(signal, journaled.remote && recoversMcpCalls(ctx) ? ["cancel", "shutdown"] : ["cancel"]))
             : invoke === "sandbox"
                 ? await callSandboxTool(ctx, request, signal)
-                : await invokeModel(ctx, request, signal, segment.model);
+                : await invokeModel(ctx, journaled.journaled ?? request, signal, segment.model);
         return await store.tx(async (t) => {
             const s = await ownedSession(t, lease, request.sessionId);
             // Only a cancel discards an outcome in hand (§10.7). After any other abort (shutdown,
@@ -256,6 +300,18 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
         // A lost epoch writes nothing: the new owner decides what the effect became.
         if (isOwnershipLost(error))
             throw error;
+        // A shutdown leaves a model call running at the gate, still `invoking`: the next advance
+        // re-sends it (P1.2). The segment stops for the shutdown as usual.
+        if (invoke === "model" && recoversModelCalls(ctx) && abortKind(signal) === "shutdown")
+            throw error;
+        // The same for a remote MCP call at the Tool Gate (G3). A user cancel stops it there: a
+        // keyed call outlives the request that sent it.
+        if (invoke === "mcp" && journaled.remote && recoversMcpCalls(ctx)) {
+            if (abortKind(signal) === "shutdown")
+                throw error;
+            if (abortKind(signal) === "cancel" && ctx.toolGate.cancel)
+                await ctx.toolGate.cancel({ tenantId: ctx.config.tenantId, effectId: request.effectId });
+        }
         await store.tx(async (t) => {
             const s = request.sessionId === lease.sessionId
                 ? await t.assertEpoch(request.sessionId, lease.epoch)
@@ -544,7 +600,25 @@ export async function prepareMcp(ctx, lease, signal) {
         await t.put("sessions", id, current);
     });
 }
-async function callMcpTool(ctx, request) {
+/**
+ * A signal that follows `signal` only for the abort kinds in `kinds`. An MCP call stops on a
+ * cancel; at the Tool Gate it also stops waiting on a shutdown, since the gate keeps the call
+ * for the next owner. Otherwise a shutdown or a deadline lets the call finish and records it,
+ * so the next advance replays it.
+ */
+function abortOn(signal, kinds) {
+    const controller = new AbortController();
+    const follow = () => {
+        if (kinds.includes(abortKind(signal)))
+            controller.abort(signal.reason);
+    };
+    if (signal.aborted)
+        follow();
+    else
+        signal.addEventListener("abort", follow, { once: true });
+    return controller.signal;
+}
+async function callMcpTool(ctx, request, signal) {
     const s = await loadSession(ctx, request.sessionId);
     const tool = mcpToolOf(s, request);
     if (!tool)
@@ -558,6 +632,8 @@ async function callMcpTool(ctx, request) {
         args: request.input,
         manifest: s.manifest,
         pluginRoots: s.pluginRoots ?? {},
+        effectId: request.effectId,
+        signal,
     });
 }
 /**

package/dist/tenant/ephemeral.d.ts

@@ -1,17 +1,23 @@
-import type { PostgresClient } from "../store/postgres/connect.js";
+import { type PostgresClient } from "../store/postgres/connect.js";
 import type { Logger, TenantModelConfig } from "./types.js";
 export interface StartEphemeralRuntimeOptions {
     /**
-     * Absolute Host root for `host.json`, the admin key and each Tenant's files (vault key,
+     * Absolute Host root for `host.json`, the admin key and the Tenant's files (vault key,
      * home, sandboxes). Caller creates any temporary directory. Session data never lands here.
      */
     hostRoot: string;
+    /** The Tenant's id when the database holds no Tenant yet. Default: a new id. */
     tenantId?: string;
+    /** The Tenant's name when the database holds no Tenant yet. Default `ephemeral`. */
     name?: string;
+    /** An application key for an application principal of the Tenant. Default: a new key. */
     applicationKey?: string;
     adminKey?: string;
     principalId?: string;
-    /** SHA-256 of a derived Studio key; registers principal `studio`. */
+    /**
+     * SHA-256 of the Studio key; registers principal `studio` with it. Default: the key the
+     * admin key derives (`deriveStudioToken` in `@nylorun/admin`).
+     */
     studioCredentialHash?: string;
     /** Allowlisted baseline for childEnv (e.g. PATH). Never read from ambient here. */
     baseline?: Readonly<Record<string, string>>;
@@ -25,10 +31,12 @@ export interface StartEphemeralRuntimeOptions {
     operatorListener?: boolean;
     logger?: Logger;
     /**
-     * A Postgres pool: Tenants become schemas in it (`store-pg.ts`) instead of living in memory.
-     * The caller ends the pool; the schemas stay.
+     * The Postgres database of the Tenant (one Tenant per database): a pool, which the caller
+     * ends, or a URL, for which the Runtime opens a pool and ends it on `close()`. A database
+     * that already holds a Tenant serves that one. The data stays after `close()`; a test drops
+     * its database.
      */
-    database?: PostgresClient;
+    database: PostgresClient | string;
 }
 export interface EphemeralRuntime {
     url: string;
@@ -42,7 +50,8 @@ export interface EphemeralRuntime {
     close(): Promise<void>;
 }
 /**
- * Private Host on port 0 with one Tenant (D9 / A19). Not durable (see the module comment).
+ * Private Host on port 0 serving one Tenant (D9 / A19). Durable only in its database (see the
+ * module comment).
  * Exported from `@nylorun/runtime` and `@nylorun/runtime/core`.
  */
 export declare function startEphemeralRuntime(options: StartEphemeralRuntimeOptions): Promise<EphemeralRuntime>;

package/dist/tenant/ephemeral.js

@@ -1,29 +1,28 @@
 /**
- * `startEphemeralRuntime`: a private, in-process Host on port 0 with one Tenant, for tests and
- * embeds that need the Runtime's HTTP API without the Docker stack. Nothing in it is durable:
- * its Tenants live in memory (the memory Session Store and memory Durable Streams) and are gone
- * after `close()`, or in the Postgres database a test passes. Scheduling is the in-process
- * execution each Tenant starts for itself.
+ * `startEphemeralRuntime`: a private, in-process Host on port 0 serving one Tenant, for tests
+ * and embeds that need the Runtime's HTTP API without Restate and S2. Its Tenant is the one
+ * the Postgres database the caller passes holds (`store/postgres/tenant.ts`), created there on
+ * first start through the same path as a Host's; there is no in-memory Session Store. The rest
+ * is not durable: Durable Streams are in memory and gone after `close()`, and scheduling is
+ * the in-process execution the Tenant starts for itself.
  *
- * It is not the temporary Tenant the smoke checks use (scripts/lib/temporary-tenant.mjs):
- * that one is created on the running stack, with the Tenant-level fixture model
- * (`model-setting.ts`), and deleted afterwards.
+ * The smoke checks do not use it: they reset the Tenant of a temporary Docker stack and seed
+ * the Tenant-level fixture model (`model-setting.ts`, scripts/lib/stack-tenant.mjs).
  */
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import { newTenantId } from "@nylorun/core/compatibility";
-import { hashToken, mintBearerToken } from "../core/bearer.js";
+import { mintBearerToken } from "../core/bearer.js";
 import { createHost } from "../host/create-host.js";
 import { createKekFile } from "../vault/kek.js";
-import { MemorySessionStore } from "../store/memory.js";
 import { createTenantModule } from "./module.js";
-import { createMemoryTenantStore } from "./store-memory.js";
-import { createPostgresTenantStore } from "./store-pg.js";
+import { createPostgresTenantOpener } from "./store-pg.js";
+import { createPostgresClient, } from "../store/postgres/connect.js";
 import { MemoryStreams } from "../streams/memory.js";
 import { createTenantLogger } from "./logger.js";
 import { hostPaths, tenantPaths } from "./paths.js";
-import { bootstrapPrincipal } from "./principals.js";
+import { hostPrincipals } from "./principals.js";
 import { openTenantRuntime } from "./runtime.js";
 const nodeRequire = createRequire(import.meta.url);
 function coreVersion() {
@@ -38,70 +37,8 @@ function newHostId() {
     return `host_${newTenantId().slice(3)}`;
 }
 /**
- * A Tenant store whose Tenants live in memory: one memory Session Store per Tenant, created
- * with its bootstrap principals, kept across closes and re-opens, dropped on delete.
- */
-function memoryTenants(options) {
-    const stores = new Map();
-    const inner = createMemoryTenantStore({
-        configFor: options.configFor,
-        logger: options.logger,
-        openRuntime: async (config) => {
-            const store = stores.get(config.tenantId);
-            if (!store)
-                throw new Error(`Tenant ${config.tenantId} has no Session Store`);
-            return openTenantRuntime(config, {
-                createKekIfMissing: true,
-                streams: options.streams,
-                store: kept(store),
-                envelope: await inner.readEnvelope(config.tenantId),
-            });
-        },
-    });
-    const store = {
-        ...inner,
-        async create(envelope, bootstrap) {
-            const created = await inner.create(envelope, bootstrap);
-            if (created === "created") {
-                const sessions = new MemorySessionStore({ tenantId: envelope.id });
-                await sessions.tx((t) => bootstrapPrincipal(t, bootstrap));
-                stores.set(envelope.id, sessions);
-            }
-            return created;
-        },
-        async trash(id, now) {
-            await inner.trash(id, now);
-            await stores.get(id)?.close();
-            stores.delete(id);
-        },
-        async removePartial(id) {
-            await inner.removePartial(id);
-            await stores.get(id)?.close();
-            stores.delete(id);
-        },
-    };
-    return {
-        store,
-        async close() {
-            for (const sessions of stores.values())
-                await sessions.close();
-            stores.clear();
-        },
-    };
-}
-/** The Tenant closes its store on close; a memory store must outlive that for a re-open. */
-function kept(store) {
-    return {
-        tenantId: store.tenantId,
-        tx: (fn) => store.tx(fn),
-        onCommit: (listener) => store.onCommit(listener),
-        record: () => store.record(),
-        health: () => store.health(),
-        close: async () => { },
-    };
-}
-/**
- * Private Host on port 0 with one Tenant (D9 / A19). Not durable (see the module comment).
+ * Private Host on port 0 serving one Tenant (D9 / A19). Durable only in its database (see the
+ * module comment).
  * Exported from `@nylorun/runtime` and `@nylorun/runtime/core`.
  */
 export async function startEphemeralRuntime(options) {
@@ -109,8 +46,6 @@ export async function startEphemeralRuntime(options) {
     const paths = hostPaths(hostRoot);
     mkdirSync(paths.home, { recursive: true });
     mkdirSync(paths.tmp, { recursive: true });
-    mkdirSync(paths.tenants, { recursive: true });
-    mkdirSync(paths.trash, { recursive: true });
     const hostId = newHostId();
     const adminKey = options.adminKey ?? randomBytes(32).toString("hex");
     const hostConfig = {
@@ -132,7 +67,7 @@ export async function startEphemeralRuntime(options) {
     const baseline = options.baseline ?? {};
     const model = options.model ?? { kind: "scripted", output: "ok" };
     const configFor = (tenantId) => {
-        const tenant = tenantPaths(hostRoot, tenantId);
+        const tenant = tenantPaths(hostRoot);
         // A seeded `sandbox.backend` setting overrides this when the Tenant opens.
         const sandboxBackend = options.sandboxBackend ?? "virtual";
         return {
@@ -153,13 +88,26 @@ export async function startEphemeralRuntime(options) {
         };
     };
     const streams = new MemoryStreams();
-    const memory = options.database
-        ? undefined
-        : memoryTenants({ configFor, streams, logger });
-    const store = options.database
-        ? createPostgresTenantStore({
+    const ownPool = typeof options.database === "string"
+        ? createPostgresClient(options.database)
+        : undefined;
+    const applicationKey = options.applicationKey ?? mintBearerToken();
+    const principalId = options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
+    const module = createTenantModule({
+        open: createPostgresTenantOpener({
             hostRoot,
-            sql: options.database,
+            sql: ownPool ?? options.database,
+            create: {
+                tenantId: options.tenantId ?? newTenantId(),
+                name: options.name ?? "ephemeral",
+                principals: hostPrincipals({
+                    adminKey,
+                    application: { principalId, key: applicationKey },
+                    ...(options.studioCredentialHash
+                        ? { studioCredentialHash: options.studioCredentialHash }
+                        : {}),
+                }),
+            },
             configFor,
             logger,
             openRuntime: (config, opened) => openTenantRuntime(config, {
@@ -167,45 +115,24 @@ export async function startEphemeralRuntime(options) {
                 streams,
                 ...opened,
             }),
-        })
-        : memory.store;
-    const module = createTenantModule({
-        store,
+        }),
         logger,
-        onDeleted: (tenantId) => streams.deleteTenant(tenantId),
     });
     let host;
     /** Closes what was opened, in reverse order; `close()` and a failed start share it. */
     const release = async () => {
         await host?.close();
         await module.close();
-        await memory?.close();
         await streams.close();
+        await ownPool?.end({ timeout: 5 });
         if (!options.retainRoot)
             rmSync(hostRoot, { recursive: true, force: true });
     };
     let tenantId;
-    let applicationKey;
-    let principalId;
     try {
-        await module.start();
-        tenantId = options.tenantId ?? newTenantId();
-        applicationKey = options.applicationKey ?? mintBearerToken();
-        principalId =
-            options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
-        const credentialHash = hashToken(applicationKey);
-        await module.create({
-            tenantId,
-            name: options.name ?? "ephemeral",
-            principalId,
-            credentialHash,
-            idempotencyKey: `ephemeral-${tenantId}`,
-            ...(options.studioCredentialHash
-                ? { studioCredentialHash: options.studioCredentialHash }
-                : {}),
-        });
         // KEK for first vault write; openTenantRuntime also creates when hooks allow.
-        const kekPath = tenantPaths(hostRoot, tenantId).kek;
+        const kekPath = tenantPaths(hostRoot).kek;
+        mkdirSync(tenantPaths(hostRoot).root, { recursive: true, mode: 0o700 });
         if (!existsSync(kekPath))
             createKekFile(kekPath);
         host = createHost({
@@ -220,7 +147,14 @@ export async function startEphemeralRuntime(options) {
                 ? { operator: { host: "127.0.0.1", port: 0 } }
                 : {}),
         });
+        // Opens the Tenant: creates it in the database first when it holds none.
         await host.listen();
+        const tenant = module.tenant();
+        if (tenant.state !== "open" || !tenant.id)
+            throw new Error(tenant.cause
+                ? `The Tenant could not be opened (${tenant.cause.code}): ${tenant.cause.message}`
+                : "The Tenant could not be opened: its database is unavailable");
+        tenantId = tenant.id;
     }
     catch (error) {
         await release().catch((cleanup) => logger.warn("ephemeral runtime cleanup failed", {

package/dist/tenant/history.d.ts

@@ -0,0 +1,64 @@
+/**
+ * One history (blueprint P0.3): the own loop's model-facing transcript is a fold of the
+ * session's record, not a copy on the session row.
+ *
+ * - **Write.** After a segment that keeps the engine's state (a rollover, or a settle that is
+ *   not a failure), the Runtime appends `transcript.updated` events: an edit from the
+ *   transcript the segment started with to the one the engine returned (`transcriptUpdates`).
+ *   Normal steps only append; compaction replaces the prefix, so its edit is a snapshot.
+ * - **Fold.** `foldTranscript` applies the edits in order. `turn.cancelled` and `turn.failed`
+ *   restore the transcript from before that turn's first edit, as cancel and failure restore
+ *   `turnStartState`.
+ * - **Lean rows.** The session row stores the engine state with an empty transcript
+ *   (`leanState`). `runSegment` folds the record from `Session.history.from` and hands the
+ *   engine the full transcript (`withTranscript`).
+ * - **Shadow mode** (on in the runtime's tests, `test/setup/transcript-shadow.ts`) keeps the
+ *   transcript on the row too and checks the fold against it at every segment start.
+ */
+import type { LiveEvent } from "@nylorun/core/contracts";
+/** The payload of one `transcript.updated` event. */
+export interface TranscriptUpdate {
+    keep: number;
+    entries: unknown[];
+    length: number;
+}
+/** Where a session's fold starts. */
+export interface SessionHistory {
+    /** The fold reads the record from this seq: a snapshot at or before the turn's start. */
+    from: number;
+    /** The latest snapshot (`keep: 0`), which `from` moves to when the next turn starts. */
+    snapshot?: number;
+}
+/** An edit's entries are split so each event stays well under S2's 1 MiB record limit. */
+export declare const CHUNK_BYTES: number;
+/** Shadow mode: keep the transcript on the session row and check the fold against it. */
+export declare function transcriptShadow(): boolean;
+/** Tests switch shadow mode off to exercise lean rows. Returns the previous setting. */
+export declare function setTranscriptShadow(on: boolean): boolean;
+export declare class TranscriptFoldError extends Error {
+    constructor(message: string);
+}
+/** The fold and the transcript on the row differ (shadow mode only). */
+export declare class TranscriptParityError extends Error {
+    constructor(sessionId: string, at: number, folded: number, stored: number);
+}
+/** The engine state's transcript, or none. */
+export declare function transcriptOf(state: unknown): unknown[];
+/**
+ * The edits from `before` to `after`, split into chunks of at most `CHUNK_BYTES` of entries.
+ * Empty when nothing changed.
+ */
+export declare function transcriptUpdates(before: readonly unknown[], after: readonly unknown[], chunkBytes?: number): TranscriptUpdate[];
+/** Applies one edit. Throws `TranscriptFoldError` when it does not fit the transcript. */
+export declare function applyUpdate(transcript: readonly unknown[], update: TranscriptUpdate): unknown[];
+/**
+ * Folds a session's events, from the start of its record or from a snapshot, into the
+ * transcript the engine resumes from.
+ */
+export declare function foldTranscript(events: Iterable<Pick<LiveEvent, "type" | "turnId" | "payload">>): unknown[];
+/** `state` with an empty transcript (what the session row stores outside shadow mode). */
+export declare function leanState<T>(state: T): T;
+/** `state` with `transcript` (what the engine runs on). */
+export declare function withTranscript<T>(state: T, transcript: readonly unknown[]): T;
+/** In shadow mode, checks the fold against the transcript the row kept. */
+export declare function checkParity(sessionId: string, folded: readonly unknown[], stored: readonly unknown[]): void;

package/dist/tenant/history.js

@@ -0,0 +1,120 @@
+/** An edit's entries are split so each event stays well under S2's 1 MiB record limit. */
+export const CHUNK_BYTES = 256 * 1024;
+let shadow = false;
+/** Shadow mode: keep the transcript on the session row and check the fold against it. */
+export function transcriptShadow() {
+    return shadow;
+}
+/** Tests switch shadow mode off to exercise lean rows. Returns the previous setting. */
+export function setTranscriptShadow(on) {
+    const previous = shadow;
+    shadow = on;
+    return previous;
+}
+export class TranscriptFoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TranscriptFoldError";
+    }
+}
+/** The fold and the transcript on the row differ (shadow mode only). */
+export class TranscriptParityError extends Error {
+    constructor(sessionId, at, folded, stored) {
+        super(`Session ${sessionId}: the folded transcript differs from the stored one at entry ${at}` +
+            ` (folded ${folded} entries, stored ${stored})`);
+        this.name = "TranscriptParityError";
+    }
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** The engine state's transcript, or none. */
+export function transcriptOf(state) {
+    const transcript = state?.transcript;
+    return Array.isArray(transcript) ? transcript : [];
+}
+/**
+ * The edits from `before` to `after`, split into chunks of at most `CHUNK_BYTES` of entries.
+ * Empty when nothing changed.
+ */
+export function transcriptUpdates(before, after, chunkBytes = CHUNK_BYTES) {
+    let keep = 0;
+    while (keep < before.length && keep < after.length && same(before[keep], after[keep]))
+        keep += 1;
+    if (keep === before.length && keep === after.length)
+        return [];
+    const added = after.slice(keep);
+    if (added.length === 0)
+        return [{ keep, entries: [], length: keep }];
+    const updates = [];
+    let chunk = [];
+    let bytes = 0;
+    let base = keep;
+    const flush = () => {
+        updates.push({ keep: base, entries: chunk, length: base + chunk.length });
+        base += chunk.length;
+        chunk = [];
+        bytes = 0;
+    };
+    for (const entry of added) {
+        const size = JSON.stringify(entry).length;
+        if (chunk.length > 0 && bytes + size > chunkBytes)
+            flush();
+        chunk.push(entry);
+        bytes += size;
+    }
+    flush();
+    return updates;
+}
+/** Applies one edit. Throws `TranscriptFoldError` when it does not fit the transcript. */
+export function applyUpdate(transcript, update) {
+    if (update.keep > transcript.length)
+        throw new TranscriptFoldError(`transcript.updated keeps ${update.keep} entries of ${transcript.length}`);
+    const next = [...transcript.slice(0, update.keep), ...update.entries];
+    if (next.length !== update.length)
+        throw new TranscriptFoldError(`transcript.updated should give ${update.length} entries, not ${next.length}`);
+    return next;
+}
+/**
+ * Folds a session's events, from the start of its record or from a snapshot, into the
+ * transcript the engine resumes from.
+ */
+export function foldTranscript(events) {
+    let transcript = [];
+    // The transcript before the current turn's first edit: what a cancel or failure restores.
+    let turn;
+    for (const event of events) {
+        if (event.type === "transcript.updated") {
+            if (!turn || turn.id !== event.turnId)
+                turn = { id: event.turnId, before: transcript };
+            transcript = applyUpdate(transcript, event.payload);
+        }
+        else if (event.type === "turn.cancelled" || event.type === "turn.failed") {
+            if (turn && turn.id === event.turnId)
+                transcript = turn.before;
+            turn = undefined;
+        }
+        else if (event.type === "turn.completed")
+            turn = undefined;
+    }
+    return transcript;
+}
+/** `state` with an empty transcript (what the session row stores outside shadow mode). */
+export function leanState(state) {
+    if (shadow || !state || transcriptOf(state).length === 0)
+        return state;
+    return { ...state, transcript: [] };
+}
+/** `state` with `transcript` (what the engine runs on). */
+export function withTranscript(state, transcript) {
+    if (!state)
+        return state;
+    return { ...state, transcript: [...transcript] };
+}
+/** In shadow mode, checks the fold against the transcript the row kept. */
+export function checkParity(sessionId, folded, stored) {
+    if (!shadow)
+        return;
+    const length = Math.max(folded.length, stored.length);
+    for (let i = 0; i < length; i += 1)
+        if (!same(folded[i], stored[i]))
+            throw new TranscriptParityError(sessionId, i, folded.length, stored.length);
+}

package/dist/tenant/model-setting.d.ts

@@ -2,8 +2,8 @@
  * The Tenant-level fixture model: Tenant setting `model.fixture`, seeded with
  * `fixtureModel: true` (`PUT /v1/tenant/config/seed`, Host feature `tenant-fixture-model`).
  * A Tenant with it answers every model call with the Runtime's deterministic fixture model
- * (`core/provider.ts` `toolFixtureModel`) instead of its configured model, whatever the Host
- * uses for other Tenants. Temporary test Tenants seed it (scripts/lib/temporary-tenant.mjs).
+ * (`core/provider.ts` `toolFixtureModel`) instead of its configured model. Smoke checks seed
+ * it (scripts/lib/stack-tenant.mjs).
  *
  * The setting is read once per advance, in a transaction the advance makes anyway, so a Tenant
  * seeded on another node takes it at its next advance.