@nylorun/runtime 0.16.0-beta → 0.19.0-beta

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, publishableKeys, sandboxes, sandboxEvents, sandboxResources, sessionEvents, sessionLogHeads, sessions, toJson, toolCrossings, signingKeys, subjectEpochs, subjectUsage, tenant, tenantSettings, vaultAudit, vaultCredentials, vaultIdempotency, vaults, } 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,14 +616,33 @@ class PostgresTx {
         const [row] = await this.db.select().from(principals).where(eq(principals.id, id));
         return row;
     }
-    async applicationTokenHashes() {
+    async listPrincipals() {
+        this.check();
+        return await this.db.select().from(principals).orderBy(principals.id);
+    }
+    async putPrincipal(id, tokenHash, createdAt, role = "application") {
+        this.check();
+        const [row] = await this.db
+            .insert(principals)
+            .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) {
         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);
+            .delete(principals)
+            .where(eq(principals.id, id))
+            .returning({ id: principals.id });
+        return rows.length > 0;
     }
     // --- vault ---------------------------------------------------------------
     async insertVault(row) {
@@ -778,6 +662,14 @@ class PostgresTx {
             .where(and(eq(vaults.ownerUserId, ownerUserId), eq(vaults.scope, "user")))
             .orderBy(vaults.createdAt, vaults.id);
     }
+    async installationVaults() {
+        this.check();
+        return this.db
+            .select()
+            .from(vaults)
+            .where(eq(vaults.scope, "installation"))
+            .orderBy(vaults.createdAt, vaults.id);
+    }
     async updateVaultMetadata(id, metadataJson) {
         this.check();
         await this.db.update(vaults).set({ metadataJson }).where(eq(vaults.id, id));
@@ -858,7 +750,24 @@ class PostgresTx {
         this.check();
         await this.db.insert(vaultIdempotency).values(row);
     }
-    // --- subject tokens ------------------------------------------------------
+    async insertOAuthPending(row) {
+        this.check();
+        await this.db.insert(oauthPending).values(row);
+    }
+    async takeOAuthPending(stateHash) {
+        this.check();
+        const [row] = await this.db
+            .delete(oauthPending)
+            .where(eq(oauthPending.stateHash, stateHash))
+            .returning();
+        return row;
+    }
+    async deleteExpiredOAuthPending(now) {
+        this.check();
+        const result = await this.db.delete(oauthPending).where(lt(oauthPending.expiresAt, now));
+        return result.count;
+    }
+    // --- signing keys --------------------------------------------------------
     async lockSigningKeys() {
         this.check();
         await this.db.execute(sql `SELECT pg_advisory_xact_lock(hashtext('nylorun.signing_keys'))`);
@@ -895,103 +804,6 @@ class PostgresTx {
         const [row] = await this.db.select({ n: count() }).from(signingKeys);
         return row.n;
     }
-    async subjectEpoch(subject) {
-        this.check();
-        const [row] = await this.db
-            .select({ epoch: subjectEpochs.epoch })
-            .from(subjectEpochs)
-            .where(eq(subjectEpochs.subject, subject));
-        return row?.epoch ?? 0;
-    }
-    async subjectEpochs(subjects) {
-        this.check();
-        if (subjects.length === 0)
-            return new Map();
-        const rows = await this.db
-            .select({ subject: subjectEpochs.subject, epoch: subjectEpochs.epoch })
-            .from(subjectEpochs)
-            .where(inArray(subjectEpochs.subject, subjects));
-        return new Map(rows.map((row) => [row.subject, row.epoch]));
-    }
-    async bumpSubjectEpoch(subject, at) {
-        this.check();
-        const [row] = await this.db
-            .insert(subjectEpochs)
-            .values({ subject, epoch: 1, revokedAt: at })
-            .onConflictDoUpdate({
-            target: subjectEpochs.subject,
-            set: { epoch: sql `${subjectEpochs.epoch} + 1`, revokedAt: excluded("revoked_at") },
-        })
-            .returning({ epoch: subjectEpochs.epoch });
-        return row.epoch;
-    }
-    async lockSubjectUsage(initial) {
-        this.check();
-        await this.db.insert(subjectUsage).values(initial).onConflictDoNothing();
-        const [row] = await this.db
-            .select()
-            .from(subjectUsage)
-            .where(eq(subjectUsage.subject, initial.subject))
-            .for("update");
-        return row;
-    }
-    async putSubjectUsage(row) {
-        this.check();
-        await this.db
-            .insert(subjectUsage)
-            .values(row)
-            .onConflictDoUpdate({
-            target: subjectUsage.subject,
-            set: { turnTokens: excluded("turn_tokens"), refilledAt: excluded("refilled_at") },
-        });
-    }
-    async countOwnerSessions(ownerUserId, statuses) {
-        this.check();
-        const [row] = await this.db
-            .select({ n: count() })
-            .from(sessions)
-            .where(and(eq(sessions.ownerUserId, ownerUserId), inArray(sessions.status, statuses)));
-        return row.n;
-    }
-    // --- publishable keys ----------------------------------------------------
-    async insertPublishableKey(row) {
-        this.check();
-        await this.db.insert(publishableKeys).values(row);
-    }
-    async publishableKeyByKey(key) {
-        this.check();
-        const [row] = await this.db
-            .select()
-            .from(publishableKeys)
-            .where(eq(publishableKeys.key, key));
-        return row;
-    }
-    async publishableKey(id) {
-        this.check();
-        const [row] = await this.db
-            .select()
-            .from(publishableKeys)
-            .where(eq(publishableKeys.id, id));
-        return row;
-    }
-    async publishableKeys() {
-        this.check();
-        return this.db
-            .select()
-            .from(publishableKeys)
-            .orderBy(publishableKeys.createdAt, publishableKeys.id);
-    }
-    async updatePublishableKey(id, patch) {
-        this.check();
-        if (patch.originsJson === undefined && patch.revokedAt === undefined)
-            return (await this.publishableKey(id)) !== undefined;
-        const rows = await this.db
-            .update(publishableKeys)
-            .set(patch)
-            .where(eq(publishableKeys.id, id))
-            .returning({ id: publishableKeys.id });
-        return rows.length === 1;
-    }
     // --- model usage ---------------------------------------------------------
     async recordModelUsage(row) {
         this.check();
@@ -1001,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();
@@ -1185,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();
@@ -1208,7 +1056,6 @@ class PostgresTx {
         if (scope === "sessions" || scope === "all") {
             for (const table of SESSION_TABLES)
                 await db.delete(table);
-            await db.delete(subjectUsage);
             await db.delete(toolCrossings);
             // A session's artifacts go with it (their versions by cascade).
             await db.delete(artifacts).where(isNotNull(artifacts.sessionId));
@@ -1228,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 (derived keys depend 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 (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 { 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;
 }