@sanoma-ai/workflows 0.9.1 → 0.10.0

package/src/change-steps.ts

@@ -15,6 +15,7 @@ import {
   followBase,
   repositoryOf,
   isRules,
+  mayDeclarePeople,
   sourceOfRun,
   touchesOf,
 } from "./change.ts";
@@ -23,7 +24,7 @@ import type { DriftReport } from "./drift.ts";
 import { isRunControlError } from "./errors.ts";
 import { warn } from "./log.ts";
 import { inside } from "./paths.ts";
-import { DECLARES_PEOPLE } from "./resources.ts";
+import { peopleSources } from "./resources.ts";
 import { currentRun, type Run } from "./run.ts";
 import {
   AGENTS,
@@ -48,8 +49,8 @@ const runNow = (): Run => {
   return run;
 };
 
-/** True when the file at `path` is a people file (`DECLARES_PEOPLE`), one `readPeople` would read; false when there is none. */
-const fileDeclaresPeople = async (path: string) => DECLARES_PEOPLE.test(await readFile(path, "utf8").catch(() => ""));
+/** True when the file at `path` is a people file (`mayDeclarePeople`), one `readPeople` would load; false when there is none. */
+const fileDeclaresPeople = async (path: string) => mayDeclarePeople(await readFile(path, "utf8").catch(() => ""));
 
 /** Which events win when several wait: one that ends the change over one that plans it again. */
 const WEIGHT: Record<ChangeEvent["kind"], number> = { commits: 0, close: 1, closed: 2, merged: 3 };
@@ -188,12 +189,14 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
               .filter((file) => file.startsWith("resources/"))
               .flatMap((file) => [join(source.root, file), join(draft.root, file)].map(fileDeclaresPeople)),
           );
+          const sources = peopleSources(source.root);
           return {
             touches,
             strandedRuns: stranded.length,
             stranded,
             checksOk: check.ok,
-            rules: people.includes(true) || touches.some(isRules),
+            // Or a file main's people are read from: a helper a people file imports.
+            rules: people.includes(true) || touches.some(isRules) || files.some((file) => sources.has(file)),
           };
         },
         { name: "change:plan" },

package/src/change.ts

@@ -320,6 +320,16 @@ export const ADMIN = "admin";
  */
 export const isRules = (path: string) =>
   path === "policies/" || path === "resources/people.ts" || /^apps\/[^/]+\/policies\/$/.test(path);
+/**
+ * Whether a data file's text imports the runtime's constructors, `sanoma` (by any local name, or
+ * the whole entry, `* as`, from which it can reach them): a file that may declare a person, agent
+ * or group, which `readPeople` loads and a change to which is a change to the rules. Read from the
+ * text, so a draft's file is told without running it.
+ */
+export const mayDeclarePeople = (text: string): boolean =>
+  /(?:\{[^}]*\bsanoma\b[^}]*\}|\*(?:\s*as\s+[\w$]+)?)\s*from\s*["'](?:sanoma|@sanoma-ai\/workflows)\/resources["']/.test(
+    text,
+  );
 /** The runtime rule's id, as a hold's `reasons` name it. */
 const RULES_WAIT_FOR_ADMIN = "sanoma:rules-wait-for-admin";
 

package/src/client.ts

@@ -1,3 +1,4 @@
+import { connectionDriver, type ConnectionRef, type ConnectionSnapshot } from "./connection.ts";
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { type DBOSClient, Error as DBOSErrors, type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
@@ -16,7 +17,7 @@ import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call
 import { type Chats, chatStore } from "./chats.ts";
 import { collectionsDriver } from "./collection.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
-import { deleteCredential, storeCredential, storedCredentials, storedSecrets } from "./credentials.ts";
+import { configuredSecrets } from "./credentials.ts";
 import { dbosClient, lazyPool, type LazyPool } from "./db.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
 import { type ApprovalState, Principal, type WorkflowDefinition } from "./define.ts";
@@ -52,7 +53,7 @@ import type { CallContext, Driver, Op } from "./op.ts";
 import { allowAll, type RecordedDecision } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
 import type { RunArgs, StartHold } from "./run.ts";
-import type { Secrets } from "./secret.ts";
+import type { SecretAccess, SecretLocation } from "./secret-store.ts";
 import {
   BUILT_IN_WORKFLOWS,
   CALL_WORKFLOW,
@@ -206,6 +207,7 @@ export interface ChangesFilter {
 
 /** What `SanomaClient.call` takes besides the operation's id and its input. */
 export interface CallOptions {
+  connection?: ConnectionRef;
   /**
    * Who calls, by id, admitted as `startedBy` is: the policy decides as them, a write's record
    * names them, and a save's `updatedBy` is their id.
@@ -243,7 +245,7 @@ export class SanomaClient {
   /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
   private readonly pool: LazyPool;
   /** What a direct call's driver reads secrets from, as a worker's live driver does. */
-  private readonly storedSecrets: Secrets;
+  private readonly storedSecrets: SecretAccess;
   /** The operator agent's chats: their rows and their transcripts, in the config's database. */
   readonly chats: Chats;
   private readonly options: ClientOptions;
@@ -260,7 +262,7 @@ export class SanomaClient {
     this.options = options;
     this.audit = ownedLedger(config);
     this.pool = lazyPool(config.databaseUrl, "client");
-    this.storedSecrets = storedSecrets(() => this.db(), "sanoma");
+    this.storedSecrets = configuredSecrets(config.secrets, () => this.db());
     this.chats = chatStore(() => this.db());
   }
 
@@ -272,7 +274,14 @@ export class SanomaClient {
   static async connect(config: SanomaConfig, options: ClientOptions = {}): Promise<SanomaClient> {
     const resolved = resolveConfig(config);
     const dbos = await dbosClient(resolved.databaseUrl, resolved.appName);
-    return new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+    const client = new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+    try {
+      await client.storedSecrets.validate();
+      return client;
+    } catch (error) {
+      await client.close();
+      throw error;
+    }
   }
 
   /**
@@ -414,14 +423,21 @@ export class SanomaClient {
     const fn = drivers.get(op.id);
     if (!fn) throw new SanomaError("invalid_input", `${op.id} has no driver: the connector package must attach one`);
     const parsed = parseOrThrow(op.input, input, `The input to ${op.id} does not match its schema`, { op: op.id });
+    const connection = await this.config.connections.select(op.vendor, options.connection, actor.id);
+    const selected = connection && {
+      $connection: connection.id,
+      vendor: connection.vendor,
+      revision: connection.revision,
+    };
     const runId = `direct:${actor.id}:${id}`;
     const heldId = `call:${actor.id}:${id}`;
-    const held: RunArgs = { input: { op: op.id, input }, startedBy: actor };
+    const held: RunArgs = { input: { op: op.id, input, ...(selected && { connection: selected }) }, startedBy: actor };
     const logged = recorded(op, parsed);
     const write = op.effect !== "read";
     // Only an id the caller gave can have been used: a write made, or held, with it settles it.
     if (write && options.id !== undefined) {
-      const first = (await this.recordedCall(runId, op.id, logged)) ?? (await this.heldCall(op.id, heldId, held));
+      const first =
+        (await this.recordedCall(runId, op.id, logged, connection)) ?? (await this.heldCall(op.id, heldId, held));
       if (first) return first.output;
     }
     const before = await beforeOf(policy, op, parsed, this.config.collections, (get, key) =>
@@ -431,7 +447,7 @@ export class SanomaClient {
       ),
     );
     const run = { id: runId, workflow: CALL_WORKFLOW, approvals: [] };
-    const decision = decideCall(policy, op, parsed, actor, run, before);
+    const decision = decideCall(policy, op, parsed, actor, run, { ...before, ...(connection && { connection }) });
     if (decision.kind === "deny") throw new PolicyDeniedError(op.id, decision.reason);
     if (decision.kind === "approve") {
       await this.start(CALL_WORKFLOW, held.input, { startedBy: actor, runId: heldId });
@@ -445,7 +461,10 @@ export class SanomaClient {
       attempt: 1,
       secrets: this.storedSecrets,
       by: actor.id,
+      principal: actor,
+      ...(connection && { connection }),
     };
+    await this.config.connections.assertCurrent(connection, actor.id);
     if (!write) return outputOf(op, () => fn(parsed, context));
     return this.directWrite({ op, fn, parsed, logged, actor, decision, context });
   }
@@ -469,13 +488,22 @@ export class SanomaClient {
     const { op, parsed, logged, actor, decision, context } = call;
     const { runId } = context;
     const { dataStore, collections, ledger } = this.config;
-    const conn = op.vendor === DATA_VENDOR && !ledger && dataStore ? await (await dataStore.db()).connect() : undefined;
+    const connectionMutation = op.id.startsWith("sanoma.connection.");
+    const transactionStore = connectionMutation
+      ? this.config.connectionPool
+      : op.vendor === DATA_VENDOR
+        ? dataStore
+        : undefined;
+    const conn = !ledger && transactionStore ? await (await transactionStore.db()).connect() : undefined;
     let broken: Error | undefined;
     try {
       await conn?.query("BEGIN");
-      // On the transaction's connection, the collection's own driver: it has no `env` to guard.
+      // The metadata or collection driver shares the ledger transaction; neither has an env guard.
       const fn = conn
-        ? collectionsDriver([collections.get(op.resource)!], { db: async () => conn }).ops[`${op.resource}.${op.name}`]!
+        ? (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: { output: unknown } | { error: ErrorInfo }): LedgerRecord => ({
@@ -492,6 +520,7 @@ export class SanomaClient {
         effect: op.effect,
         input: logged,
         decision,
+        ...(context.connection && { connection: context.connection }),
         ...outcome,
         durationMs: Date.now() - at,
       });
@@ -513,7 +542,7 @@ export class SanomaClient {
         return output;
       }
       await conn.query("ROLLBACK");
-      return (await this.recordedCall(runId, op.id, logged))!.output;
+      return (await this.recordedCall(runId, op.id, logged, context.connection))!.output;
     } catch (err) {
       await conn?.query("ROLLBACK").catch((e: Error) => (broken = e));
       throw err;
@@ -526,10 +555,19 @@ export class SanomaClient {
    * What the direct write recorded as `runId` returned, when one did: refused (`invalid_input`)
    * when it was of another operation or input, and its failure again (`driver_failed`) when it failed.
    */
-  private async recordedCall(runId: string, opId: string, input: unknown): Promise<{ output: unknown } | undefined> {
+  private async recordedCall(
+    runId: string,
+    opId: string,
+    input: unknown,
+    connection?: ConnectionSnapshot,
+  ): Promise<{ output: unknown } | undefined> {
     const first = (await this.audit.store.read(runId)).find((r) => r.type === "op.called");
     if (!first) return undefined;
-    const differs = [...(first.op === opId ? [] : ["op"]), ...(sameJson(first.input, input) ? [] : ["input"])];
+    const differs = [
+      ...(first.op === opId ? [] : ["op"]),
+      ...(sameJson(first.input, input) ? [] : ["input"]),
+      ...(sameJson(first.connection ?? null, connection ?? null) ? [] : ["connection"]),
+    ];
     if (differs.length) {
       throw new SanomaError(
         "invalid_input",
@@ -1061,7 +1099,8 @@ export class SanomaClient {
         issues: [{ path: ["value"], message: problem, code: "custom" }],
       });
     }
-    await storeCredential(await this.db(), { name, value, setBy });
+    const current = await this.storedSecrets.read(name);
+    await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
   }
 
   /**
@@ -1072,7 +1111,8 @@ export class SanomaClient {
   async clearCredential(name: string, options: { by: string }): Promise<void> {
     await this.admittedBy(options);
     this.declared(name, () => undefined);
-    await deleteCredential(await this.db(), name);
+    const current = await this.storedSecrets.read(name);
+    if (current) await this.storedSecrets.delete(name, { expectedVersion: current.version, by: options.by });
   }
 
   /**
@@ -1091,7 +1131,21 @@ export class SanomaClient {
       const path = VARIABLE.test(name) ? "value" : "name";
       throw new SanomaError("invalid_input", problem, { issues: [{ path: [path], message: problem, code: "custom" }] });
     }
-    await storeCredential(await this.db(), { name, value, setBy });
+    const current = await this.storedSecrets.read(name);
+    await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
+  }
+
+  /** Removes a logical secret from the selected store; external bindings remain read-only. */
+  async clearSecret(name: string, options: { by: string }): Promise<void> {
+    const by = await this.admittedBy(options);
+    if (!VARIABLE.test(name)) {
+      const message = "That is not a variable name";
+      throw new SanomaError("invalid_input", message, {
+        issues: [{ path: ["name"], message, code: "custom" }],
+      });
+    }
+    const current = await this.storedSecrets.read(name);
+    if (current) await this.storedSecrets.delete(name, { expectedVersion: current.version, by });
   }
 
   /**
@@ -1100,40 +1154,51 @@ export class SanomaClient {
    * is left out. For server code: a page is told whether one is set, never its value.
    */
   async secrets(names: readonly string[]): Promise<Map<string, StoredSecret>> {
-    const rows = await storedCredentials(await this.db(), names);
     const found = new Map<string, StoredSecret>();
     for (const name of names) {
-      const env = process.env[name];
-      const row = rows.get(name);
-      if (env && env !== row?.value) found.set(name, { value: env, source: "environment" });
-      else if (row) found.set(name, { ...row, source: "stored" });
+      const row = await this.storedSecrets.read(name);
+      const location = this.storedSecrets.location(name);
+      if (row)
+        found.set(name, {
+          value: row.value,
+          source: location.store === "environment" ? "environment" : "stored",
+          version: row.version,
+          location,
+          ...(row.updatedBy && { setBy: row.updatedBy }),
+          ...(row.updatedAt && { setAt: row.updatedAt }),
+        });
     }
     return found;
   }
 
-  /**
-   * Each vendor's declared variables and their statuses now: from this process's environment,
-   * which wins, else from the stored credentials, with `source` saying which (a value equal to
-   * the stored one, as a worker in this process loads it, is `stored`), and who set a stored one
-   * and when. Never a value.
-   */
+  /** Non-secret statuses for the selected store and declared bindings. */
   async credentials(): Promise<Map<string, CredentialStatus[]>> {
     const names = [...credentialsOf(this.drivers, () => undefined).values()].flat().map((c) => c.name);
-    if (!names.length) return new Map();
-    const rows = await storedCredentials(await this.db(), names);
-    const statuses = credentialsOf(this.drivers, (name) => process.env[name] || rows.get(name)?.value);
-    const sourced = (c: CredentialStatus): CredentialStatus => {
-      const row = rows.get(c.name);
-      const env = process.env[c.name];
-      // A worker in this process loads the stored values into its environment: those are stored.
-      if (env && env !== row?.value) return { ...c, source: "environment" };
-      return row ? { ...c, source: "stored", setBy: row.setBy, setAt: row.setAt } : c;
-    };
-    return new Map([...statuses].map(([vendor, list]) => [vendor, list.map(sourced)]));
+    const rows = await this.secrets(names);
+    const statuses = credentialsOf(this.drivers, (name) => rows.get(name)?.value);
+    return new Map(
+      [...statuses].map(([vendor, list]) => [
+        vendor,
+        list.map((c) => {
+          const row = rows.get(c.name);
+          return {
+            ...c,
+            location: this.storedSecrets.location(c.name),
+            ...(row && { source: row.source, setBy: row.setBy, setAt: row.setAt }),
+          };
+        }),
+      ]),
+    );
   }
 
   async close() {
-    await Promise.all([this.dbos.destroy(), this.pool.close(), this.audit.close(), this.config.dataStore?.close()]);
+    await Promise.all([
+      this.dbos.destroy(),
+      this.pool.close(),
+      this.audit.close(),
+      this.config.dataStore?.close(),
+      this.config.connectionPool.close(),
+    ]);
   }
 
   /**
@@ -1285,6 +1350,8 @@ const sameJson = (a: unknown, b: unknown): boolean => isDeepStrictEqual(asJson(a
 
 /** A secret's value as `SanomaClient.secrets` reads it, and where from. */
 export interface StoredSecret {
+  version?: string;
+  location?: SecretLocation;
   value: string;
   source: "environment" | "stored";
   /** Who stored it (`setSecret`'s `by`), and when, as an ISO 8601 time. */
@@ -1293,7 +1360,7 @@ export interface StoredSecret {
 }
 
 /** What an environment variable's name looks like. */
-const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
+const VARIABLE = /^[A-Z][A-Z0-9_]*$/;
 
 const alreadyDecided = (runId: string, a: ApprovalState) =>
   new SanomaError(

package/src/collection.ts

@@ -99,10 +99,18 @@ export function collection<
   const F extends Record<string, Field>,
   const K extends RequiredTextKeys<F>,
 >(declaration: { name: N; key: K; fields: F; title?: string }): Collection<N, F, K> {
+  // Frame 2 of `callerFile` is this function's caller: the data file.
+  return collectionIn(appOfFile(callerFile()), declaration);
+}
+
+/** `collection()` in the app `app` names (none for the root's): what the loader's `collection` calls, knowing the file itself. */
+export function collectionIn<
+  const N extends string,
+  const F extends Record<string, Field>,
+  const K extends RequiredTextKeys<F>,
+>(app: string | undefined, declaration: { name: N; key: K; fields: F; title?: string }): Collection<N, F, K> {
   checkCollection(declaration);
   const { key, fields, title } = declaration;
-  // Frame 2 of `callerFile` is this function's caller: the data file.
-  const app = appOfFile(callerFile());
   const name = qualified(app, declaration.name);
   const record = z.strictObject(
     Object.fromEntries(

package/src/config.ts

@@ -1,3 +1,14 @@
+import { configuredSecrets } from "./credentials.ts";
+import { currentRun } from "./run.ts";
+import {
+  connectionCatalog,
+  ConnectionRegistry,
+  connectionDriver,
+  connectionOps,
+  type ConnectionDefinition,
+  type ConnectionRule,
+} from "./connection.ts";
+import { checkSecretConfiguration, type SecretConfiguration } from "./secret-store.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -81,6 +92,10 @@ export interface SanomaConfig {
    * only, for tests.
    */
   ledger?: LedgerStore;
+  /** Credential storage and explicit bindings. Omitted: encrypted Postgres, no environment fallback. */
+  secrets?: SecretConfiguration;
+  connections?: readonly ConnectionDefinition[];
+  connectionRules?: readonly ConnectionRule[];
   /** Postgres for the runtime. Defaults to `SANOMA_DATABASE_URL`, then `DEFAULT_DATABASE_URL`. */
   databaseUrl?: string;
   /** The file that defined the config, absolute, when known. Set by `defineConfig` from its call site. */
@@ -118,6 +133,9 @@ export interface SanomaConfig {
 
 /** A config, checked, with everything a worker, client or app derives from it. */
 export interface ResolvedConfig {
+  secrets: SecretConfiguration;
+  connections: ConnectionRegistry;
+  connectionPool: LazyPool;
   /**
    * Scopes workflows, queues and versions in the system database: the `name` of
    * `<root>/package.json` when it names one, else "sanoma".
@@ -252,6 +270,7 @@ export function rootOf(config: Pick<SanomaConfig, "root" | "file">): string | un
  * `startApp`, the `sanoma` bin when it loads the config.
  */
 export function resolveConfig(config: SanomaConfig): ResolvedConfig {
+  checkSecretConfiguration(config.secrets ?? {});
   if (!Array.isArray(config.connectors)) {
     throw new Error("The config needs `connectors`: the connectors its workflows call, as their packages export them");
   }
@@ -280,6 +299,12 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const hostTyped = [...types.values()].some((type) => type.host);
   // Built-in: the collections' operations, `data.<name>.<op>`, on the config's database.
   const databaseUrl = resolveDatabaseUrl(config);
+  const connectionPool = lazyPool(databaseUrl, "connections");
+  const connections = new ConnectionRegistry(
+    connectionCatalog(config.connectors, config.connections, config.connectionRules),
+    () => connectionPool.db(),
+    configuredSecrets(config.secrets ?? {}, () => connectionPool.db()),
+  );
   const declared = [...collections.values()];
   const dataStore = declared.length ? lazyPool(databaseUrl, "data") : undefined;
   // Built-in, in every config: a change's operations, which the template's policy names
@@ -287,6 +312,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const ops = indexConnectors([
     ...running,
     changeOps,
+    connectionOps,
     appsListOps,
     ...(hostTyped ? [sourceOps] : []),
     ...(dataStore ? [collectionsConnector(declared)] : []),
@@ -299,6 +325,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     [
       ...driversByVendor.values(),
       changeDriver(remotes),
+      connectionDriver(connections),
       appsListDriver,
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
@@ -326,7 +353,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const connectors = connectorsOf(config);
   // The types the data files may declare: the vendors' and the people's, whose resources are left out.
   const declarable = resourceTypesOf(connectors);
-  const read = () => readDeclared(root, connectors, declarable, types);
+  const read = () => readDeclared(root, connectors, declarable, types, connections);
   if (types.size) {
     names.set(
       DRIFT_WORKFLOW,
@@ -343,6 +370,9 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   if (call.uses.length) names.set(CALL_WORKFLOW, call);
   const { policy, policies, problems: policyProblems } = policyAt(root, { ops, workflows: names, collections });
   return {
+    secrets: config.secrets ?? {},
+    connections,
+    connectionPool,
     appName,
     databaseUrl,
     // The built-in's code and operations are part of the app's version, like the config's own.
@@ -495,9 +525,9 @@ export async function declaredWakeup(config: SanomaConfig): Promise<DeclaredWake
   const connectors = connectorsOf(config);
   const types = resourceTypesOf(connectors);
   if (![...types.values()].some((type) => type.wakeup)) return undefined;
-  // Loaded when it is needed, not with the worker: the reader parses with oxc-parser.
-  const { readDataFiles } = await import("./resources.ts");
-  const { resources } = readDataFiles(rootOf(config), connectors, types);
+  // Loaded when it is needed, not with the worker.
+  const { loadDataFiles } = await import("./resources.ts");
+  const { resources } = loadDataFiles(rootOf(config), connectors, types);
   const typeOf = (r: DeclaredResource) => types.get(`${r.vendor}.${r.type}`)!;
   const declared = resources.find((r) => typeOf(r).wakeup);
   if (!declared) return undefined;
@@ -523,15 +553,38 @@ async function readDeclared(
   connectors: readonly Connector<any, any>[],
   declarable: ReadonlyMap<string, Resource>,
   types: ReadonlyMap<string, Resource>,
+  connections: ConnectionRegistry,
 ): Promise<Omit<ApplyDeclared, "rebinds">> {
-  // Loaded when a run reads the files, not with the worker: the reader parses with oxc-parser.
-  const { readDataFiles } = await import("./resources.ts");
-  const { resources, bindings, orphans, problems } = readDataFiles(root, connectors, declarable);
+  // Loaded when a run reads the files, not with the worker.
+  const { loadDataFiles } = await import("./resources.ts");
+  const { resources, bindings, orphans, problems } = loadDataFiles(root, connectors, declarable);
+  // Read inside the data-file durable step: every operation of the plan uses one pinned account.
+  const run = currentRun.getStore();
+  if (run && !run.sandbox) {
+    for (const resource of resources.filter((r) => types.has(`${r.vendor}.${r.type}`))) {
+      try {
+        const selected = await connections.select(resource.vendor, resource.connection, run.actor.id);
+        if (selected) {
+          const pinned = { vendor: selected.vendor, $connection: selected.id, revision: selected.revision };
+          const locked = bindings[resource.id]?.connection;
+          if (locked && (locked.$connection !== pinned.$connection || locked.revision !== pinned.revision))
+            throw new Error("The bound resource's account changed; explicitly unbind before using a new account");
+          resource.connection = pinned;
+        }
+      } catch {
+        problems.push({
+          file: resource.file,
+          message: `${resource.id}: its connection is unavailable or changed; reconnect and explicitly rebind`,
+        });
+        resources.splice(resources.indexOf(resource), 1);
+      }
+    }
+  }
   return {
     // Only `types`' resources have a vendor object to check or apply: not the people's (vendorless).
     resources: resources
       .filter((r) => types.has(`${r.vendor}.${r.type}`))
-      .map(({ id, vendor, type, name, identity, binding, desired, refs }) => ({
+      .map(({ id, vendor, type, name, identity, binding, desired, refs, connection }) => ({
         id,
         vendor,
         type,
@@ -540,6 +593,7 @@ async function readDeclared(
         ...(binding !== undefined && { binding }),
         desired: withoutWriteOnly(types.get(`${vendor}.${type}`)!.fields, desired),
         refs,
+        ...(connection && { connection }),
       })),
     bindings,
     orphans,