@nylorun/runtime 0.14.0-beta → 0.15.0-beta

package/dist/store/postgres/tenant.d.ts

@@ -0,0 +1,56 @@
+import type { Sql } from "postgres";
+import { type TenantEnvelope } from "@nylorun/core/contracts";
+import type { SessionStore } from "../types.js";
+import { type Queryable } from "./db.js";
+import { type Migration } from "./migrate.js";
+/** An application principal the Tenant is created with (or given later). */
+export interface InitialPrincipal {
+    id: string;
+    /** SHA-256 hex of the principal's key. */
+    credentialHash: string;
+}
+/** Who the Tenant is when the database holds none yet. */
+export interface TenantCreation {
+    /** Default: a new id (`newTenantId()`). Ignored when the Tenant exists. */
+    tenantId?: string;
+    /** Ignored when the Tenant exists. */
+    name: string;
+    /**
+     * The principals the Tenant must have, given its id (derived keys depend on it). Created
+     * with the Tenant; on later opens, the missing ones are added.
+     */
+    principals?(tenantId: string): readonly InitialPrincipal[];
+}
+export interface OpenTenantDatabaseOptions {
+    /** The pool on the Tenant's database. The store never ends it. */
+    sql: Sql;
+    create: TenantCreation;
+    /** Clock for the envelope and the principals' `createdAt`, and the store's. */
+    now?: () => Date;
+    /** Passed to the store (post-commit failures). */
+    onError?: (error: unknown) => void;
+    /** Tests only: the migrations this Runtime knows. Default: the shipped ones. */
+    migrations?: readonly Migration[];
+}
+export interface OpenedTenantDatabase {
+    store: SessionStore;
+    envelope: TenantEnvelope;
+    /** This call created the Tenant. */
+    created: boolean;
+    /** The schema versions (applied migrations) before and after. */
+    migrated: {
+        from: number;
+        to: number;
+    };
+}
+/**
+ * Migrates the database, creates its Tenant when it has none, and opens its Session Store.
+ * Throws a `TenantOpenError` with the cause when the Tenant cannot be opened (see above).
+ */
+export declare function openTenantDatabase(options: OpenTenantDatabaseOptions): Promise<OpenedTenantDatabase>;
+/**
+ * The Tenant's envelope, or undefined when the database holds no Tenant yet (no `nylorun`
+ * schema, or an empty `tenant` table). Throws `envelope-invalid` when the row does not parse.
+ * Takes the pool or a Drizzle database or transaction on it.
+ */
+export declare function readTenantEnvelope(q: Sql | Queryable): Promise<TenantEnvelope | undefined>;

package/dist/store/postgres/tenant.js

@@ -0,0 +1,154 @@
+/**
+ * The Tenant a database holds (tenancy.md §1, §4; session-store.md §2). One database is one
+ * Tenant: its state in the schema `nylorun`, its record in `nylorun_streams`, and its
+ * envelope in the one row of `nylorun.tenant`. There is no catalog.
+ *
+ * `openTenantDatabase` runs in one transaction, under the database's migration lock
+ * (`migrate.ts`), so several processes starting at once migrate and create once:
+ *
+ * 1. Refuse an old layout (`database-layout-old`): `tenant_<id>` schemas or a record keyed by
+ *    Tenant (a Runtime from before one Tenant per installation), or the `schema_version`
+ *    tables of a pre-release build of it. It is never touched: this release starts fresh.
+ * 2. Apply the missing migrations (`migrate.ts`). A database with migrations this Runtime
+ *    does not know is `schema-too-new`; a migration Postgres rejects is `migration-failed`.
+ * 3. When `nylorun.tenant` is empty, create the Tenant: its row (id, name, created time) and
+ *    its first principals. A database whose row is gone but that holds a Tenant's data
+ *    (principals, sessions, agents, vaults, keys) is `envelope-invalid`, never given a new
+ *    Tenant. Principals given later that the Tenant does not have yet are added (a derived
+ *    principal configured after the first start); existing ones are kept.
+ * 4. Read the envelope back (`envelope-invalid` when it does not parse), and open the store.
+ *
+ * A lost connection or an unavailable server says nothing about the Tenant: it is thrown as
+ * it is, never as a cause.
+ */
+import { sql } from "drizzle-orm";
+import { isTenantId, newTenantId } from "@nylorun/core/compatibility";
+import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
+import { openError, TenantOpenError } from "../../tenant/cause.js";
+import { database, driverError } from "./db.js";
+import { applyMigrations, assertCurrentLayout, isStatementError, lockMigrations, shippedMigrations, } from "./migrate.js";
+import { definitions, principals, sessions, signingKeys, TENANT_SCHEMA, tenant, vaults, } from "./schema.js";
+import { createPostgresSessionStore } from "./store.js";
+/**
+ * Migrates the database, creates its Tenant when it has none, and opens its Session Store.
+ * Throws a `TenantOpenError` with the cause when the Tenant cannot be opened (see above).
+ */
+export async function openTenantDatabase(options) {
+    const { sql: pool } = options;
+    const db = database(pool);
+    const now = options.now ?? (() => new Date());
+    const migrations = options.migrations ?? shippedMigrations();
+    let outcome;
+    try {
+        outcome = await db.transaction(async (tx) => {
+            await lockMigrations(tx);
+            await assertCurrentLayout(tx);
+            const migrated = await applyMigrations(tx, migrations);
+            const created = await ensureTenant(tx, options.create, migrated, now);
+            return { created, migrated };
+        });
+    }
+    catch (thrown) {
+        const error = driverError(thrown);
+        if (!(error instanceof TenantOpenError) && !isStatementError(error))
+            throw error;
+        // A statement of the bootstrap itself (the layout check, the Tenant row) was rejected.
+        const failure = error instanceof TenantOpenError
+            ? error
+            : openError("open-failed", `Opening the Tenant database failed: ${error.message}`);
+        // Name the Tenant when its row reads (a database newer than this Runtime, say).
+        if (failure.code !== "database-layout-old")
+            failure.envelope ??= await readTenantEnvelope(db).catch(() => undefined);
+        throw failure;
+    }
+    const envelope = await readTenantEnvelope(db);
+    if (!envelope)
+        throw openError("envelope-invalid", "The Tenant row is missing");
+    const store = createPostgresSessionStore({
+        sql: pool,
+        tenantId: envelope.id,
+        schemaVersion: migrations.length,
+        ...(options.now ? { now: options.now } : {}),
+        ...(options.onError ? { onError: options.onError } : {}),
+    });
+    return { store, envelope, ...outcome };
+}
+/**
+ * The Tenant's envelope, or undefined when the database holds no Tenant yet (no `nylorun`
+ * schema, or an empty `tenant` table). Throws `envelope-invalid` when the row does not parse.
+ * Takes the pool or a Drizzle database or transaction on it.
+ */
+export async function readTenantEnvelope(q) {
+    const db = typeof q === "function" ? database(q) : q;
+    try {
+        const [table] = await db.execute(sql `
+      SELECT to_regclass(${`${TENANT_SCHEMA}.tenant`}) IS NOT NULL AS exists`);
+        if (!table?.exists)
+            return undefined;
+        const [row] = await db
+            .select({
+            id: tenant.id,
+            name: tenant.name,
+            createdAt: tenant.createdAt,
+            updatedAt: tenant.updatedAt,
+            schemaVersion: tenant.schemaVersion,
+        })
+            .from(tenant);
+        if (!row)
+            return undefined;
+        const parsed = TenantEnvelopeSchema.safeParse(row);
+        if (!parsed.success || !isTenantId(parsed.data.id))
+            throw openError("envelope-invalid", "The Tenant row is not valid");
+        return parsed.data;
+    }
+    catch (error) {
+        throw driverError(error);
+    }
+}
+/**
+ * Creates the Tenant when there is none, and adds the principals it is missing. Records the
+ * schema version on the Tenant row when this transaction migrated.
+ */
+async function ensureTenant(tx, create, migrated, now) {
+    const [existing] = await tx.select({ id: tenant.id }).from(tenant);
+    const createdAt = now().toISOString();
+    let tenantId = existing?.id;
+    if (tenantId === undefined) {
+        const [data] = await tx.execute(sql `
+      SELECT EXISTS (SELECT 1 FROM ${principals})
+        OR EXISTS (SELECT 1 FROM ${sessions})
+        OR EXISTS (SELECT 1 FROM ${definitions})
+        OR EXISTS (SELECT 1 FROM ${vaults})
+        OR EXISTS (SELECT 1 FROM ${signingKeys}) AS held`);
+        if (data?.held)
+            throw openError("envelope-invalid", "The Tenant row is missing from a database that holds a Tenant's data: restore it from a backup");
+        tenantId = create.tenantId ?? newTenantId();
+        if (!isTenantId(tenantId))
+            throw new Error(`Invalid Tenant id: ${tenantId}`);
+        if (!create.name)
+            throw new Error("A Tenant needs a name");
+        await tx.insert(tenant).values({
+            id: tenantId,
+            name: create.name,
+            createdAt,
+            updatedAt: createdAt,
+            schemaVersion: migrated.to,
+        });
+    }
+    else if (migrated.from !== migrated.to) {
+        await tx.update(tenant).set({ schemaVersion: migrated.to });
+    }
+    for (const principal of create.principals?.(tenantId) ?? [])
+        // A principal with this id or this key already exists: it is kept as it is.
+        await tx
+            .insert(principals)
+            .values({
+            id: principal.id,
+            role: "application",
+            tokenHash: principal.credentialHash,
+            idempotencyKey: null,
+            createdAt,
+        })
+            .onConflictDoNothing();
+    return existing === undefined;
+}

package/dist/store/types.d.ts

@@ -2,8 +2,8 @@
  * The Session Store seam (architecture §12.2).
  *
  * The Session Store records what happened. It is async, transactional and
- * tenant-scoped: one `SessionStore` per Tenant. Postgres is the supported
- * implementation; `store/memory.ts` is the in-memory fake for unit tests.
+ * tenant-scoped: one `SessionStore` per Tenant. Postgres is the
+ * implementation (`store/postgres/store.ts`); tests run on it too.
  *
  * ## Invariants every implementation keeps
  *
@@ -23,7 +23,7 @@
  *    committed transactions. The sequence is also the S2 sequence number of the
  *    event in the session's stream (`sessions/<id>` in the Tenant's basin
  *    generation, `streams/basin.ts`), and the cursor is
- *    `base64url("<sessionId>:<seq>")` (see `store/cursor.ts`).
+ *    `base64url("<sessionId>:<seq>")` (see `record/cursor.ts`).
  * 4. **No external I/O inside `fn`.** No model, tool, MCP, sandbox, Restate or
  *    S2 call, and no `fetch`, runs inside a transaction. Wakes and deliveries go
  *    through `afterCommit`, and events are delivered to commit listeners after
@@ -57,8 +57,9 @@
 import type { RecordReader } from "../streams/relay/types.js";
 import type { Action, EventPayload, EventType, LiveEvent, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
+import type { ModelBudgetRow, ModelUsageRow, PrincipalRow, ToolCrossingRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
-export type DocTable = "definitions" | "sessions" | "commands" | "checkpoints" | "effects" | "actions" | "sandboxes" | "links";
+export type DocTable = "definitions" | "sessions" | "commands" | "effects" | "actions" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
 /** Session lifecycle (architecture §10.2). */
 export type SessionStatus = "idle" | "runnable" | "running" | "waiting" | "paused" | "uncertain" | "completed" | "failed" | "cancelled";
@@ -186,87 +187,29 @@ export type EndpointHealthUpdate =
     implementationVersion: string;
     manifestHash?: string;
 };
-export interface PrincipalRow {
-    id: string;
-    role: "application" | (string & {});
-    tokenHash: string;
-    idempotencyKey: string | null;
-    createdAt: string;
-}
-export interface VaultRow {
-    id: string;
-    name: string;
-    ownerUserId: string;
-    /** JSON text, or null. */
-    metadataJson: string | null;
-    createdAt: string;
-    scope: "user" | "host";
-}
-/** Envelope-encrypted secret material. Always in columns, never inside a JSON body. */
-export interface SealedSecret {
-    kekId: string;
-    nonce: Uint8Array;
-    ciphertext: Uint8Array;
-    wrappedDek: Uint8Array;
-}
-/** A Tenant signing key (subject tokens). The private key is sealed; the public JWK is not. */
-export interface SigningKeyRow extends SealedSecret {
-    id: string;
-    state: "standby" | "current" | "previous" | "revoked";
-    alg: "ES256";
-    /** JSON text of the public JWK. */
-    publicJwk: string;
-    createdAt: string;
-    activatedAt: string | null;
-    retiredAt: string | null;
-    revokedAt: string | null;
-}
-/** A publishable key (Host feature `browser-access`). Public by design. */
-export interface PublishableKeyRow {
-    id: string;
-    key: string;
-    name: string;
-    /** JSON array of allowed origins. */
-    originsJson: string;
-    createdAt: string;
-    revokedAt: string | null;
-}
-/** A subject's turn bucket (subject limits): tokens left and when they were last refilled. */
-export interface SubjectUsageRow {
-    subject: string;
-    turnTokens: number;
-    refilledAt: string;
+/**
+ * The rows of the typed tables, inferred from the tables Drizzle defines
+ * (`store/postgres/schema.ts`): a principal, a vault and its credentials (secrets sealed in
+ * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
+ * Tenant's signing keys, a subject's turn bucket, a publishable key, a model call in the usage
+ * ledger and a model budget.
+ */
+export type { ModelBudgetRow, ModelUsageRow, ToolCrossingRow, PrincipalRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
+/** Which rows of the usage ledger a total covers. */
+export interface ModelUsageQuery {
+    scope: "tenant" | "agent" | "turn";
+    /** The agent or turn id; ignored for `tenant`. */
+    id?: string;
+    /** Only rows created at or after this ISO time. */
+    since?: string;
 }
-export interface VaultCredentialRow extends SealedSecret {
-    id: string;
-    vaultId: string;
-    name: string;
-    type: "bearer" | "oauth" | "model";
-    /** JSON text of the non-secret binding (url, or provider and model). */
-    bindingJson: string;
-    expiresAt: string | null;
-    createdAt: string;
-    rotatedAt: string | null;
+export interface ModelUsageTotals {
+    calls: number;
+    tokens: number;
+    costUsd: number;
 }
 /** Fields `updateCredential` may change. */
 export type VaultCredentialPatch = Partial<Omit<VaultCredentialRow, "id" | "vaultId" | "createdAt">>;
-export interface VaultAuditRow {
-    id: string;
-    at: string;
-    actor: string;
-    action: string;
-    vaultId: string | null;
-    credentialId: string | null;
-    sessionId: string | null;
-    target: string | null;
-    outcome: string;
-}
-export interface VaultIdempotencyRow {
-    id: string;
-    bodyHash: string;
-    /** JSON text of the original response. */
-    response: string;
-}
 export interface SessionEffectFilter {
     /** Only this turn. Absent means every turn. */
     turnId?: string;
@@ -356,7 +299,7 @@ export interface Tx {
      * Locking twice in one transaction is a no-op.
      *
      * Lock order, so concurrent transactions cannot deadlock (Postgres takes row
-     * locks in statement order; the in-memory fake serializes whole transactions):
+     * locks in statement order):
      * - a linked agent (child) session is locked before its workflow (parent)
      *   session, never after it. `t.event` on a session takes its lock, so an
      *   event on a child after the parent is locked breaks the rule too. Work
@@ -519,19 +462,32 @@ export interface Tx {
     publishableKeys(): Promise<PublishableKeyRow[]>;
     /** Returns false when the key does not exist. */
     updatePublishableKey(id: string, patch: Partial<Pick<PublishableKeyRow, "originsJson" | "revokedAt">>): Promise<boolean>;
+    /** Appends a row, setting `duplicate` when one with the same `effectKey` exists; returns it. */
+    recordModelUsage(row: Omit<ModelUsageRow, "duplicate">): Promise<ModelUsageRow>;
+    modelUsageTotals(query: ModelUsageQuery): Promise<ModelUsageTotals>;
+    /** Every budget, ordered by scope, then scope id. */
+    listModelBudgets(): Promise<ModelBudgetRow[]>;
+    /** Replaces every budget with `rows`. */
+    putModelBudgets(rows: readonly ModelBudgetRow[]): Promise<void>;
+    toolCrossing(key: string): Promise<ToolCrossingRow | undefined>;
+    /** Inserts the running call's row; false when a row with `key` already exists. */
+    startToolCrossing(row: Pick<ToolCrossingRow, "key" | "hash" | "startedAt">): Promise<boolean>;
+    /** Records the call's answer. */
+    settleToolCrossing(key: string, answer: unknown, settledAt: string): Promise<void>;
+    /** Deletes rows that settled before `before`; returns how many. */
+    pruneToolCrossings(before: string): Promise<number>;
     getSetting(key: string): Promise<string | undefined>;
     putSetting(key: string, value: string): Promise<void>;
     /**
      * Deletes Tenant state by scope, in this transaction:
-     * - `sessions`: sessions, commands, checkpoints, effects, actions, links, subject turn
+     * - `sessions`: sessions, commands, effects, actions, links, subject turn
      *   buckets and the Tenant's record rows and log heads. The Tenant moves to the next basin
      *   generation and the current one is retired, so session ids it frees start again in an
      *   empty basin;
      * - `sandboxes`: sandbox records;
-     * - `all`: both, plus definitions, Action endpoints and user vaults with their
-     *   credentials. The host vault, principals, signing keys, subject epochs, publishable
-     *   keys, settings,
-     *   audit and vault idempotency rows stay.
+     * - `all`: both, plus definitions, Action endpoints, user vaults with their credentials,
+     *   the model usage ledger and the model budgets. The host vault, principals, signing keys, subject epochs,
+     *   publishable keys, settings, audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;
 }

package/dist/store/types.js

@@ -2,7 +2,6 @@ export const DOC_TABLES = [
     "definitions",
     "sessions",
     "commands",
-    "checkpoints",
     "effects",
     "actions",
     "sandboxes",

package/dist/streams/control.d.ts

@@ -5,7 +5,7 @@
  */
 import { type DurableStreams } from "./types.js";
 /** Appends a `session.cancel` signal: the process running the session's advance aborts it. */
-export declare function signalCancel(streams: DurableStreams, basin: string, sessionId: string): Promise<void>;
+export declare function signalCancel(streams: DurableStreams, basin: string, sessionId: string, turnId?: string): Promise<void>;
 /**
  * Appends a `sessions.reset` signal to the old generation's basin: every process with the
  * Tenant open moves its readers to `generation` and ends the streams of deleted sessions.

package/dist/streams/control.js

@@ -5,10 +5,14 @@
  */
 import { CONTROL_STREAM } from "./types.js";
 /** Appends a `session.cancel` signal: the process running the session's advance aborts it. */
-export async function signalCancel(streams, basin, sessionId) {
+export async function signalCancel(streams, basin, sessionId, turnId) {
     if (!sessionId)
         throw new Error("sessionId is required");
-    const signal = { type: "session.cancel", sessionId };
+    const signal = {
+        type: "session.cancel",
+        sessionId,
+        ...(turnId ? { turnId } : {}),
+    };
     await streams.append(basin, CONTROL_STREAM, [signal]);
 }
 /**

package/dist/streams/relay/types.d.ts

@@ -2,7 +2,8 @@
  * Contracts of the stream relay (Durable Streams §7): what it reads committed events from,
  * and how it reads the record back to refill and reconcile. Postgres implements both with
  * logical replication (`adapters/replication/pgoutput.ts`) and the record tables
- * (`store/postgres/record.ts`); `streams/relay/memory.ts` is the in-memory pair.
+ * (`store/postgres/record.ts`); the relay core's unit tests use an in-memory pair
+ * (`test/support/relay-record.ts`).
  */
 /** One committed row of the record: a session event and the basin generation it goes to. */
 export interface RecordRow {

package/dist/streams/relay/types.js

@@ -2,6 +2,7 @@
  * Contracts of the stream relay (Durable Streams §7): what it reads committed events from,
  * and how it reads the record back to refill and reconcile. Postgres implements both with
  * logical replication (`adapters/replication/pgoutput.ts`) and the record tables
- * (`store/postgres/record.ts`); `streams/relay/memory.ts` is the in-memory pair.
+ * (`store/postgres/record.ts`); the relay core's unit tests use an in-memory pair
+ * (`test/support/relay-record.ts`).
  */
 export {};

package/dist/streams/types.d.ts

@@ -123,6 +123,11 @@ export declare function sessionStream(sessionId: string): string;
 export interface SessionCancelSignal {
     type: "session.cancel";
     sessionId: string;
+    /**
+     * The cancelled turn. Only an advance of this turn stops, so a signal delivered late (an
+     * append retried after S2 returns) never stops a later turn. Absent: any advance stops.
+     */
+    turnId?: string;
 }
 /**
  * The Tenant was reset and moved to basin generation `generation`. Appended to the old

package/dist/tenant/advance.d.ts

@@ -8,8 +8,13 @@ import type { Session, TenantContext } from "./context.js";
 export declare function advance(ctx: TenantContext, id: string, signal: AbortSignal): Promise<AdvanceResult>;
 /**
  * Takeover (§10.5 step 2, §11.4), inside the transaction that took ownership: the dead
- * owner's `invoking` effects become `uncertain` and are never invoked again. When one belongs
+ * owner's `invoking` effects become `uncertain` and are never invoked again, except model
+ * calls when the gate recovers them (P1.2) and remote MCP calls when the Tool Gate does (F4.1
+ * G3): those stay `invoking`, and the replay re-sends them. When one belongs
  * to the active turn, the session becomes `uncertain` too, with an `effect.uncertain` event.
  * Mutates and writes `s`. Returns the effect ids it marked.
  */
-export declare function takeOver(t: Tx, s: Session): Promise<string[]>;
+export declare function takeOver(t: Tx, s: Session, options?: {
+    recoversModelCalls?: boolean;
+    recoversMcpCalls?: boolean;
+}): Promise<string[]>;