@nylorun/runtime 0.17.0-beta → 0.19.1-beta

package/dist/store/postgres/schema.js

@@ -1,39 +1,3 @@
-/**
- * The tables of a Tenant database (session-store.md §2–§3): the source drizzle-kit generates
- * the migrations from (`drizzle/`, `CONTRIBUTING.md` "Adding a migration") and the query
- * builder's view of them. Column names are the camelCase keys in snake_case (`casing:
- * "snake_case"`, here, in `db.ts` and in `drizzle.config.ts`).
- *
- * - `nylorun` holds the Tenant's state: the one `tenant` row, the document tables, Action
- *   endpoints, principals, vaults and credentials, signing keys, settings, the model usage
- *   ledger, the model budgets, the Tool Gate's crossings and file artifacts with their versions.
- * - `nylorun_streams` holds the record (Durable Streams §6): `session_events`,
- *   `session_log_heads` and the relay's `relay_slots`. The relay's publication is custom SQL
- *   (`drizzle/0002_stream_relay.sql`).
- *
- * What the columns keep:
- *
- * - **Bodies are `json`, not `jsonb`** (`jsonText`), written as the text `JSON.stringify`
- *   wrote, so every string round-trips exactly, key order included. `jsonb` rejects the
- *   escapes `\u0000` (`22P05`) and unpaired surrogates (`\ud800`), which tool output can
- *   contain; `json` stores the text verbatim and checks only its syntax.
- * - **Indexed fields of a body are stored generated columns** read through
- *   `nylorun.doc(body)` (custom SQL, `drizzle/0000_foundation.sql`), which casts to `jsonb`
- *   after replacing those two escapes with `\ufffd`: the body is untouched, and only an indexed
- *   field that itself contained one (never an id, status or timestamp) would see U+FFFD.
- *   Queries never apply `->`/`->>` to a `json` body (Postgres de-escapes the whole text and
- *   fails on the same escapes); they read the generated columns.
- * - **Ids and timestamps compared as text are `COLLATE "C"`** (`textC`), so they order by code
- *   point whatever the database's collation.
- * - **Timestamps are ISO text**, except the session lease `owner_expires_at` and the record's
- *   `committed_at` (`timestamptz`).
- * - **Sealed secrets are `bytea` columns** (`bytes`), never inside a JSON body.
- * - Sessions carry the store-managed ownership columns (`owner`, `epoch`,
- *   `owner_expires_at`), which are never in `body`.
- *
- * Columns are listed in the order the tables have them, so a database created by these
- * migrations and one created by the hand-written migrations they replaced dump the same.
- */
 import { sql } from "drizzle-orm";
 import { bigint, boolean, check, customType, doublePrecision, foreignKey, index, integer, pgSchema, primaryKey, text, timestamp, uniqueIndex, } from "drizzle-orm/pg-core";
 export const TENANT_SCHEMA = "nylorun";
@@ -91,11 +55,14 @@ export const tenant = nylorun.table("tenant", {
     retiredGenerations: integer().array().notNull().default(sql `'{}'`),
 }, () => [check("tenant_singleton_check", sql `singleton`)]);
 export const definitions = documents("definitions");
+const xid8 = customType({ dataType: () => "xid8" });
 export const sessions = nylorun.table("sessions", {
     id: textC().primaryKey(),
     body: jsonText().notNull(),
     status: field("->>'status'"),
     agentId: field("->>'agentId'"),
+    /** Unknown for legacy sessions; assigned only on insert. */
+    createdAt: timestamp({ withTimezone: true, mode: "string" }).defaultNow(),
     /** The lease holder; store-managed, never in `body`. */
     owner: text(),
     epoch: bigint({ mode: "number" }).notNull().default(0),
@@ -105,6 +72,7 @@ export const sessions = nylorun.table("sessions", {
     /** The sandbox resource the session is attached to (`sandbox: { id }`). */
     sandboxId: field("->>'sandboxId'"),
 }, (t) => [
+    index("sessions_created").on(t.createdAt.desc().nullsLast(), t.id.desc().nullsFirst()),
     index("sessions_status").on(t.status, t.ownerExpiresAt),
     index("sessions_agent").on(t.agentId),
     index("sessions_owner_user").on(t.ownerUserId),
@@ -122,29 +90,16 @@ export const effects = nylorun.table("effects", {
     index("effects_session").on(t.sessionId, t.turnId, t.status),
     index("effects_status").on(t.status, t.kind),
 ]);
-export const actions = nylorun.table("actions", {
-    id: textC().primaryKey(),
-    body: jsonText().notNull(),
-    sessionId: field("->>'sessionId'"),
-    turnId: field("->>'turnId'"),
-    agentId: field("->>'agentId'"),
-    status: field("->>'status'"),
-    kind: field("->>'kind'"),
-    /** When the Action being delivered is lost (ISO text). */
-    deadlineAt: field("->>'deadlineAt'"),
-}, (t) => [
-    index("actions_session").on(t.sessionId, t.turnId, t.status),
-    index("actions_agent").on(t.agentId, t.status),
-    index("actions_status").on(t.status, t.kind),
-    index("actions_deadline").on(t.status, t.deadlineAt),
-]);
 export const sandboxes = documents("sandboxes");
 export const links = nylorun.table("links", {
     id: textC().primaryKey(),
     body: jsonText().notNull(),
     workflowSessionId: field("->>'workflowSessionId'"),
 }, (t) => [index("links_workflow").on(t.workflowSessionId)]);
-/** An application principal: who holds a key, by its SHA-256. */
+/**
+ * A principal: who holds a key, by its SHA-256, and what the key reaches (`role`, protocol 8):
+ * `application` the Runtime API, `management` the Management API, `studio` both.
+ */
 export const principals = nylorun.table("principals", {
     id: textC().primaryKey(),
     role: text().$type().notNull(),
@@ -249,7 +204,7 @@ export const tenantSettings = nylorun.table("tenant_settings", {
     value: text().notNull(),
 });
 /**
- * The Tenant's signing keys (delivery tokens, capability links, run and host tokens): the
+ * The Tenant's signing keys (capability links, run and host tokens): the
  * private half sealed, the public JWK not.
  */
 export const signingKeys = nylorun.table("signing_keys", {
@@ -273,28 +228,6 @@ export const signingKeys = nylorun.table("signing_keys", {
     uniqueIndex("signing_keys_one_current").on(t.state).where(sql `state = 'current'`),
     uniqueIndex("signing_keys_one_previous").on(t.state).where(sql `state = 'previous'`),
 ]);
-/**
- * Action endpoints: where the Runtime delivers each agent's Actions over HTTP, and the health
- * recent deliveries and the last ping report.
- */
-export const endpoints = nylorun.table("endpoints", {
-    agentId: textC().primaryKey(),
-    url: text().notNull(),
-    implementationVersion: text().notNull(),
-    manifestHash: text(),
-    timeoutMs: integer().notNull(),
-    maxConcurrent: integer().notNull(),
-    principalId: text(),
-    lastDeliveryAt: text(),
-    lastSuccessAt: text(),
-    lastErrorCode: text(),
-    lastErrorMessage: text(),
-    consecutiveFailures: integer().notNull().default(0),
-    servedImplementationVersion: text(),
-    servedManifestHash: text(),
-    createdAt: text().notNull(),
-    updatedAt: text().notNull(),
-});
 /**
  * The model usage ledger (P1.3): one row per model call a gate served, written after the call.
  * A second row for the same effect (a call the gate ran again after a gateway restart) is
@@ -305,6 +238,9 @@ export const modelUsage = nylorun.table("model_usage", {
     id: textC().primaryKey(),
     /** The model effect's id; unique per Tenant, since it carries the turn id. */
     effectKey: textC().notNull(),
+    tokensReported: boolean(),
+    costKnown: boolean(),
+    txid: xid8().notNull().default(sql `pg_current_xact_id()`),
     sessionId: textC().notNull(),
     turnId: textC().notNull(),
     agentId: textC().notNull(),
@@ -321,6 +257,8 @@ export const modelUsage = nylorun.table("model_usage", {
     duplicate: boolean().notNull(),
     createdAt: text().notNull(),
 }, (t) => [
+    index("model_usage_session").on(t.sessionId, t.createdAt, t.id),
+    index("model_usage_export").on(t.txid, t.id),
     index("model_usage_effect").on(t.effectKey),
     index("model_usage_agent").on(t.agentId, t.createdAt),
     index("model_usage_turn").on(t.turnId),
@@ -470,6 +408,33 @@ export const artifactContent = nylorun.table("artifact_content", {
     }).onDelete("cascade"),
     index("artifact_content_sha256").on(t.sha256),
 ]);
+/**
+ * The definition files the Tenant holds (track R2 M4): files a definition names by the SHA-256
+ * of their bytes (a skill's folder), uploaded with `PUT /v1/files/sha256:<hex>`. The bytes are
+ * in the Object store at `definitions/sha256/<hex>`; a row counts them only once they are
+ * stored. `sha256` is `sha256:<hex>`.
+ */
+export const definitionFiles = nylorun.table("definition_files", {
+    sha256: textC().primaryKey(),
+    /** What the file is part of: `skill` for now. */
+    kind: text().notNull(),
+    size: bigint({ mode: "number" }).notNull(),
+    contentType: text(),
+    createdAt: textC().notNull(),
+});
+/**
+ * Which definition version names which definition file: one row per agent id, manifest hash
+ * and file, written when the definition is stored. A later sweep deletes the files no
+ * definition uses.
+ */
+export const definitionFileUses = nylorun.table("definition_file_uses", {
+    agentId: textC().notNull(),
+    manifestHash: textC().notNull(),
+    sha256: textC().notNull(),
+}, (t) => [
+    primaryKey({ name: "definition_file_uses_pkey", columns: [t.agentId, t.manifestHash, t.sha256] }),
+    index("definition_file_uses_sha256").on(t.sha256),
+]);
 // ---------------------------------------------------------------------------
 // nylorun_streams: the record
 /**

package/dist/store/postgres/store.js

@@ -8,7 +8,7 @@
  *
  * Plain reads and writes use Drizzle's query builder: `.set(patch)` and `and(...)` skip
  * `undefined`, rows come back in the camelCase of `schema.ts`. Statements whose logic is SQL
- * stay `sql` fragments inside it: the endpoint upsert's `CASE` arms, the log-head upsert,
+ * stay `sql` fragments inside it: the log-head upsert,
  * `orphanedSessions`' ordering, `counts()`, advisory locks and array updates.
  *
  * ## Transactions
@@ -28,7 +28,7 @@
  * ends. To stay deadlock-free:
  *
  * 1. A session-scoped transaction locks its session row before writing any
- *    other row of that session (effects, actions, its record rows and log
+ *    other row of that session (effects, its record rows and log
  *    head).
  * 2. A transaction that touches several sessions locks them in ascending id
  *    order, with `lockSessions` (`./locking.ts`), before writing any of them.
@@ -51,12 +51,12 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { and, count, eq, getTableColumns, gte, inArray, isNotNull, isNull, lt, lte, ne, or, sql, } from "drizzle-orm";
 import { appendEvent, appendSandboxEvent } from "../../record/index.js";
-import { OwnershipLostError } from "../ownership.js";
+import { OwnershipLostError, PrincipalRoleConflict } from "../ownership.js";
 import { database, driverError } from "./db.js";
 import { expectedSchemaVersion, readSchemaVersion } from "./migrate.js";
 import { createPostgresRecordReader } from "./record.js";
 import { postgresRecordWriter, postgresSandboxRecordWriter } from "./record-writer.js";
-import { actions, artifacts, artifactVersions, artifactContent, commands, definitions, effects, endpoints, links, modelBudgets, modelUsage, principals, sandboxes, sandboxEvents, sandboxResources, sessionEvents, sessionLogHeads, sessions, toJson, toolCrossings, signingKeys, tenant, tenantSettings, vaultAudit, vaultCredentials, vaultIdempotency, vaults, oauthPending, } from "./schema.js";
+import { artifacts, artifactVersions, artifactContent, definitionFiles, definitionFileUses, commands, definitions, effects, links, modelBudgets, modelUsage, principals, sandboxes, sandboxEvents, sandboxResources, sessionEvents, sessionLogHeads, sessions, toJson, toolCrossings, signingKeys, tenant, tenantSettings, vaultAudit, vaultCredentials, vaultIdempotency, vaults, oauthPending, } from "./schema.js";
 export function createPostgresSessionStore(options) {
     return new PostgresSessionStore(options);
 }
@@ -68,7 +68,6 @@ const DOCUMENTS = {
     sessions: sessions,
     commands,
     effects: effects,
-    actions: actions,
     sandboxes,
     links: links,
 };
@@ -243,10 +242,6 @@ function podColumns(patch) {
     };
     return Object.fromEntries(Object.entries(columns).filter(([, value]) => value !== undefined));
 }
-/** An endpoint row with its unset (null) columns left out, as `EndpointRow` has them. */
-function endpointRow(row) {
-    return Object.fromEntries(Object.entries(row).filter(([, value]) => value !== null));
-}
 /** The time column a signing key's new state stamps. */
 const SIGNING_KEY_STAMP = {
     current: "activatedAt",
@@ -255,11 +250,9 @@ const SIGNING_KEY_STAMP = {
 };
 /** The audit columns a row has (`ord` only orders them). */
 const { ord: _ord, ...AUDIT } = getTableColumns(vaultAudit);
-const SESSION_TABLES = [sessions, commands, effects, actions, links];
+const SESSION_TABLES = [sessions, commands, effects, links];
 /** The inserted row's `column` (`ON CONFLICT … DO UPDATE`). */
 const excluded = (column) => sql.raw(`excluded.${column}`);
-/** Keeps an endpoint's health `column` when its URL stays; a new URL starts with `fresh`. */
-const sameUrl = (column, fresh = sql `NULL`) => sql `CASE WHEN ${endpoints.url} = excluded.url THEN ${column} ELSE ${fresh} END`;
 class PostgresTx {
     db;
     tenantId;
@@ -536,56 +529,6 @@ class PostgresTx {
             .limit(options.limit ?? 1000);
         return rows.map((row) => row.body);
     }
-    async actionBodies(where) {
-        const rows = await this.db
-            .select({ body: actions.body })
-            .from(actions)
-            .where(where)
-            .orderBy(actions.id);
-        return rows.map((row) => row.body);
-    }
-    async pendingActions(agentId) {
-        this.check();
-        return this.actionBodies(and(eq(actions.agentId, agentId), eq(actions.status, "pending")));
-    }
-    async deliveringCount(agentId) {
-        this.check();
-        const [row] = await this.db
-            .select({ n: count() })
-            .from(actions)
-            .where(and(eq(actions.agentId, agentId), eq(actions.status, "delivering")));
-        return row.n;
-    }
-    async pendingActionsWithEndpoint(limit) {
-        this.check();
-        const rows = await this.db
-            .select({ body: actions.body })
-            .from(actions)
-            .innerJoin(endpoints, eq(endpoints.agentId, actions.agentId))
-            .where(eq(actions.status, "pending"))
-            .orderBy(actions.id)
-            .limit(limit);
-        return rows.map((row) => row.body);
-    }
-    async expiredDeliveries(now, limit) {
-        this.check();
-        const deadline = sql `${actions.deadlineAt}::timestamptz`;
-        const rows = await this.db
-            .select({ body: actions.body })
-            .from(actions)
-            .where(and(eq(actions.status, "delivering"), isNotNull(actions.deadlineAt), sql `${deadline} <= ${now.toISOString()}::timestamptz`))
-            .orderBy(deadline, actions.id)
-            .limit(limit);
-        return rows.map((row) => row.body);
-    }
-    async actionsForSession(sessionId, filter = {}) {
-        this.check();
-        return this.actionBodies(and(eq(actions.sessionId, sessionId), filter.turnId === undefined ? undefined : eq(actions.turnId, filter.turnId), filter.statuses === undefined ? undefined : inArray(actions.status, filter.statuses)));
-    }
-    async actionsWithStatus(statuses, filter = {}) {
-        this.check();
-        return this.actionBodies(and(inArray(actions.status, statuses), filter.kinds === undefined ? undefined : inArray(actions.kind, filter.kinds)));
-    }
     async effectBodies(where) {
         const rows = await this.db
             .select({ body: effects.body })
@@ -629,15 +572,12 @@ class PostgresTx {
         (SELECT count(*) FROM ${sessions})::int AS sessions,
         (SELECT count(*) FROM ${sessions}
           WHERE ${sessions.status} IN ('running', 'runnable'))::int AS running,
-        (SELECT count(*) FROM ${actions}
-          WHERE ${actions.status} IN ('pending', 'delivering'))::int AS actions,
         (SELECT count(*) FROM ${effects} WHERE ${effects.status} = 'uncertain')::int AS uncertain,
         (SELECT count(*) FROM ${sandboxes})::int AS sandboxes,
         (SELECT count(*) FROM ${definitions})::int AS definitions`);
         return {
             sessions: row.sessions,
             runningSessions: row.running,
-            pendingActions: row.actions,
             uncertainEffects: row.uncertain,
             sandboxes: row.sandboxes,
             definitions: row.definitions,
@@ -658,81 +598,6 @@ class PostgresTx {
             retiredGenerations: sql `array_remove(${tenant.retiredGenerations}, ${generation}::int)`,
         });
     }
-    // --- Action endpoints -----------------------------------------------------
-    async listEndpoints() {
-        this.check();
-        const rows = await this.db.select().from(endpoints).orderBy(endpoints.agentId);
-        return rows.map(endpointRow);
-    }
-    async getEndpoint(agentId) {
-        this.check();
-        const [row] = await this.db.select().from(endpoints).where(eq(endpoints.agentId, agentId));
-        return row && endpointRow(row);
-    }
-    async putEndpoint(row) {
-        this.check();
-        // Health belongs to a URL: a new URL starts with none.
-        await this.db
-            .insert(endpoints)
-            .values({
-            agentId: row.agentId,
-            url: row.url,
-            implementationVersion: row.implementationVersion,
-            manifestHash: row.manifestHash ?? null,
-            timeoutMs: row.timeoutMs,
-            maxConcurrent: row.maxConcurrent,
-            principalId: row.principalId ?? null,
-            consecutiveFailures: 0,
-            createdAt: row.updatedAt,
-            updatedAt: row.updatedAt,
-        })
-            .onConflictDoUpdate({
-            target: endpoints.agentId,
-            set: {
-                url: excluded("url"),
-                implementationVersion: excluded("implementation_version"),
-                manifestHash: excluded("manifest_hash"),
-                timeoutMs: excluded("timeout_ms"),
-                maxConcurrent: excluded("max_concurrent"),
-                principalId: excluded("principal_id"),
-                updatedAt: excluded("updated_at"),
-                lastDeliveryAt: sameUrl(sql `${endpoints.lastDeliveryAt}`),
-                lastSuccessAt: sameUrl(sql `${endpoints.lastSuccessAt}`),
-                lastErrorCode: sameUrl(sql `${endpoints.lastErrorCode}`),
-                lastErrorMessage: sameUrl(sql `${endpoints.lastErrorMessage}`),
-                consecutiveFailures: sameUrl(sql `${endpoints.consecutiveFailures}`, sql `0`),
-                servedImplementationVersion: sameUrl(sql `${endpoints.servedImplementationVersion}`),
-                servedManifestHash: sameUrl(sql `${endpoints.servedManifestHash}`),
-            },
-        });
-    }
-    async deleteEndpoint(agentId) {
-        this.check();
-        await this.db.delete(endpoints).where(eq(endpoints.agentId, agentId));
-    }
-    async recordEndpointHealth(agentId, update) {
-        this.check();
-        const set = update.kind === "success"
-            ? {
-                lastDeliveryAt: update.at,
-                lastSuccessAt: update.at,
-                consecutiveFailures: 0,
-                lastErrorCode: null,
-                lastErrorMessage: null,
-            }
-            : update.kind === "failure"
-                ? {
-                    lastDeliveryAt: update.at,
-                    lastErrorCode: update.code,
-                    lastErrorMessage: update.message,
-                    consecutiveFailures: sql `${endpoints.consecutiveFailures} + 1`,
-                }
-                : {
-                    servedImplementationVersion: update.implementationVersion,
-                    servedManifestHash: update.manifestHash ?? null,
-                };
-        await this.db.update(endpoints).set(set).where(eq(endpoints.agentId, agentId));
-    }
     // --- principals ----------------------------------------------------------
     async insertPrincipal(row) {
         this.check();
@@ -751,29 +616,24 @@ class PostgresTx {
         const [row] = await this.db.select().from(principals).where(eq(principals.id, id));
         return row;
     }
-    async applicationTokenHashes() {
-        this.check();
-        const rows = await this.db
-            .select({ tokenHash: principals.tokenHash })
-            .from(principals)
-            .where(eq(principals.role, "application"))
-            .orderBy(principals.id);
-        return rows.map((row) => row.tokenHash);
-    }
     async listPrincipals() {
         this.check();
         return await this.db.select().from(principals).orderBy(principals.id);
     }
-    async putPrincipal(id, tokenHash, createdAt) {
+    async putPrincipal(id, tokenHash, createdAt, role = "application") {
         this.check();
         const [row] = await this.db
             .insert(principals)
-            .values({ id, role: "application", tokenHash, idempotencyKey: null, createdAt })
+            .values({ id, role, tokenHash, idempotencyKey: null, createdAt })
             .onConflictDoUpdate({
             target: principals.id,
             set: { tokenHash, createdAt, idempotencyKey: null },
+            // A key keeps its role: rotating never turns one kind of key into another.
+            setWhere: eq(principals.role, role),
         })
             .returning();
+        if (!row)
+            throw new PrincipalRoleConflict(id);
         return row;
     }
     async deletePrincipal(id) {
@@ -953,8 +813,8 @@ class PostgresTx {
             ...row,
             duplicate: sql `EXISTS (SELECT 1 FROM ${modelUsage} WHERE ${modelUsage.effectKey} = ${row.effectKey})`,
         })
-            .returning({ duplicate: modelUsage.duplicate });
-        return { ...row, duplicate: inserted.duplicate };
+            .returning();
+        return inserted;
     }
     async modelUsageTotals(query) {
         this.check();
@@ -1137,6 +997,42 @@ class PostgresTx {
             .where(scope === "sessions" ? isNotNull(artifacts.sessionId) : undefined);
         return rows.map((row) => row.blobKey);
     }
+    // --- definition files -----------------------------------------------------
+    async definitionFile(sha256) {
+        this.check();
+        const [row] = await this.db.select().from(definitionFiles).where(eq(definitionFiles.sha256, sha256));
+        return row;
+    }
+    async insertDefinitionFile(row) {
+        this.check();
+        const inserted = await this.db
+            .insert(definitionFiles)
+            .values(row)
+            .onConflictDoNothing()
+            .returning({ sha256: definitionFiles.sha256 });
+        return inserted.length === 1;
+    }
+    async heldDefinitionFiles(shas) {
+        this.check();
+        const found = new Set();
+        for (let at = 0; at < shas.length; at += CONTENT_BATCH) {
+            const rows = await this.db
+                .select({ sha256: definitionFiles.sha256 })
+                .from(definitionFiles)
+                .where(inArray(definitionFiles.sha256, shas.slice(at, at + CONTENT_BATCH)));
+            for (const row of rows)
+                found.add(row.sha256);
+        }
+        return found;
+    }
+    async insertDefinitionFileUses(agentId, manifestHash, shas) {
+        this.check();
+        for (let at = 0; at < shas.length; at += CONTENT_BATCH)
+            await this.db
+                .insert(definitionFileUses)
+                .values(shas.slice(at, at + CONTENT_BATCH).map((sha256) => ({ agentId, manifestHash, sha256 })))
+                .onConflictDoNothing();
+    }
     // --- settings ------------------------------------------------------------
     async getSetting(key) {
         this.check();
@@ -1179,7 +1075,8 @@ class PostgresTx {
         }
         if (scope === "all") {
             await db.delete(definitions);
-            await db.delete(endpoints);
+            // The files stay, as their bytes do; only what used them goes.
+            await db.delete(definitionFileUses);
             await db.delete(modelUsage);
             await db.delete(modelBudgets);
             await db.delete(artifacts);

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

@@ -1,3 +1,27 @@
+/**
+ * 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 (the
+ *    ephemeral Runtime's application key); existing ones are kept, as ordinary keys.
+ * 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 type { KeyRole } from "@nylorun/core/compatibility";
 import type { Sql } from "postgres";
 import { type TenantEnvelope } from "@nylorun/core/contracts";
 import type { SessionStore } from "../types.js";
@@ -8,6 +32,14 @@ export interface InitialPrincipal {
     id: string;
     /** SHA-256 hex of the principal's key. */
     credentialHash: string;
+    /** What the key reaches; `application` when absent. */
+    role?: KeyRole;
+    /**
+     * Its key comes from outside the database (the bootstrap file, or Studio's key derived from
+     * the admin key): on later opens a principal of the same role takes this hash. Otherwise an
+     * existing principal is kept as it is.
+     */
+    replace?: boolean;
 }
 /** Who the Tenant is when the database holds none yet. */
 export interface TenantCreation {
@@ -16,8 +48,8 @@ export interface TenantCreation {
     /** Ignored when the Tenant exists. */
     name: string;
     /**
-     * The principals the Tenant must have, given its id (Studio's derived key depends on it). Created
-     * with the Tenant; on later opens, the missing ones are added.
+     * The principals the Tenant must have, given its id. Created with the Tenant; on later
+     * opens, the missing ones are added.
      */
     principals?(tenantId: string): readonly InitialPrincipal[];
 }

package/dist/store/postgres/tenant.js

@@ -1,27 +1,4 @@
-/**
- * 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 (the
- *    ephemeral Runtime's application key); existing ones are kept, as ordinary keys.
- * 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 { and, eq, ne, sql } from "drizzle-orm";
 import { isTenantId, newTenantId } from "@nylorun/core/compatibility";
 import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
 import { openError, TenantOpenError } from "../../tenant/cause.js";
@@ -138,17 +115,24 @@ async function ensureTenant(tx, create, migrated, now) {
     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({
+    for (const principal of create.principals?.(tenantId) ?? []) {
+        const insert = tx.insert(principals).values({
             id: principal.id,
-            role: "application",
+            role: principal.role ?? "application",
             tokenHash: principal.credentialHash,
             idempotencyKey: null,
             createdAt,
-        })
-            .onConflictDoNothing();
+        });
+        if (principal.replace)
+            // The bootstrap key or Studio's: a principal of the same role takes the current key.
+            await insert.onConflictDoUpdate({
+                target: principals.id,
+                set: { tokenHash: principal.credentialHash, createdAt },
+                setWhere: and(eq(principals.role, principal.role ?? "application"), ne(principals.tokenHash, principal.credentialHash)),
+            });
+        // A principal with this id or this key already exists: it is kept as it is.
+        else
+            await insert.onConflictDoNothing();
+    }
     return existing === undefined;
 }