@sanoma-ai/workflows 0.9.0 → 0.10.0

package/src/call-workflow.ts

@@ -1,3 +1,4 @@
+import { connectionRefSchema, type ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
 import { isDirect } from "./direct.ts";
@@ -12,10 +13,10 @@ export { CALL_WORKFLOW } from "./shared.ts";
 // held to the same lint: the call goes through `ctx`, under the policy, in the ledger.
 
 /** An operation on `ctx`. */
-type OpCall = (input: unknown) => Promise<unknown>;
+type OpCall = (input: unknown, options?: { connection?: ConnectionRef }) => Promise<unknown>;
 
 /** The call workflow's input: the operation's id, and its input. */
-export const CallInput = z.object({ op: z.string(), input: z.unknown() });
+export const CallInput = z.object({ op: z.string(), input: z.unknown(), connection: connectionRefSchema.optional() });
 
 /**
  * The call workflow for a config: it `uses` every operation that may be called directly and has
@@ -43,10 +44,10 @@ export function callWorkflow(
       // Four segments for an app's collection: `data.<app>.<collection>.<op>`.
       const [vendor = "", a = "", b = "", c] = input.op.split(".");
       return c === undefined
-        ? ctx[vendor]![a]![b]!(input.input)
+        ? ctx[vendor]![a]![b]!(input.input, { connection: input.connection })
         : (ctx as unknown as Record<string, Record<string, Record<string, Record<string, OpCall>>>>)[vendor]![a]![b]![
             c
-          ]!(input.input);
+          ]!(input.input, { connection: input.connection });
     },
   });
 }

package/src/call.ts

@@ -1,3 +1,4 @@
+import type { ConnectionRef, ConnectionSnapshot } from "./connection.ts";
 import { DBOS, DBOSWorkflowConflictError, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { awaitApproval, type CheckedApproval } from "./approvals.ts";
 import { offsetOf } from "./ast.ts";
@@ -161,8 +162,10 @@ export function buildCtx(wf: WorkflowDefinition<any, any>, run: Run): any {
       .split(".")
       .slice(0, -1)
       .reduce<Record<string, any>>((at, key) => (at[key] ??= {}), members);
-    group[op.name] = placed(op.id, (node, input) =>
-      serial(run, () => callOp(run, op.id, input, { node: node.path, name: named(node) ?? op.id })),
+    group[op.name] = placed(op.id, (node, input, options?: { connection?: ConnectionRef }) =>
+      serial(run, () =>
+        callOp(run, op.id, input, { node: node.path, name: named(node) ?? op.id }, options?.connection),
+      ),
     );
   }
   members.runId = run.id;
@@ -284,8 +287,19 @@ function targetOf(op: Op, input: unknown): { target?: string } {
  * the running instance's people): while it holds or denies, the company's policy is not asked.
  * Runs inside a step, so it must have no side effects of its own.
  */
-export async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
-  const seen = { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) };
+export async function decide(
+  run: Run,
+  op: Op,
+  input: unknown,
+  connection?: ConnectionSnapshot,
+): Promise<RecordedDecision> {
+  const seen = {
+    id: run.id,
+    workflow: run.workflow,
+    approvals: structuredClone(run.approvals).filter(
+      (a) => a.requestedBy !== "policy" || a.connection === connection?.revision,
+    ),
+  };
   // Only a merge is the rule's: no other call reads the people's files.
   const held =
     op.id === CHANGE_MERGE ? runtimeHold(op.id, input, seen.approvals, readPeople(run.state.root).people) : undefined;
@@ -298,7 +312,7 @@ export async function decide(run: Run, op: Op, input: unknown): Promise<Recorded
       { idempotencyKey: `${run.id}:${run.seq}:before`, runId: run.id, opId: get, attempt: 1, secrets: secretsOf(run) },
     ),
   );
-  const call = { ...callOf(op, input, run.actor, seen), ...before };
+  const call = { ...callOf(op, input, run.actor, seen), ...before, ...(connection && { connection }) };
   return ask(policy, op.id, () => policy(call), run.state);
 }
 
@@ -357,7 +371,7 @@ export function decideCall(
   input: unknown,
   actor: Principal,
   run: PolicyCall["run"],
-  before: Pick<PolicyCall, "before"> = {},
+  before: Pick<PolicyCall, "before" | "connection"> = {},
 ): RecordedDecision {
   const call = { ...callOf(op, input, actor, run), ...before };
   return ask(policy, op.id, () => policy(call));
@@ -411,7 +425,7 @@ function ask(
   return policy.version === undefined ? decision : { ...decision, policyVersion: policy.version };
 }
 
-async function callOp(run: Run, id: string, input: unknown, place: Placed) {
+async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?: ConnectionRef) {
   // The worker's declaration, never the workflow's: its effect, schemas and retry setting.
   const op = run.state.ops.get(id);
   // A sandbox run calls its own fakes, never a vendor.
@@ -441,10 +455,36 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The decision is recorded as a step, so a replay reuses it instead of asking a policy
   // that may have changed since. The policy must still be deterministic: a run that fails
   // before the step is recorded asks again.
-  const decideStep = () => DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  const connection = await DBOS.runStep(
+    async () => {
+      if (run.sandbox !== undefined) {
+        if (ref)
+          throw new SanomaError("invalid_input", "Named sandbox connections require explicit fake account state");
+        return undefined;
+      }
+      return run.state.connections?.select(op.vendor, ref, run.actor.id);
+    },
+    { name: `connection:${op.id}` },
+  );
+  const decideStep = () =>
+    DBOS.runStep(
+      async () => {
+        await run.state.connections?.assertCurrent(connection, run.actor.id);
+        return decide(run, op, parsed, connection);
+      },
+      { name: `policy:${op.id}` },
+    );
   let decision = await decideStep();
   const logged = recorded(op, parsed);
-  const call = { type: "op.called", op: op.id, ...place, effect: op.effect, input: logged, decision } as const;
+  const call = {
+    type: "op.called",
+    op: op.id,
+    ...place,
+    effect: op.effect,
+    input: logged,
+    decision,
+    ...(connection && { connection }),
+  } as const;
 
   // Each hold is lifted in turn: once one is approved, the policy is asked again, with it.
   for (;;) {
@@ -462,6 +502,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
         seq,
         input: logged,
         reasons: decision.reasons,
+        connection: connection?.revision,
       });
     } catch (err) {
       // A rejection or a withdrawal stops the call: it is recorded as failed, naming the approval.
@@ -486,6 +527,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
+        await run.state.connections?.assertCurrent(connection, run.actor.id);
         const secrets = secretsOf(run);
         const context: CallContext = {
           idempotencyKey: `${run.id}:${seq}`,
@@ -493,6 +535,8 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
           opId: op.id,
           attempt,
           secrets,
+          principal: run.actor,
+          ...(connection && { connection }),
           // A call run is the person's direct call held for an approval: made as them, as it would have been.
           by: run.workflow === CALL_WORKFLOW ? run.actor.id : `run:${run.id}`,
         };

package/src/cedar.ts

@@ -403,7 +403,20 @@ export function cedarPolicy(
       call.actor,
       call.op.id,
       call.target,
-      { input: call.input, ...(call.before !== undefined && { before: call.before }) },
+      {
+        input: call.input,
+        ...(call.before !== undefined && { before: call.before }),
+        ...(call.connection && {
+          connection: {
+            id: call.connection.id,
+            vendor: call.connection.vendor,
+            method: call.connection.method,
+            account: call.connection.account,
+            revision: call.connection.revision,
+            scopes: call.connection.scopes,
+          },
+        }),
+      },
       call.run.approvals,
       call.run.workflow === CALL_WORKFLOW,
       call.entity,

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(