@sanoma-ai/workflows 0.11.11 → 0.11.13

package/CLOUD-IDENTITY.md

@@ -75,8 +75,10 @@ Trusted composition that already owns a writer pool may instead supply the low-l
 
 ```ts
 import { postgresIdentityProvisioning } from "@sanoma-ai/workflows/cloud-identity";
+import { databaseOn } from "@sanoma-ai/workflows/db";
 
-const identityProvisioning = postgresIdentityProvisioning(async () => enrollmentWriterPool, {
+const enrollmentWriter = databaseOn(enrollmentWriterPool);
+const identityProvisioning = postgresIdentityProvisioning(async () => enrollmentWriter, {
   maxValidityMs: 24 * 60 * 60 * 1000,
 });
 // Supply this adapter as defineConfig's identityProvisioning value.
@@ -111,9 +113,11 @@ import {
   postgresIdentityEnrollments,
   attachedGoogleTokenIssuer,
 } from "@sanoma-ai/workflows/cloud-identity";
+import { databaseOn } from "@sanoma-ai/workflows/db";
 
+const brokerReader = databaseOn(brokerReadOnlyPool);
 const handle = identityBroker({
-  enrollments: postgresIdentityEnrollments(async () => brokerReadOnlyPool),
+  enrollments: postgresIdentityEnrollments(async () => brokerReader),
   issue: attachedGoogleTokenIssuer(),
   audit: writeDurableIdentityAudit,
 });
@@ -131,8 +135,10 @@ The following composition joins D1 to the separate [#470 KMS adapter](https://gi
 import { readFile } from "node:fs/promises";
 import { KeyManagementServiceClient } from "@google-cloud/kms";
 import { cloudIdentityAuth } from "@sanoma-ai/workflows/cloud-identity";
+import { databaseOn } from "@sanoma-ai/workflows/db";
 import { kmsPostgresStore } from "@sanoma-ai/workflows/kms-secrets";
 
+const companyDatabase = databaseOn(companyScopedPool);
 const authClient = cloudIdentityAuth({
   endpoint: "https://identity.example.test/token",
   credential: async () => (await readFile("/run/sanoma/deployment-credential", "utf8")).trim(),
@@ -142,7 +148,7 @@ const store = kmsPostgresStore({
   company: "example-company", // Fixed by trusted bootstrap.
   keyName: "projects/example-project/locations/us-central1/keyRings/production/cryptoKeys/example-company",
   kms,
-  database: async () => companyScopedPool,
+  database: async () => companyDatabase,
 });
 // Supply store to defineConfig's secrets configuration.
 // The deployment owns kms.close() and the database pool lifecycle.
@@ -208,7 +214,9 @@ import {
   attachedGoogleIdTokenIssuer,
   postgresIdentityEnrollments,
 } from "@sanoma-ai/workflows/cloud-identity";
+import { databaseOn } from "@sanoma-ai/workflows/db";
 
+const provisioningReader = databaseOn(provisioningReadOnlyPool);
 const identity = {
   serviceAccount: "provision-source@example-project.iam.gserviceaccount.com",
   subject: "123456789012345678901",
@@ -217,7 +225,7 @@ const identity = {
 };
 const handle = provisioningIdentityBroker({
   identity,
-  enrollments: postgresIdentityEnrollments(async () => provisioningReadOnlyPool),
+  enrollments: postgresIdentityEnrollments(async () => provisioningReader),
   issue: attachedGoogleIdTokenIssuer(identity),
   audit: writeDurableProvisioningAudit,
 });

package/KMS-SECRETS.md

@@ -48,8 +48,10 @@ For standalone use or an explicitly supplied KMS client, use the lower-level `km
 
 ```ts
 import { KeyManagementServiceClient } from "@google-cloud/kms";
+import { databaseOn } from "@sanoma-ai/workflows/db";
 import { kmsPostgresStore } from "@sanoma-ai/workflows/kms-secrets";
 
+const companyDatabase = databaseOn(companyPool);
 const kms = new KeyManagementServiceClient({ authClient: companyAuthClient });
 const store = kmsPostgresStore({
   company: companyIdFromTrustedBootstrap,
@@ -60,7 +62,7 @@ const store = kmsPostgresStore({
 await store.validate("production");
 ```
 
-An explicit `database` returns a `SecretStore`; omitting it returns a factory that uses the runtime's database. In both forms of `kmsPostgresStore`, the caller owns the supplied KMS client, including `kms.close()`. An explicit database connection is also caller-owned. `managedKmsStore` supplies both the runtime binding and SDK lifecycle instead.
+An explicit `database` returns a `SecretStore`; omitting it returns a factory that uses the runtime's database. In both forms of `kmsPostgresStore`, the caller owns the supplied KMS client, including `kms.close()`. An explicit database (`databaseOn` over the caller's `pg` pool) is also caller-owned, its pool included. `managedKmsStore` supplies both the runtime binding and SDK lifecycle instead.
 
 `SANOMA_SIGNING_KEY` stays independent. This store does not use `SANOMA_SECRETS_KEY`. Workflow code cannot import either backend entry. Secret intake must remain outside durable workflow inputs/outputs. Runtime binding does not establish deployed Cloud readiness; provisioning, bootstrap delivery and live company isolation remain #532 verification work.
 

package/README.md

@@ -53,7 +53,9 @@ export const shop = withSetup(defineConnector("shop", specs, info), {
 
 `withSetup` lays what it is given over what the connector already carries, and keeps it on the connector's vendor record, so a spread copy of the connector keeps it too. A config that needs a driver made otherwise (another bridge, other options) swaps the driver and keeps the fake: `withSetup(github, { driver: () => githubDriver({ bridge }) })`. It is for connector packages and configs, not for workflows, which the lint does not let import it. Both are optional: a connector without a driver declares its operations and implements none, so a workflow using one is refused; a connector without a fake has none for sandbox runs, which the app's connector page says.
 
-A connector that signs visitors in to a public site attaches a login half too, as `login`: `withSetup(connector, { login: (context) => half })`. The app calls it once per public site whose `site.ts` names the connector (`defineSite({ public: true, login: "<vendor>" })`), when it starts, with a `LoginContext` (the database, a key of its own derived from `SANOMA_SIGNING_KEY` to sign its cookies with, a vendor's secrets, the site's origins, `sendCode(email, code)` when the config names a `login.sender`, and `social`, the company's GitHub App's OAuth client when the app is given it); a login that keeps tables in the database migrates them there, serialized and idempotent. The `LoginHalf` it makes (see its type) answers the provider's stable subject for a request, with the email and the GitHub login when it verified them, never a principal: the app makes the visitor's principal from it, so a connector cannot set a visitor's groups. A visitor's address, for rate limits, is the `CLIENT_IP_HEADER` header the app sets, never `X-Forwarded-For`. One vendor's connectors attach one `login`, as for a driver. [`@sanoma-ai/connector-better-auth`](https://www.npmjs.com/package/@sanoma-ai/connector-better-auth) is one, email and password (and an email code, with a sender) on the company's database; it also exports `betterAuthStaffLogin`, the staff sign-in the app uses on a host (`LoginContext.staff`: who is declared, the GitHub client, and where a sign-in is recorded). The app makes it as it starts and sends it every request to the site's own host ([public sites](https://www.npmjs.com/package/@sanoma-ai/app#public-sites)).
+A connector that keeps tables on the company's database (a login's) attaches how to make them, as `prepare`: `withSetup(connector, { prepare: async (databaseUrl) => … })`, a `DatabasePreparation` the worker runs at its start, after the runtime's own tables, with the database's direct URL (never a pooler's: an advisory lock is one connection's); idempotent, and safe for two workers at once. The app never makes a connector's tables, since on a host it may run where it must not migrate: a login opened before the worker prepared them refuses. `startWorker`'s `prepare` option adds preparations no config names, as the `sanoma` bin adds the staff login's.
+
+A connector that signs visitors in to a public site attaches a login half too, as `login`: `withSetup(connector, { login: (context) => half })`. The app calls it once per public site whose `site.ts` names the connector (`defineSite({ public: true, login: "<vendor>" })`), when it starts, with a `LoginContext` (`database()`, the client's pool, the app's one on Node and the request's own on a Worker, so a half keeps an instance per pool and nothing else across requests; a key of its own derived from `SANOMA_SIGNING_KEY` to sign its cookies with, a vendor's secrets, the site's origins, `sendCode(email, code)` when the config names a `login.sender`, and `social`, the company's GitHub App's OAuth client when the app is given it), on the tables its `prepare` made. The `LoginHalf` it makes (see its type) answers the provider's stable subject for a request, with the email and the GitHub login when it verified them, never a principal: the app makes the visitor's principal from it, so a connector cannot set a visitor's groups. A visitor's address, for rate limits, is the `CLIENT_IP_HEADER` header the app sets, never `X-Forwarded-For`. One vendor's connectors attach one `login`, as for a driver. [`@sanoma-ai/connector-better-auth`](https://www.npmjs.com/package/@sanoma-ai/connector-better-auth) is one, email and password (and an email code, with a sender) on the company's database; it also exports `betterAuthStaffLogin`, the staff sign-in the app uses on a host (`LoginContext.staff`: who is declared, the GitHub client, and where a sign-in is recorded). The app makes it as it starts and sends it every request to the site's own host ([public sites](https://www.npmjs.com/package/@sanoma-ai/app#public-sites)).
 
 A model connector attaches a model half, as `model`: `withSetup(connector, { model: (context) => provider })`, an AI SDK provider (`ProviderV4` from `@ai-sdk/provider`) with the vendor's adapter as the transport. The app makes it for its model registry, once per resolved config and client (again after one that throws), where its models are `<vendor>/<model-id>`; it answers `languageModel("default")` with the connector's own default. Its `ModelContext` gives it the secrets as a login's does (the selected store and explicit bindings), which it reads when a model is called; its driver declares the key in `env`, with no operations if it needs none. One vendor's connectors attach one `model`. [`@sanoma-ai/connector-anthropic`](https://www.npmjs.com/package/@sanoma-ai/connector-anthropic) is one.
 
@@ -669,6 +671,8 @@ A stopped worker cannot launch again in its process, so whoever supervises it st
 
 A database is a resource type that holds the company's database (a Neon project, a Supabase project): `defineResource({ …, writable: true, afterCreate, database })`, where `database` (`DatabaseSpec`) says what it can do (`capabilities: { pauses, branch }`: its compute scales to zero and wakes on a connection; it makes copy-on-write branches that carry the data), where it takes going live's choices, by dotted path into its fields (`inputs: { region, size? }`), the regions it takes when known (`regions`), the operation that stores its URL (`storeUrl`) and how its state reads (`outputs(state) → { healthy }`). `storeUrl` is an operation of the type's own vendor, in the type's own group (`neon.project.storeUrl`) or another (`supabase.database.storeUrl`), never one of a resource type's own: it takes `{ ref | id, export }` and stores the URL that carries `LISTEN` as `SANOMA_DATABASE_URL_<EXPORT>` (`databaseUrlSecret(export)`; `storeDatabaseUrl` stores it so, refusing a secret that holds another), never returning it, and the type's `afterCreate` calls it. A database type is not `stateless`: apply asks before it deletes one. `defineResource` refuses a `database` that breaks any of that; `resolveConfig` refuses one whose `storeUrl` is not among the config's operations, or does not take a binding id and an export. Its conformance kit is [`@sanoma-ai/testing/database`](../testing/README.md#a-databases-conformance). After retiring a database, a workflow can remove its exported URL with `sanoma.secret.delete` under the [runtime operation contract](#the-runtimes-own-operations).
 
+`databaseUrlSecret` converts camel-case exports to uppercase words (`mainStore` → `SANOMA_DATABASE_URL_MAIN_STORE`) and preserves exports that are already uppercase, including digits and underscores (`CLOUD_ACME_97F9` → `SANOMA_DATABASE_URL_CLOUD_ACME_97F9`). Use the same export when storing, binding and retiring its URL.
+
 ### Secrets
 
 Never put a secret in a workflow's input or an operation's input or output. They are persisted verbatim: DBOS keeps every step's input and output in Postgres, the ledger records each call's input and output, an approval a policy asks for carries the held call's input, and the app shows all of it to anyone who can reach it. A driver reads its credentials when it is called (from the environment or a secret store), and an operation that creates a secret (an API key, a password reset link) returns a reference to where it is stored, not the secret.
@@ -679,7 +683,7 @@ A secret a resource needs is named, never written. A data file gives `secret("NA
 
 Every run is stamped with the application version of the worker that runs it, `<appName>@<version>`, and only a worker on that version recovers it after a restart. Versioning is automatic: the version is a hash of each workflow's name, the source of its `run` function, its operations and its input schema, which is DBOS's own scheme applied to the workflow code rather than to the runtime's registration wrapper (DBOS would otherwise see one identical function for every workflow and never change). The hash cannot see functions `run` calls that live elsewhere, op schemas, drivers or the policy: edit those with no run in flight, or restart on the old code first. To name a version instead (a git commit, say), set DBOS's `DBOS__APPVERSION` environment variable; it is prefixed with the app name the same way. A new version becomes the app's latest when it first starts, and runs queued without a version go to the latest; a worker started on an older version (a rollback) warns instead, unless started with `{ promote: true }`. The hash is of the code as it runs, so TypeScript source and the compiled JavaScript of the same workflow have different versions.
 
-Change runs are the exception: a change's own deploy restarts the worker on the merged code, a new version, so the run has to outlive its version. Each change run carries a hash of the change workflow's own code (its `changeCode` attribute: what the version hashes of the change workflow, with the runtime's and DBOS's versions, never the company's workflows), and a worker that starts as the app's latest version takes over the unfinished change runs of other versions whose hash is its own, keeping each run's id, its completed steps and the messages it has not read yet (an approval decided, an event told while no worker ran). It says so in one line at `info`. Runs of the company's workflows stay on their version, a change's `apply` and `drift` runs among them; so does a change run whose hash differs, after an upgrade of the runtime.
+Built-in runs are the exception: a deploy restarts the worker on the merged code, a new version, and the `apply` or `change` run that made the deploy has to outlive its version. Each run of a built-in workflow (`apply`, `change`, `drift`, `call`, `login-code`) carries a hash of that workflow's own code (its `builtInCode` attribute: what the version hashes of the workflow, with the runtime's and DBOS's versions, never the company's workflows), and a worker that starts as the app's latest version takes over the unfinished built-in runs of other versions whose hash is its own, keeping each run's id, its completed steps and the messages it has not read yet (an approval decided, an event told while no worker ran). It says so in one line at `info`. Runs of the company's workflows stay on their version; so does a built-in run whose hash differs, after an upgrade of the runtime (or, for `apply`, a change of the resource types it may call).
 
 When a worker starts, it warns about unfinished runs it will not pick up, naming them: runs started on another version, and runs queued on another queue. Run the version that started them, or fork each onto the current version with `DBOSClient.forkWorkflow(id, step, { applicationVersion, queueName })` and cancel the original.
 

package/dist/bundled.d.ts

@@ -5,8 +5,8 @@ export interface RootSnapshot {
     appName: string;
     /** `ResolvedConfig.version`: a hash of the workflows' source, which a bundle's code is not, so a run it queues is its worker's. */
     version: string;
-    /** `ResolvedConfig.changeCode`, for the same reason. */
-    changeCode: string;
+    /** `ResolvedConfig.builtInCodes`, for the same reason. */
+    builtInCodes: Readonly<Record<string, string>>;
     /** `readPolicyFiles`: each `.cedar` file under `policies/` (and an app's), by path from the root. */
     policies: {
         file: string;

package/dist/chats.d.ts

@@ -1,5 +1,5 @@
 import type { UIMessage } from "ai";
-import type { Pool } from "pg";
+import type { Db } from "./db.ts";
 /** A chat as `SanomaClient.chats.list` reads it. */
 export interface Chat {
     id: string;
@@ -39,5 +39,5 @@ export interface Chats {
     /** The person's chats, the newest first: the latest 50. */
     list(person: string): Promise<Chat[]>;
 }
-/** The chats' store on the pool `db` gives, the config's database once it is prepared. */
-export declare function chatStore(db: () => Promise<Pool>): Chats;
+/** The chats' store on the database `db` gives, the config's database once it is prepared. */
+export declare function chatStore(db: () => Promise<Db>): Chats;

package/dist/chats.js

@@ -1,21 +1,25 @@
-import { CHAT_MESSAGES_TABLE as MESSAGES, CHATS_TABLE as CHATS } from "./db.js";
+import { asc, desc, eq, sql } from "drizzle-orm";
+import { chatMessages, chats } from "./db/company.js";
 import { SanomaError } from "./errors.js";
-const COLUMNS = "id, person, engine, draft_id, title, created_at";
-const chatOf = ({ draft_id, created_at, ...row }) => ({
+const chatOf = ({ draftId, createdAt, ...row }) => ({
     ...row,
-    ...(draft_id === null ? {} : { draftId: draft_id }),
-    createdAt: created_at.getTime(),
+    ...(draftId === null ? {} : { draftId }),
+    createdAt: createdAt.getTime(),
 });
-/** The chats' store on the pool `db` gives, the config's database once it is prepared. */
+/** The chats' store on the database `db` gives, the config's database once it is prepared. */
 export function chatStore(db) {
     return {
         async open({ id, person, engine, title }) {
-            const { rows } = await (await db()).query(`INSERT INTO ${CHATS} (id, person, engine, title) VALUES ($1, $2, $3, $4) ON CONFLICT (id) DO NOTHING RETURNING id`, [id, person, engine, title]);
-            if (!rows.length)
+            const opened = await (await db())
+                .insert(chats)
+                .values({ id, person, engine, title })
+                .onConflictDoNothing()
+                .returning({ id: chats.id });
+            if (!opened.length)
                 throw new SanomaError("invalid_input", `Chat ${id} exists already; open it with another id`);
         },
         async attach(id, draftId) {
-            await (await db()).query(`UPDATE ${CHATS} SET draft_id = $2 WHERE id = $1`, [id, draftId]);
+            await (await db()).update(chats).set({ draftId }).where(eq(chats.id, id));
         },
         async upsert(id, messages) {
             if (!messages.length)
@@ -23,24 +27,34 @@ export function chatStore(db) {
             if (messages.some((m) => !m.id))
                 throw new SanomaError("invalid_input", "A chat message needs an id");
             // A new message's place is after the chat's last, in the order given.
-            await (await db()).query(`INSERT INTO ${MESSAGES} (chat_id, id, seq, message) ` +
-                `SELECT $1, m.value->>'id', last.seq + m.n, m.value ` +
-                `FROM jsonb_array_elements($2::jsonb) WITH ORDINALITY AS m (value, n), ` +
-                `(SELECT coalesce(max(seq), 0) AS seq FROM ${MESSAGES} WHERE chat_id = $1) AS last ` +
-                "ON CONFLICT (chat_id, id) DO UPDATE SET message = EXCLUDED.message", [id, JSON.stringify(messages)]);
+            const last = sql `(SELECT coalesce(max(${chatMessages.seq}), 0) FROM ${chatMessages} WHERE ${eq(chatMessages.chatId, id)})`;
+            await (await db())
+                .insert(chatMessages)
+                .values(messages.map((message, n) => ({ chatId: id, id: message.id, seq: sql `${last} + ${n + 1}`, message })))
+                .onConflictDoUpdate({
+                target: [chatMessages.chatId, chatMessages.id],
+                set: { message: sql `excluded.message` },
+            });
         },
         async load(id) {
-            const { rows } = await (await db()).query(`SELECT message FROM ${MESSAGES} WHERE chat_id = $1 ORDER BY seq, id`, [id]);
+            const rows = await (await db())
+                .select({ message: chatMessages.message })
+                .from(chatMessages)
+                .where(eq(chatMessages.chatId, id))
+                .orderBy(asc(chatMessages.seq), asc(chatMessages.id));
             return rows.map((row) => row.message);
         },
         async get(id) {
-            const { rows } = await (await db()).query(`SELECT ${COLUMNS} FROM ${CHATS} WHERE id = $1`, [id]);
-            return rows[0] && chatOf(rows[0]);
+            const [row] = await (await db()).select().from(chats).where(eq(chats.id, id));
+            return row && chatOf(row);
         },
         async list(person) {
-            const { rows } = await (await db()).query(`SELECT ${COLUMNS} FROM ${CHATS} WHERE person = $1 ORDER BY created_at DESC, id LIMIT 50`, [
-                person,
-            ]);
+            const rows = await (await db())
+                .select()
+                .from(chats)
+                .where(eq(chats.person, person))
+                .orderBy(desc(chats.createdAt), asc(chats.id))
+                .limit(50);
             return rows.map(chatOf);
         },
     };

package/dist/chats.js.map

@@ -1 +1 @@
-{"version":3,"file":"chats.js","sourceRoot":"","sources":["../src/chats.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chats.js","sourceRoot":"","sources":["../src/chats.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { Pool } from "pg";
 import { type ConnectionRef, type ConnectionSnapshot, type ConnectionTarget, type ConnectionSetup, type ConnectionCard, type ConnectionRule } from "./connection.ts";
 import { type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
@@ -126,6 +127,12 @@ export interface ClientOptions {
      * `origin`) and fetches a draft's new commits into. Without one, `remoteEvent` does nothing.
      */
     source?: Source;
+    /**
+     * The version each run it starts is queued for, so only a worker of that code runs it: the app
+     * bundle's (its snapshot's), which is live beside a worker of another version while a deploy
+     * rolls. Without it a run is queued with none, which DBOS gives the app's latest version.
+     */
+    appVersion?: string;
 }
 /** Talks to the runtime from another process (the app, a script), through the shared Postgres. */
 export declare class SanomaClient {
@@ -135,7 +142,7 @@ export declare class SanomaClient {
     /** The config's own ledger store, or a Postgres one made for this client, which `close` then closes. */
     private readonly audit;
     /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
-    private readonly pool;
+    private readonly database;
     /** What a direct call's driver reads secrets from, as a worker's live driver does. */
     private readonly storedSecrets;
     /** The operator agent's chats: their rows and their transcripts, in the config's database. */
@@ -154,7 +161,8 @@ export declare class SanomaClient {
      * Checks the input against the workflow's schema, then queues a run for the worker. The run
      * gets the input as sent, not as the schema parsed it: the worker parses it once, so a schema
      * with a `.transform` or a default sees the caller's value, and `run.started` records it.
-     * `workflow` is a definition, or the name of one in the config's `workflows`.
+     * `workflow` is a definition, or the name of one in the config's `workflows`. The run is queued
+     * for the client's `appVersion` when it has one.
      */
     start<S extends z.ZodType>(workflow: WorkflowDefinition<any, S> | string, input: z.input<S>, options: StartOptions): Promise<string>;
     /**
@@ -213,6 +221,11 @@ export declare class SanomaClient {
         by: string;
         expiresAt: Date;
     }): Promise<void>;
+    /**
+     * Spends a sealed invite request's `nonce` (`openInvite`), good until `expiresAt`: true the first
+     * time, false when it was spent already, in this process or another.
+     */
+    spendInviteRequest(nonce: string, expiresAt: Date): Promise<boolean>;
     /** When each of `people` last signed in to the staff login, and how, by id (`recordSignIn`); one who never did is left out. */
     lastSignIns(people: readonly string[]): Promise<Record<string, {
         at: number;
@@ -451,8 +464,8 @@ export declare class SanomaClient {
      * `invalid_input` when none does.
      */
     private declared;
-    /** The pool the runtime's tables are read and written with, on the database once it is prepared. */
-    private db;
+    /** The pool the client reads and writes with, once the database is prepared: what a login runs on (`LoginContext.database`). */
+    pool(): Promise<Pool>;
     /**
      * The principal as the data files declare it (`admit`): its id alone is taken, never the groups
      * a caller gives, and an id nobody declares is `not_admitted`.

package/dist/client.js

@@ -3,6 +3,8 @@ import { encodeCredentials, decodeCredentials, verifyAuthentication, Authenticat
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { is } from "drizzle-orm";
+import { TransactionRollbackError } from "drizzle-orm/errors";
 import { z } from "zod";
 import { APPROVALS_EVENT, ApprovalMessage, ApprovalWithdrawal, decisionEventOf, messageKeyOf, topicOf, withdrawalRefusal, } from "./approvals.js";
 import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call.js";
@@ -11,7 +13,7 @@ import { tokenStore } from "./tokens.js";
 import { collectionsDriver } from "./collection.js";
 import { resolveConfig } from "./config.js";
 import { configuredSecrets } from "./credentials.js";
-import { dbosClient, lazyPool } from "./db.js";
+import { dbosClient, lazyDb, spendInviteRequest } from "./db.js";
 import { credentialsOf } from "./env.js";
 import { Principal } from "./define.js";
 import { APPLY_WORKFLOW } from "./apply.js";
@@ -79,7 +81,7 @@ export class SanomaClient {
     /** The config's own ledger store, or a Postgres one made for this client, which `close` then closes. */
     audit;
     /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
-    pool;
+    database;
     /** What a direct call's driver reads secrets from, as a worker's live driver does. */
     storedSecrets;
     /** The operator agent's chats: their rows and their transcripts, in the config's database. */
@@ -93,10 +95,10 @@ export class SanomaClient {
         this.drivers = drivers;
         this.options = options;
         this.audit = ownedLedger(config);
-        this.pool = lazyPool(config.databaseUrl, "client");
-        this.storedSecrets = configuredSecrets(config.secrets, () => this.db());
-        this.chats = chatStore(() => this.db());
-        this.tokens = tokenStore(() => this.db());
+        this.database = lazyDb(config.databaseUrl, "client");
+        this.storedSecrets = configuredSecrets(config.secrets, () => this.database.db());
+        this.chats = chatStore(() => this.database.db());
+        this.tokens = tokenStore(() => this.database.db());
     }
     /**
      * Connects to the runtime's Postgres for the config's app. Checks the config first and throws
@@ -120,7 +122,8 @@ export class SanomaClient {
      * Checks the input against the workflow's schema, then queues a run for the worker. The run
      * gets the input as sent, not as the schema parsed it: the worker parses it once, so a schema
      * with a `.transform` or a default sees the caller's value, and `run.started` records it.
-     * `workflow` is a definition, or the name of one in the config's `workflows`.
+     * `workflow` is a definition, or the name of one in the config's `workflows`. The run is queued
+     * for the client's `appVersion` when it has one.
      */
     async start(workflow, input, options) {
         const startedBy = await this.withSubject(await this.admitted(parseOrThrow(PrincipalOrId, options?.startedBy, '`startedBy` must be a principal, such as "alice" or { id: "alice" }')));
@@ -146,11 +149,11 @@ export class SanomaClient {
         const args = { input, startedBy, ...(sandbox === undefined ? {} : { sandbox }), ...(hold && { hold }) };
         // Kept on the run's status row too, so a listing tells sandbox runs apart without its input,
         // and says whom an agent's run is for (DBOS keeps the principal's id and groups itself); a
-        // change run's code, so a worker on another version with the same takes it over.
+        // built-in run's code, so a worker on another version with the same takes it over.
         const attributes = {
             sandbox,
             onBehalfOf: startedBy.onBehalfOf,
-            changeCode: workflow.name === CHANGE_WORKFLOW ? this.config.changeCode : undefined,
+            builtInCode: this.config.builtInCodes[workflow.name],
         };
         this.options.onWrite?.();
         // An id DBOS has already returns that run, unless it is another workflow's, which DBOS refuses.
@@ -160,6 +163,7 @@ export class SanomaClient {
             workflowName: workflow.name,
             workflowID: runId,
             applicationName: this.config.appName,
+            ...(this.options.appVersion !== undefined && { appVersion: this.options.appVersion }),
             authenticatedUser: startedBy.id,
             authenticatedRoles: startedBy.groups ?? [],
             ...(Object.values(attributes).some((v) => v !== undefined) && { attributes }),
@@ -281,66 +285,66 @@ export class SanomaClient {
         const { dataStore, collections, ledger } = this.config;
         const connectionMutation = op.id.startsWith("sanoma.connection.");
         const transactionStore = connectionMutation
-            ? this.config.connectionPool
+            ? this.config.connectionStore
             : op.vendor === DATA_VENDOR
                 ? dataStore
                 : undefined;
-        const conn = !ledger && transactionStore ? await (await transactionStore.db()).connect() : undefined;
-        let broken;
-        try {
-            await conn?.query("BEGIN");
-            // The metadata or collection driver shares the ledger transaction; neither has an env guard.
-            const fn = conn
-                ? (connectionMutation
-                    ? connectionDriver(this.config.connections.onDatabase(conn))
-                    : collectionsDriver([collections.get(op.resource)], { db: async () => conn })).ops[`${op.resource}.${op.name}`]
-                : call.fn;
-            const at = Date.now();
-            const record = (outcome) => ({
-                v: 1,
-                app: this.config.appName,
-                id: `${runId}:op.called:0`,
-                runId,
-                seq: 0,
-                at,
-                actor,
-                workflow: CALL_WORKFLOW,
-                type: "op.called",
-                op: op.id,
-                effect: op.effect,
-                input: logged,
-                decision,
-                ...(context.connection && { connection: context.connection }),
-                ...outcome,
-                durationMs: Date.now() - at,
-            });
-            let output;
+        const at = Date.now();
+        const record = (outcome) => ({
+            v: 1,
+            app: this.config.appName,
+            id: `${runId}:op.called:0`,
+            runId,
+            seq: 0,
+            at,
+            actor,
+            workflow: CALL_WORKFLOW,
+            type: "op.called",
+            op: op.id,
+            effect: op.effect,
+            input: logged,
+            decision,
+            ...(context.connection && { connection: context.connection }),
+            ...outcome,
+            durationMs: Date.now() - at,
+        });
+        /** Runs the call through `fn`; a failure is recorded on the store's own connection, outside any transaction. */
+        const output = async (fn) => {
             try {
-                output = await outputOf(op, () => fn(parsed, context));
+                return await outputOf(op, () => fn(parsed, context));
             }
             catch (err) {
-                // Recorded on the store's own connection; the transaction is rolled back below.
                 await this.audit.store.append(record({ error: errorInfo(err) }));
                 throw err;
             }
-            const done = record({ output: recorded(op, output) });
-            if (!conn) {
-                await this.audit.store.append(done);
-                return output;
-            }
-            if (await insertRecord(conn, done)) {
-                await conn.query("COMMIT");
-                return output;
-            }
-            await conn.query("ROLLBACK");
-            return (await this.recordedCall(runId, op.id, logged, context.connection)).output;
+        };
+        if (ledger || !transactionStore) {
+            const result = await output(call.fn);
+            await this.audit.store.append(record({ output: recorded(op, result) }));
+            return result;
         }
-        catch (err) {
-            await conn?.query("ROLLBACK").catch((e) => (broken = e));
-            throw err;
+        // The write and its record in one transaction: the metadata or collection driver runs on the
+        // transaction's connection (neither has an env guard), and a record another write of the id
+        // was first with rolls the write back, for the recorded output to stand.
+        const store = await transactionStore.db();
+        try {
+            return await store.transaction(async (tx) => {
+                const fn = (connectionMutation
+                    ? connectionDriver(this.config.connections.onDatabase(tx))
+                    : collectionsDriver([collections.get(op.resource)], { db: async () => tx })).ops[`${op.resource}.${op.name}`];
+                const result = await output(fn);
+                if (await insertRecord(tx, record({ output: recorded(op, result) })))
+                    return result;
+                tx.rollback();
+            });
         }
-        finally {
-            conn?.release(broken);
+        catch (err) {
+            if (!is(err, TransactionRollbackError))
+                throw err;
+            const first = await this.recordedCall(runId, op.id, logged, context.connection);
+            if (!first)
+                throw err;
+            return first.output;
         }
     }
     /**
@@ -413,6 +417,13 @@ export class SanomaClient {
             expiresAt: options.expiresAt.toISOString(),
         }));
     }
+    /**
+     * Spends a sealed invite request's `nonce` (`openInvite`), good until `expiresAt`: true the first
+     * time, false when it was spent already, in this process or another.
+     */
+    async spendInviteRequest(nonce, expiresAt) {
+        return spendInviteRequest(await this.database.db(), nonce, expiresAt);
+    }
     /** When each of `people` last signed in to the staff login, and how, by id (`recordSignIn`); one who never did is left out. */
     lastSignIns(people) {
         return lastSignIns(this.audit.store, people);
@@ -1116,10 +1127,10 @@ export class SanomaClient {
             this.config.connections.close(),
             this.config.identityProvisioning.close(),
             this.dbos.destroy(),
-            this.pool.close(),
+            this.database.close(),
             this.audit.close(),
             this.config.dataStore?.close(),
-            this.config.connectionPool.close(),
+            this.config.connectionStore.close(),
         ]);
     }
     /**
@@ -1140,9 +1151,9 @@ export class SanomaClient {
             issues: [{ path: ["name"], message, code: "custom" }],
         });
     }
-    /** The pool the runtime's tables are read and written with, on the database once it is prepared. */
-    db() {
-        return this.pool.db();
+    /** The pool the client reads and writes with, once the database is prepared: what a login runs on (`LoginContext.database`). */
+    pool() {
+        return this.database.pool();
     }
     /**
      * The principal as the data files declare it (`admit`): its id alone is taken, never the groups