@sanoma-ai/workflows 0.10.0 → 0.10.2

package/src/connection.ts

@@ -1,11 +1,21 @@
 import type { Principal } from "./define.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { checkAuthenticationStore, defineAuthentication, type Authentication } from "./authentication.ts";
+import {
+  checkAuthenticationStore,
+  decodeCredentials,
+  defineAuthentication,
+  verifyAuthentication,
+  AuthenticationError,
+  authenticationProblem,
+  type AuthenticationProblem,
+  type Authentication,
+  type CallAuthentication,
+} from "./authentication.ts";
 import { type Connector, setupOf, VENDOR, defineConnector, defineDriver, type CallContext } from "./op.ts";
 import { isSecret, type Secret } from "./secret.ts";
 import { SanomaError } from "./errors.ts";
-import type { SecretAccess } from "./secret-store.ts";
+import { SecretStoreError, type SecretAccess, type SecretLocation } from "./secret-store.ts";
 import type { Db } from "./db.ts";
 
 /** Serializable account reference; vendor literal prevents cross-connector selection in typed calls. */
@@ -40,6 +50,51 @@ export interface ConnectionSnapshot {
   /** A logical reference only, never the value or a provider credential. */
   credentials?: Secret;
 }
+export type ConnectionTarget = { connection: ConnectionRef } | { rule: string };
+export interface ConnectionCard {
+  id: string;
+  vendor: string;
+  name: string;
+  method: string;
+  account?: string;
+  scopes: readonly string[];
+  requiredScopes: readonly string[];
+  expectedAccount?: string;
+  revision?: string;
+  owner?: string;
+  status: "missing" | "connected" | "disconnected" | "pending" | "uncertain" | "configuration_changed";
+  location?: SecretLocation;
+  boundLocation?: SecretLocation;
+  updatedBy?: string;
+  updatedAt?: string;
+  health?: ConnectionHealth;
+}
+export interface ConnectionHealth {
+  state:
+    | AuthenticationProblem
+    | "connected"
+    | "disconnected"
+    | "pending"
+    | "configuration_changed"
+    | "store_denied"
+    | "invalid";
+  checkedAt: string;
+  externallyRenewed: boolean;
+}
+export interface ConnectionSetup {
+  target: ConnectionTarget;
+  id: string;
+  vendor: string;
+  method: string;
+  definition: string;
+  credential?: string;
+  location?: SecretLocation;
+  expectedRevision: string | null;
+  requiredScopes: readonly string[];
+  expectedAccount?: string;
+  previousAccount?: string;
+  previousLocation?: SecretLocation;
+}
 const idPart = /^[a-z][a-z0-9-]{0,63}$/;
 function refuse(message: string): never {
   throw new SanomaError("invalid_input", message);
@@ -59,6 +114,28 @@ const snapshotSchema = z.object({
   definition: z.string(),
   credentials: z.object({ $secret: z.string() }).optional(),
 });
+export const connectionTargetSchema = z.union([
+  z.object({ connection: connectionRefSchema }),
+  z.object({ rule: z.string().min(1) }),
+]);
+const setupSchema = z.object({
+  target: connectionTargetSchema,
+  id: z.string(),
+  vendor: z.string(),
+  method: z.string(),
+  definition: z.string(),
+  credential: z.string().optional(),
+  location: z
+    .object({ store: z.string(), namespace: z.string(), path: z.string(), management: z.enum(["sanoma", "external"]) })
+    .optional(),
+  expectedRevision: z.string().nullable(),
+  requiredScopes: z.array(z.string()),
+  expectedAccount: z.string().optional(),
+  previousAccount: z.string().optional(),
+  previousLocation: z
+    .object({ store: z.string(), namespace: z.string(), path: z.string(), management: z.enum(["sanoma", "external"]) })
+    .optional(),
+});
 
 export function defineConnection<C extends Connector<any, any>>(
   connector: C,
@@ -189,7 +266,13 @@ type ConnectionRow = {
   revision: string;
   definition: string;
   credential: string | null;
-  status: "connected" | "disconnected";
+  location?: SecretLocation | null;
+  status: "connected" | "disconnected" | "pending" | "uncertain";
+  updated_by?: string;
+  updated_at?: Date;
+  health?: ConnectionHealth["state"];
+  checked_at?: Date;
+  externally_renewed?: boolean;
 };
 const snapshot = (r: ConnectionRow): ConnectionSnapshot => ({
   id: r.id,
@@ -222,6 +305,285 @@ export class ConnectionRegistry {
     return new ConnectionRegistry(this.catalog, async () => db, this.secrets);
   }
 
+  /** Safe card data only. Listing does not read credential values or contact a vendor. */
+  async cards(actor: string): Promise<ConnectionCard[]> {
+    const rows = (
+      await (
+        await this.db()
+      ).query<ConnectionRow>(
+        "SELECT c.*, h.health, h.checked_at, h.externally_renewed FROM sanoma_connections c LEFT JOIN sanoma_connection_health h ON c.id=h.connection_id AND c.revision=h.revision WHERE c.owner IS NULL OR c.owner=$1",
+        [actor],
+      )
+    ).rows;
+    const found = new Map(rows.map((r) => [r.id, r]));
+    const ids = new Set([...this.catalog.definitions.keys(), ...rows.filter((r) => r.rule).map((r) => r.id)]);
+    const cards: ConnectionCard[] = [];
+    for (const id of ids) {
+      const row = found.get(id);
+      const declaration = row?.rule ? this.catalog.rules.get(row.rule) : this.catalog.definitions.get(id);
+      if (!declaration || (row?.rule && row.owner !== actor)) continue;
+      const method = this.catalog.methods.get(declaration.vendor)?.[declaration.method];
+      if (!method) continue;
+      const credential =
+        method.kind === "workload-identity"
+          ? undefined
+          : "default" in declaration
+            ? declaration.credentials?.$secret
+            : row?.credential;
+      cards.push({
+        id,
+        vendor: declaration.vendor,
+        name: row?.rule ? id.slice(declaration.vendor.length + 1) : declaration.name,
+        method: declaration.method,
+        ...(row && { account: row.account, revision: row.revision }),
+        scopes: row?.scopes ?? [],
+        requiredScopes: declaration.scopes,
+        ...("account" in declaration && declaration.account && { expectedAccount: declaration.account }),
+        ...(row?.owner && { owner: row.owner }),
+        status: !row
+          ? "missing"
+          : row.definition !== this.bindingFingerprint(declaration, method, credential)
+            ? "configuration_changed"
+            : row.status,
+        ...(credential && this.secrets && { location: this.secrets.location(credential) }),
+        ...(row?.location && { boundLocation: row.location }),
+        ...(row?.updated_by && { updatedBy: row.updated_by }),
+        ...(row?.updated_at && { updatedAt: row.updated_at.toISOString() }),
+        ...(row?.health &&
+          row.checked_at && {
+            health: {
+              state: row.health,
+              checkedAt: row.checked_at.toISOString(),
+              externallyRenewed: row.externally_renewed ?? false,
+            },
+          }),
+      });
+    }
+    return cards;
+  }
+
+  /** Resolve code-defined setup authority without reading a credential. The request id stays
+   * stable across preview, approval and retry; account allocation is scoped to its principal. */
+  async setup(target: ConnectionTarget, actor: Principal, requestId: string): Promise<ConnectionSetup> {
+    let declaration: ConnectionDefinition | ConnectionRule | undefined;
+    let row: ConnectionRow | undefined;
+    let id: string;
+    let credential: string | undefined;
+    if ("rule" in target) {
+      const rule = this.catalog.rules.get(target.rule);
+      if (
+        !rule ||
+        !rule.createBy.some((by) => (typeof by === "string" ? by === actor.id : actor.groups?.includes(by.group)))
+      )
+        throw new SanomaError("policy_denied", "This principal cannot create connections under this rule");
+      declaration = rule;
+      const allocation = createHash("sha256")
+        .update(JSON.stringify([actor.id, target.rule, requestId]))
+        .digest("hex");
+      id = `${target.rule}/${allocation}`;
+      credential = `CONNECTION_${allocation.toUpperCase()}`;
+      row = await this.row(id);
+    } else {
+      id = target.connection.$connection;
+      row = await this.row(id);
+      declaration = row?.rule ? this.catalog.rules.get(row.rule) : this.catalog.definitions.get(id);
+      if (!declaration || declaration.vendor !== target.connection.vendor) refuse("The connection is not declared");
+      if (row?.rule && row.owner !== actor.id)
+        throw new SanomaError("policy_denied", "The connection belongs to another principal");
+      credential = "credentials" in declaration ? declaration.credentials?.$secret : (row?.credential ?? undefined);
+    }
+    const method = this.catalog.methods.get(declaration.vendor)?.[declaration.method];
+    if (!method?.verify) throw new AuthenticationError("unsupported");
+    if (method.kind === "workload-identity") credential = undefined;
+    this.checkStore(method, credential);
+    return {
+      target,
+      id,
+      vendor: declaration.vendor,
+      method: declaration.method,
+      definition: this.bindingFingerprint(declaration, method, credential),
+      ...(credential && { credential, ...(this.secrets && { location: this.secrets.location(credential) }) }),
+      expectedRevision: row?.revision ?? null,
+      requiredScopes: declaration.scopes,
+      ...("account" in declaration && declaration.account && { expectedAccount: declaration.account }),
+      ...(row && { previousAccount: row.account }),
+      ...(row?.location && { previousLocation: row.location }),
+    };
+  }
+
+  /** Metadata-only, policy-authorized reservation. Calls cannot use it until activation verifies
+   * the saved bundle. A store write failure leaves an explicit uncertain, unusable account. */
+  async configure(
+    target: ConnectionTarget,
+    requestId: string,
+    expectedRevision: string | null,
+    definition: string,
+    account: string,
+    scopes: string[],
+    actor: Principal,
+  ): Promise<ConnectionSnapshot> {
+    const setup = await this.setup(target, actor, requestId);
+    if (setup.definition !== definition || setup.expectedRevision !== expectedRevision)
+      refuse("The connection changed; review it again before saving");
+    if (setup.expectedAccount && setup.expectedAccount !== account) throw new AuthenticationError("wrong_account");
+    if (setup.requiredScopes.some((s) => !scopes.includes(s))) throw new AuthenticationError("scope_changed");
+    const current = await this.row(setup.id);
+    const row: ConnectionRow = {
+      id: setup.id,
+      vendor: setup.vendor,
+      method: setup.method,
+      owner: "rule" in target ? actor.id : (current?.owner ?? null),
+      rule: "rule" in target ? target.rule : (current?.rule ?? null),
+      account,
+      scopes,
+      revision: randomUUID(),
+      definition,
+      credential: setup.credential ?? null,
+      status: "pending",
+    };
+    await this.save(row, expectedRevision, actor.id);
+    return snapshot(row);
+  }
+
+  async uncertain(ref: ConnectionRef, revision: string, actor: string): Promise<void> {
+    await (
+      await this.db()
+    ).query(
+      "UPDATE sanoma_connections SET status='uncertain',updated_by=$3,updated_at=now() WHERE id=$1 AND revision=$2 AND status='pending'",
+      [ref.$connection, revision, actor],
+    );
+  }
+
+  async storedVersion(id: string, revision: string): Promise<string | undefined> {
+    return (
+      await (
+        await this.db()
+      ).query<{ credential_version: string }>(
+        "SELECT credential_version FROM sanoma_connection_setups WHERE connection_id=$1 AND revision=$2",
+        [id, revision],
+      )
+    ).rows[0]?.credential_version;
+  }
+
+  async recordStoredVersion(id: string, revision: string, version: string): Promise<void> {
+    await (
+      await this.db()
+    ).query(
+      "INSERT INTO sanoma_connection_setups (connection_id,revision,credential_version) SELECT id,revision,$3 FROM sanoma_connections WHERE id=$1 AND revision=$2 AND status='pending' ON CONFLICT DO NOTHING",
+      [id, revision, version],
+    );
+    if ((await this.storedVersion(id, revision)) !== version) throw new SecretStoreError("conflict");
+  }
+
+  private async health(
+    id: string,
+    revision: string,
+    state: ConnectionHealth["state"],
+    version?: string,
+    external = false,
+  ): Promise<ConnectionHealth> {
+    const previous = (
+      await (
+        await this.db()
+      ).query<{ credential_version: string | null }>(
+        "SELECT credential_version FROM sanoma_connection_health WHERE connection_id=$1 AND revision=$2",
+        [id, revision],
+      )
+    ).rows[0];
+    const renewed =
+      external &&
+      previous?.credential_version != null &&
+      version !== undefined &&
+      previous.credential_version !== version;
+    const result = await (
+      await this.db()
+    ).query<{ checked_at: Date }>(
+      "INSERT INTO sanoma_connection_health (connection_id,revision,health,credential_version,externally_renewed) SELECT id,revision,$3,$4,$5 FROM sanoma_connections WHERE id=$1 AND revision=$2 ON CONFLICT(connection_id) DO UPDATE SET revision=excluded.revision,health=excluded.health,credential_version=excluded.credential_version,externally_renewed=excluded.externally_renewed,checked_at=now() RETURNING checked_at",
+      [id, revision, state, version ?? previous?.credential_version ?? null, renewed],
+    );
+    const checked = result.rows[0];
+    if (!checked) refuse("The connection changed during the test; reload before testing it again");
+    return { state, checkedAt: checked.checked_at.toISOString(), externallyRenewed: renewed };
+  }
+
+  async test(ref: ConnectionRef, actor: Principal): Promise<ConnectionHealth> {
+    const setup = await this.setup({ connection: ref }, actor, "test");
+    const row = await this.row(setup.id);
+    if (!row) return { state: "missing", checkedAt: new Date().toISOString(), externallyRenewed: false };
+    if (row.definition !== setup.definition)
+      return { state: "configuration_changed", checkedAt: new Date().toISOString(), externallyRenewed: false };
+    if (row.status !== "connected") return this.health(row.id, row.revision, row.status);
+    try {
+      const material = await this.authenticate(snapshot(row), actor.id);
+      return this.health(
+        row.id,
+        row.revision,
+        "connected",
+        material.credentialVersion,
+        setup.location?.management === "external" || !this.secrets?.store.capabilities.writable,
+      );
+    } catch (error) {
+      const code = (error as { code?: string })?.code;
+      const state =
+        authenticationProblem(error) ??
+        (code === "denied" ? "store_denied" : code === "invalid_value" ? "invalid" : "unavailable");
+      return this.health(row.id, row.revision, state);
+    }
+  }
+
+  async setupState(selected: ConnectionSnapshot, actor: Principal): Promise<"pending" | "connected"> {
+    const setup = await this.setup(
+      { connection: { vendor: selected.vendor, $connection: selected.id } },
+      actor,
+      "state",
+    );
+    const row = await this.row(selected.id);
+    if (
+      !row ||
+      row.definition !== setup.definition ||
+      row.account !== selected.account ||
+      JSON.stringify(row.scopes.toSorted()) !== JSON.stringify(selected.scopes.toSorted())
+    )
+      refuse("The connection changed; review it again before saving");
+    if (row.status === "connected") return "connected";
+    if (row.status !== "pending" || row.revision !== selected.revision)
+      refuse("The connection changed; review it again before saving");
+    return "pending";
+  }
+
+  /** Used inside an authorized operation; verification reads stay inside its driver step. */
+  async activate(ref: ConnectionRef, revision: string, actor: Principal): Promise<ConnectionSnapshot> {
+    const setup = await this.setup({ connection: ref }, actor, "activate");
+    const row = await this.row(setup.id);
+    if (
+      !row ||
+      row.revision !== revision ||
+      row.definition !== setup.definition ||
+      !["pending", "uncertain"].includes(row.status)
+    )
+      refuse("The connection changed; review it again before activating");
+    const method = this.catalog.methods.get(row.vendor)![row.method]!;
+    const bundle = row.credential ? await this.secrets?.read(row.credential) : undefined;
+    if (row.credential && !bundle) throw new SecretStoreError("unavailable");
+    const identity = await verifyAuthentication(method, bundle && decodeCredentials(method, bundle.value), {
+      connectionId: row.id,
+      vendor: row.vendor,
+    });
+    if (identity.account !== row.account) throw new AuthenticationError("wrong_account");
+    if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(row.scopes)].toSorted()))
+      throw new AuthenticationError("scope_changed");
+    const next = randomUUID();
+    const result = await (
+      await this.db()
+    ).query(
+      "UPDATE sanoma_connections SET status='connected',revision=$3,updated_by=$4,updated_at=now() WHERE id=$1 AND revision=$2 RETURNING id",
+      [row.id, revision, next, actor.id],
+    );
+    if (!result.rowCount) refuse("The connection changed; review it again before activating");
+    await this.health(row.id, next, "connected", bundle?.version);
+    return snapshot({ ...row, revision: next, status: "connected" });
+  }
+
   private bindingFingerprint(
     declaration: ConnectionDefinition | ConnectionRule,
     method: Authentication,
@@ -286,10 +648,43 @@ export class ConnectionRegistry {
   async assertCurrent(selected: ConnectionSnapshot | undefined, actor: string): Promise<void> {
     if (!selected) return;
     const current = await this.select(selected.vendor, { vendor: selected.vendor, $connection: selected.id }, actor);
-    if (!current || current.revision !== selected.revision || current.definition !== selected.definition)
+    if (
+      !current ||
+      current.revision !== selected.revision ||
+      current.definition !== selected.definition ||
+      current.method !== selected.method ||
+      current.account !== selected.account ||
+      current.credentials?.$secret !== selected.credentials?.$secret ||
+      JSON.stringify(current.scopes.toSorted()) !== JSON.stringify(selected.scopes.toSorted())
+    )
       refuse("The connection changed after authorization; start a new call");
   }
 
+  /** Only called inside an authorized driver boundary. No value escapes into workflow history. */
+  async authenticate(selected: ConnectionSnapshot, actor: string): Promise<CallAuthentication> {
+    await this.assertCurrent(selected, actor);
+    const method = this.catalog.methods.get(selected.vendor)?.[selected.method];
+    if (!method?.verify) throw new AuthenticationError("unsupported");
+    const material: CallAuthentication = { method: selected.method, kind: method.kind };
+    if (method.kind !== "workload-identity") {
+      if (!this.secrets || !selected.credentials) throw new SecretStoreError("unavailable");
+      const bundle = await this.secrets.read(selected.credentials.$secret);
+      if (!bundle) throw new AuthenticationError("missing");
+      material.credentials = decodeCredentials(method, bundle.value);
+      material.credentialVersion = bundle.version;
+    }
+    const identity = await verifyAuthentication(method, material.credentials, {
+      connectionId: selected.id,
+      vendor: selected.vendor,
+    });
+    if (identity.account !== selected.account) throw new AuthenticationError("wrong_account");
+    if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(selected.scopes)].toSorted()))
+      throw new AuthenticationError("scope_changed");
+    // A disconnect or rebind while verification was in flight revokes this invocation too.
+    await this.assertCurrent(selected, actor);
+    return material;
+  }
+
   async bind(
     ref: ConnectionRef,
     account: string,
@@ -395,11 +790,13 @@ export class ConnectionRegistry {
       row.definition,
       row.credential,
       actor,
+      row.status,
+      row.credential && this.secrets ? JSON.stringify(this.secrets.location(row.credential)) : null,
     ];
     const query =
       expected === null
-        ? "INSERT INTO sanoma_connections (id,vendor,method,owner,rule,account,scopes,revision,definition,credential,updated_by) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT(id) DO NOTHING RETURNING id"
-        : "UPDATE sanoma_connections SET vendor=$2,method=$3,owner=$4,rule=$5,account=$6,scopes=$7,revision=$8,definition=$9,credential=$10,updated_by=$11,updated_at=now(),status='connected' WHERE id=$1 AND revision=$12 RETURNING id";
+        ? "INSERT INTO sanoma_connections (id,vendor,method,owner,rule,account,scopes,revision,definition,credential,updated_by,status,location) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13) ON CONFLICT(id) DO NOTHING RETURNING id"
+        : "UPDATE sanoma_connections SET vendor=$2,method=$3,owner=$4,rule=$5,account=$6,scopes=$7,revision=$8,definition=$9,credential=$10,updated_by=$11,updated_at=now(),status=$12,location=$13 WHERE id=$1 AND revision=$14 RETURNING id";
     const result = await (await this.db()).query(query, [...values, ...(expected === null ? [] : [expected])]);
     if (!result.rowCount) refuse("The connection changed; reload before binding it");
   }
@@ -408,6 +805,64 @@ export class ConnectionRegistry {
 /** Metadata mutations are access operations, so they are policy-reviewed and audited like other effects. */
 export const connectionOps = defineConnector("sanoma", {
   connection: {
+    test: {
+      effect: "read",
+      input: z.object({ connection: connectionRefSchema }),
+      output: z.object({
+        state: z.enum([
+          "missing",
+          "expired",
+          "revoked",
+          "rejected",
+          "wrong_account",
+          "scope_changed",
+          "uncertain",
+          "unavailable",
+          "unsupported",
+          "connected",
+          "disconnected",
+          "pending",
+          "configuration_changed",
+          "store_denied",
+          "invalid",
+        ]),
+        checkedAt: z.string(),
+        externallyRenewed: z.boolean(),
+      }),
+      target: (input: { connection: ConnectionRef }) => input.connection.$connection,
+    },
+    prepare: {
+      effect: "access",
+      input: z.object({
+        target: connectionTargetSchema,
+        requestId: z.string().min(1),
+        definition: z.string(),
+        authorization: z.string(),
+      }),
+      output: setupSchema,
+      target: (input: { target: ConnectionTarget }) =>
+        "connection" in input.target ? input.target.connection.$connection : input.target.rule,
+    },
+    configure: {
+      effect: "access",
+      input: z.object({
+        target: connectionTargetSchema,
+        requestId: z.string().min(1),
+        expectedRevision: z.string().nullable(),
+        definition: z.string(),
+        account: z.string().min(1),
+        scopes: z.array(z.string()),
+      }),
+      output: snapshotSchema,
+      target: (input: { target: ConnectionTarget }) =>
+        "connection" in input.target ? input.target.connection.$connection : input.target.rule,
+    },
+    activate: {
+      effect: "access",
+      input: z.object({ connection: connectionRefSchema, expectedRevision: z.string() }),
+      output: snapshotSchema,
+      target: (input: { connection: ConnectionRef }) => input.connection.$connection,
+    },
     disconnect: {
       effect: "access",
       input: z.object({ connection: connectionRefSchema, expectedRevision: z.string() }),
@@ -437,6 +892,23 @@ const actor = (call: CallContext) => call.principal ?? refuse("Connection mutati
 export function connectionDriver(registry: ConnectionRegistry) {
   return defineDriver(connectionOps, {
     connection: {
+      test: (input, call) => registry.test(input.connection, actor(call)),
+      prepare: async (input, call) => {
+        const setup = await registry.setup(input.target, actor(call), input.requestId);
+        if (setup.definition !== input.definition) refuse("The connection changed; review its requirements again");
+        return { ...setup, requiredScopes: [...setup.requiredScopes] };
+      },
+      configure: (input, call) =>
+        registry.configure(
+          input.target,
+          input.requestId,
+          input.expectedRevision,
+          input.definition,
+          input.account,
+          input.scopes,
+          actor(call),
+        ),
+      activate: (input, call) => registry.activate(input.connection, input.expectedRevision, actor(call)),
       disconnect: (input, call) => registry.disconnect(input.connection, input.expectedRevision, actor(call).id),
       bind: (input, call) =>
         registry.bind(input.connection, input.account, input.scopes, input.expectedRevision, actor(call).id),

package/src/db.ts

@@ -31,13 +31,26 @@ export const CHAT_MESSAGES_TABLE = "sanoma_chat_messages";
 
 /** The runtime's tables, each with the word the messages name it by. */
 const TABLES: readonly [what: string, ddl: string][] = [
+  [
+    "connection health",
+    `CREATE TABLE IF NOT EXISTS sanoma_connection_health (
+      connection_id text PRIMARY KEY, revision text NOT NULL, health text NOT NULL,
+      credential_version text, externally_renewed boolean NOT NULL, checked_at timestamptz NOT NULL DEFAULT now())`,
+  ],
+  [
+    "connection setup receipts",
+    `CREATE TABLE IF NOT EXISTS sanoma_connection_setups (
+      connection_id text NOT NULL, revision text NOT NULL, credential_version text NOT NULL,
+      PRIMARY KEY(connection_id, revision))`,
+  ],
   [
     "connections",
     `CREATE TABLE IF NOT EXISTS sanoma_connections (
     id text PRIMARY KEY, vendor text NOT NULL, method text NOT NULL, owner text, rule text,
     account text NOT NULL, scopes jsonb NOT NULL, revision text NOT NULL, definition text NOT NULL,
-    credential text, status text NOT NULL DEFAULT 'connected', updated_by text NOT NULL,
-    updated_at timestamptz NOT NULL DEFAULT now())`,
+    credential text, location jsonb, status text NOT NULL DEFAULT 'connected', updated_by text NOT NULL,
+    updated_at timestamptz NOT NULL DEFAULT now());
+    ALTER TABLE sanoma_connections ADD COLUMN IF NOT EXISTS location jsonb`,
   ],
   [
     "credentials",

package/src/describe.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import type { z } from "zod";
 import { type AppEntry, appsAt } from "./apps.ts";
 import { readSource, type SourceFile } from "./ast.ts";
@@ -17,13 +18,16 @@ import {
 import { isDirect } from "./direct.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
 import { lintWorkflow } from "./lint.ts";
+import { fresh, stampOf, stampsOf } from "./load.ts";
+import { LOCKFILE } from "./lockfile.ts";
 import { VENDOR, type VendorInfo } from "./op.ts";
 import { outlineWithSource } from "./outline.ts";
+import { APPS_DIR, kindDirs } from "./paths.ts";
 import { allowAll, policyOpOf } from "./policy.ts";
 import { type Resource, resourceTypesOf, valueAt } from "./resource.ts";
 import { type DeclaredResource, inAppPeople, loadDataFiles, type ResourceProblem } from "./resources.ts";
 import { apiNameProblem } from "./sdk.ts";
-import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, problemLine } from "./shared.ts";
+import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, errorMessage, problemLine } from "./shared.ts";
 import { readSites, type SiteEntry } from "./sites.ts";
 
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
@@ -79,6 +83,53 @@ export { previewRequests } from "./shared.ts";
 // The apply workflow's plan and report, which the app renders.
 export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 
+/**
+ * `describeConfig(config)`, kept and made again only once the files it loaded have changed: each
+ * company file a load read and its folder (`stampsOf`), the lockfile, and the folders a new data
+ * file, app or site would appear in, one `stat` each per call. What the config imports (its
+ * workflows, connectors and policies) is read once, as the worker reads it. When describing again
+ * throws, the last description stands until the files change again.
+ */
+export function liveDescription(config: SanomaConfig): () => ConfigDescription {
+  const root = rootOf(config);
+  if (root === undefined) {
+    const description = describeConfig(config);
+    return () => description;
+  }
+  /** The description and what it read; `last`, kept (and said) when describing again throws. */
+  const described = (last?: ConfigDescription) => {
+    // The folders and the lockfile as they are before describing, so a change while it reads is seen after.
+    const extra = [
+      resolve(root, LOCKFILE),
+      resolve(root, APPS_DIR),
+      ...kindDirs(root, "sites"),
+      ...kindDirs(root, "resources"),
+    ].map((path) => [path, stampOf(path)] as const);
+    let description: ConfigDescription;
+    try {
+      description = describeConfig(config);
+    } catch (err) {
+      if (last === undefined) throw err;
+      console.warn(
+        `sanoma: the files could not be described again, so the last description stands: ${errorMessage(err)}`,
+      );
+      description = last;
+    }
+    return { description, stamps: new Map([...extra, ...stampsOf(root)]) };
+  };
+  let now = described();
+  // The workflows as the config imported them, which the worker runs: their outlines and sources
+  // from the first description, never a file edited since.
+  const { workflows } = now.description;
+  return () => {
+    if (!fresh(now.stamps)) {
+      now = described(now.description);
+      now.description.workflows = workflows;
+    }
+    return now.description;
+  };
+}
+
 /**
  * Describes a config. Throws what `startWorker` would refuse (see `resolveConfig`), except missing
  * credentials (`SanomaClient.credentials` gives their statuses) and what is wrong in a workflow's

package/src/direct.ts

@@ -19,4 +19,8 @@ export const isDirect = (
   op.id === "sanoma.connection.disconnect" ||
   op.id === "sanoma.connection.bind" ||
   op.id === "sanoma.connection.create" ||
+  op.id === "sanoma.connection.prepare" ||
+  op.id === "sanoma.connection.configure" ||
+  op.id === "sanoma.connection.activate" ||
+  op.id === "sanoma.connection.test" ||
   (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));