@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/db.js

@@ -0,0 +1,179 @@
+import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
+import { Client, Pool } from "pg";
+import { warn } from "./log.js";
+import { errorMessage } from "./shared.js";
+/** Where the credentials set from the app live. */
+export const CREDENTIALS_TABLE = "sanoma_credentials";
+/** Where the Postgres ledger keeps its records. */
+export const LEDGER_TABLE = "sanoma_ledger";
+/** The runtime's tables, each with the word the messages name it by. */
+const TABLES = [
+    [
+        "credentials",
+        `CREATE TABLE IF NOT EXISTS ${CREDENTIALS_TABLE} (name text PRIMARY KEY, value text NOT NULL, ` +
+            "set_by text NOT NULL, set_at timestamptz NOT NULL DEFAULT now())",
+    ],
+    [
+        "ledger",
+        // `n` is the write order, `id` the record's, which the first write of takes, and `seq` the
+        // record's place in its run: a run reads in `seq` order, then write order.
+        `CREATE TABLE IF NOT EXISTS ${LEDGER_TABLE} (n bigserial PRIMARY KEY, id text NOT NULL UNIQUE, ` +
+            `run_id text NOT NULL, seq integer NOT NULL, record jsonb NOT NULL); ` +
+            `CREATE INDEX IF NOT EXISTS ${LEDGER_TABLE}_run_seq ON ${LEDGER_TABLE} (run_id, seq, n)`,
+    ],
+];
+/** The Postgres error code of `err`, or an empty string when it has none. */
+export const pgCode = (err) => err?.code?.toString() ?? "";
+/** Postgres's codes for a row type or a table another process made first. */
+const MADE_ALREADY = new Set(["23505", "42P07"]);
+/** True for the failure of a create that another process won: what was to be made is there. */
+export const madeAlready = (err) => MADE_ALREADY.has(pgCode(err));
+/**
+ * A pool on the config's database for `what` (a word for the messages). An idle connection that
+ * drops (Postgres restarted) is replaced on the next query; unheard, it would end the process.
+ */
+export function openPool(databaseUrl, what) {
+    const pool = new Pool({ connectionString: databaseUrl });
+    pool.on("error", (err) => warn(`a ${what} connection failed: ${errorMessage(err)}`));
+    return pool;
+}
+/**
+ * What every DBOS handle on the config's database is given (`DBOS.setConfig`, `dbosClient`): DBOS
+ * is told not to set Postgres's `idle_in_transaction_session_timeout` on each connection of its
+ * pool. It sends that `SET` from the pool's `connect` event without awaiting it (dbos-sdk 5.2.11,
+ * dist/src/system_database.js:691), so the pool hands the connection out while it runs: two
+ * queries at once on one client, which pg deprecates. `prepareDatabase` sets the same 60 s guard
+ * on the database instead. Remove the switch when DBOS awaits its `SET`.
+ */
+export const DBOS_DATABASE_OPTIONS = { systemDatabaseIdleTransactionTimeoutMs: 0 };
+/**
+ * A DBOS client of the app `applicationName` on the database at `databaseUrl`, as every client of
+ * the runtime, its tests and `@sanoma-ai/testing` make one (`DBOS_DATABASE_OPTIONS`).
+ */
+export const dbosClient = (databaseUrl, applicationName) => DBOSClient.create({
+    systemDatabaseUrl: databaseUrl,
+    ...(applicationName !== undefined && { applicationName }),
+    ...DBOS_DATABASE_OPTIONS,
+});
+/**
+ * The `idle_in_transaction_session_timeout` `prepareDatabase` sets: DBOS's own default
+ * (`DEFAULT_IDLE_TRANSACTION_TIMEOUT_MS`, 60_000, in dbos-sdk 5.2.11 dist/src/system_database.js),
+ * how long a frozen or unreachable client may hold the system database's locks.
+ */
+const IDLE_IN_TRANSACTION_TIMEOUT = "60s";
+/** Postgres's code for a statement the role lacks the privilege for. */
+const INSUFFICIENT_PRIVILEGE = "42501";
+/**
+ * A pool for `what` on the database at `databaseUrl`, opened on the first `db()` once the
+ * database is prepared (`prepareDatabase`). A preparation that fails lets the pool go, so the
+ * next `db()` tries again. `close` ends the pool, for good: a `db()` after it is refused.
+ */
+export function lazyPool(databaseUrl, what) {
+    let pool;
+    let closed = false;
+    return {
+        async db() {
+            if (closed)
+                throw new Error(`the ${what} store is closed`);
+            const current = (pool ??= openPool(databaseUrl, what));
+            try {
+                await prepareDatabase(databaseUrl);
+            }
+            catch (err) {
+                if (pool === current)
+                    pool = undefined;
+                await current.end().catch(() => undefined);
+                throw err;
+            }
+            return current;
+        },
+        async close() {
+            closed = true;
+            const current = pool;
+            pool = undefined;
+            await current?.end();
+        },
+    };
+}
+/** Each database prepared, or being prepared, by its URL. A failed preparation is forgotten. */
+const prepared = new Map();
+/**
+ * Makes the database at `databaseUrl` ready for the runtime, once per process and URL: the
+ * database itself and DBOS's tables when they are not there yet (as a worker's launch makes
+ * them; credentials may be set, and a ledger read, before any worker has run), then the
+ * credentials and ledger tables, and its idle-transaction timeout (`guardIdleTransactions`).
+ * Two processes preparing one database both succeed. A
+ * preparation that fails is forgotten, so the next call tries again.
+ */
+export function prepareDatabase(databaseUrl) {
+    let preparing = prepared.get(databaseUrl);
+    if (!preparing) {
+        preparing = prepare(databaseUrl).catch((err) => {
+            if (prepared.get(databaseUrl) === preparing)
+                prepared.delete(databaseUrl);
+            throw err;
+        });
+        prepared.set(databaseUrl, preparing);
+    }
+    return preparing;
+}
+async function prepare(databaseUrl) {
+    try {
+        await DBOS.migrate(databaseUrl);
+    }
+    catch (err) {
+        // The database, or a DBOS table, made by another process meanwhile: it is there.
+        if (!madeAlready(err))
+            throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+    }
+    const conn = new Client({ connectionString: databaseUrl });
+    await conn.connect();
+    try {
+        for (const [what, ddl] of TABLES)
+            await createTable(conn, ddl, what);
+        await guardIdleTransactions(conn);
+    }
+    finally {
+        await conn.end();
+    }
+}
+/**
+ * Sets `idle_in_transaction_session_timeout` on the database, for each session that starts after,
+ * as DBOS would per connection (`DBOS_DATABASE_OPTIONS`), unless the server, the role or the
+ * database sets it already. One process at a time (an advisory lock), so two preparing at once
+ * both succeed. A role that may not alter the database leaves it, quietly: its administrator decides.
+ */
+async function guardIdleTransactions(db) {
+    try {
+        await db.query(`DO $$ BEGIN
+      PERFORM pg_advisory_xact_lock(hashtext('sanoma.idle_in_transaction_session_timeout'));
+      IF current_setting('idle_in_transaction_session_timeout') = '0' AND NOT EXISTS (
+        SELECT FROM pg_db_role_setting s JOIN pg_database d ON d.oid = s.setdatabase, unnest(s.setconfig) c
+        WHERE d.datname = current_database() AND s.setrole = 0 AND c LIKE 'idle_in_transaction_session_timeout=%'
+      ) THEN
+        EXECUTE format('ALTER DATABASE %I SET idle_in_transaction_session_timeout = %L', current_database(),
+          '${IDLE_IN_TRANSACTION_TIMEOUT}');
+      END IF;
+    END $$`);
+    }
+    catch (err) {
+        if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) {
+            throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+        }
+    }
+}
+/**
+ * Runs `ddl` (`CREATE TABLE IF NOT EXISTS`, and the like) on `db`. Two processes racing to create
+ * the same table both succeed; any other failure names the `what` table, with its cause.
+ */
+export async function createTable(db, ddl, what) {
+    try {
+        await db.query(ddl);
+    }
+    catch (err) {
+        if (madeAlready(err))
+            return;
+        throw new Error(`could not prepare the ${what} table: ${errorMessage(err)}`, { cause: err });
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

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

package/dist/define.d.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { type Op } from "./op.ts";
+/**
+ * Who is acting: the person or service that starts a run or decides an approval. `id` is
+ * whatever the deployment identifies people by; `groups` are the roles it vouches for.
+ */
+export interface Principal {
+    id: string;
+    groups?: string[];
+}
+export declare const Principal: z.ZodType<Principal>;
+export type Builtin = "approval" | "sleep" | "all";
+export type Use = Op | Builtin;
+/** Who may decide an approval: one person, by `Principal.id`, or anyone in a group, by `Principal.groups`. */
+export type Approver = string | {
+    group: string;
+};
+export declare const Approver: z.ZodType<Approver>;
+/** Why `by` may not decide the approval, naming who may. */
+export declare const notApprover: ({ approver }: Pick<ApprovalState, "approver">, by: Principal) => string;
+/** True when the two name the same approver: the same id, or the same group. */
+export declare const sameApprover: (a: Approver, b: Approver) => boolean;
+/** `covers` as given (operations), parsed to their ids. */
+export declare const Covers: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<string, {
+    id: string;
+}>>>>;
+export interface ApprovalRequest {
+    /** Who must approve: a person's id, or `{ group }` for anyone in it. Phase 4 replaces this with a Cedar decision. */
+    approver: Approver;
+    /**
+     * The operations the approval stands for, so a policy can let their calls through once it
+     * is approved (`a.covers.includes(op.id)`). None unless given.
+     */
+    covers?: Op[];
+    links?: string[];
+    details?: string;
+}
+/**
+ * Checks a `ctx.approval` request as a workflow may give it, so the UI and the ledger get what
+ * the types say, and turns `covers` into op ids.
+ */
+export declare const ApprovalRequestSchema: z.ZodObject<{
+    approver: z.ZodType<Approver, unknown, z.core.$ZodTypeInternals<Approver, unknown>>;
+    covers: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodTransform<string, {
+        id: string;
+    }>>>>;
+    links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One approval in a run, as the run sees it. Published as the run's "approvals" event. */
+export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
+    id: string;
+    title: string;
+    /** Who asked: the workflow (`ctx.approval`), or the policy holding an operation call. */
+    requestedBy: "workflow" | "policy";
+    /**
+     * The operations the approval stands for, by id. A policy hold covers the call it held and
+     * any `covers` the policy added; a workflow's approval covers the `covers` it named, or none.
+     */
+    covers: string[];
+    /** For a policy request: the operation call held, by op id. */
+    op?: string;
+    /** For a policy request: the ledger `seq` of the call held, which its `op.called` record has. */
+    opSeq?: number;
+    /** For a policy request: the held call's input. */
+    input?: unknown;
+    status: "pending" | "approved" | "rejected";
+    requestedAt: number;
+    decidedBy?: string;
+    decidedAt?: number;
+    note?: string;
+    /** The `id` of the decision message the run decided with, when it had one. */
+    decidedWith?: string;
+    /**
+     * Messages that were ignored: decisions sent by someone who may not decide the approval,
+     * and messages that were not a decision. `by` is the sender, when the message named one, and
+     * `id` the decision message's own, when it had one.
+     */
+    refused: {
+        by?: string;
+        id?: string;
+        at: number;
+        reason: string;
+    }[];
+}
+export interface ApprovalResult {
+    approvedBy: string;
+    at: number;
+    note?: string;
+}
+/**
+ * How long `ctx.sleep` waits: until a time (an ISO 8601 date-time with an offset, such as
+ * `2026-10-07T09:00:00Z`, or epoch milliseconds), or for a duration whose parts add up. A time
+ * already past waits not at all.
+ */
+export type SleepRequest = {
+    until: string | number;
+} | {
+    ms?: number;
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+    days?: number;
+};
+/** Checks a `ctx.sleep` request that names a time. */
+export declare const SleepUntil: z.ZodObject<{
+    until: z.ZodUnion<readonly [z.ZodISODateTime, z.ZodNumber]>;
+}, z.core.$strict>;
+/** Checks a `ctx.sleep` request that names a duration. */
+export declare const SleepFor: z.ZodObject<{
+    ms: z.ZodOptional<z.ZodNumber>;
+    seconds: z.ZodOptional<z.ZodNumber>;
+    minutes: z.ZodOptional<z.ZodNumber>;
+    hours: z.ZodOptional<z.ZodNumber>;
+    days: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Checks a `ctx.all` argument: a list of functions, each one member. */
+export declare const AllMembers: z.ZodArray<z.ZodCustom<() => unknown, () => unknown>>;
+/**
+ * What a step is called, beside its operation: `ctx.ghost.post.create(input, { name: "Draft" })`,
+ * `ctx.sleep({ days: 1 }, { name: "Wait a day" })`. A string literal, or a top-level `const` of
+ * the workflow's file holding one, so the outline reads it. Without one, a call is named by its
+ * operation's id, a sleep `Sleep`; an approval by its title. Names are unique in a workflow, so a
+ * workflow that calls one operation twice names the calls.
+ */
+export interface StepOptions {
+    name?: string;
+}
+type OpsOf<U extends readonly Use[]> = Extract<U[number], Op>;
+type CtxOps<O extends Op> = {
+    readonly [V in O["vendor"]]: {
+        readonly [R in Extract<O, {
+            vendor: V;
+        }>["resource"]]: {
+            readonly [N in Extract<O, {
+                vendor: V;
+                resource: R;
+            }>["name"]]: Extract<O, {
+                vendor: V;
+                resource: R;
+                name: N;
+            }> extends Op<any, any, any, infer I, infer Out> ? (input: I, options?: StepOptions) => Promise<Out> : never;
+        };
+    };
+};
+interface ApprovalCtx {
+    /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection. */
+    approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
+}
+interface SleepCtx {
+    /** Waits, durably, until a time or for a duration. Survives worker restarts. */
+    sleep(request: SleepRequest, options?: StepOptions): Promise<void>;
+}
+interface AllCtx {
+    /**
+     * Runs the members one after another, in order, and returns their outputs in that order. It
+     * declares a fan-out for the ledger and the graph; it adds no concurrency. The first member
+     * that throws stops the group with its error, and later members never run. Not nestable.
+     */
+    all<const T extends readonly (() => Promise<unknown>)[]>(members: T): Promise<{
+        -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>;
+    }>;
+}
+interface BaseCtx {
+    /** The current time, recorded so replays see the same value. Use instead of `Date.now()`. */
+    now(): Promise<number>;
+    readonly runId: string;
+}
+export type Ctx<U extends readonly Use[]> = BaseCtx & CtxOps<OpsOf<U>> & ("approval" extends U[number] ? ApprovalCtx : unknown) & ("sleep" extends U[number] ? SleepCtx : unknown) & ("all" extends U[number] ? AllCtx : unknown);
+/**
+ * A schema as JSON Schema (draft 2020-12). By default it describes what a caller sends
+ * (`io: "input"`: defaults stay optional); `io: "output"` describes what parsing returns.
+ * What JSON Schema can't express is left open. Throws when zod can't convert the schema at all.
+ */
+export declare function jsonSchemaOf(schema: z.ZodType, io?: "input" | "output", refs?: ReadonlyMap<unknown, string>): Record<string, unknown>;
+export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
+    readonly kind: "workflow";
+    readonly name: string;
+    readonly title?: string;
+    readonly trigger: "manual";
+    readonly input: S;
+    /** Every operation and built-in the workflow may call. `ctx` is built from this list and nothing else. */
+    readonly uses: U;
+    readonly run: (ctx: Ctx<U>, input: z.output<S>) => Promise<unknown>;
+    /**
+     * The file that defined it, absolute. Set by defineWorkflow from its call site: the outline is
+     * read from it, the worker holds each run to that outline, and the app shows it as the code view.
+     */
+    readonly file: string;
+}
+/** The ids of the operations a workflow `uses`, in the order declared. */
+export declare const opIdsOf: (wf: Pick<WorkflowDefinition, "uses">) => string[];
+export declare function defineWorkflow<const U extends readonly Use[], S extends z.ZodType>(def: Omit<WorkflowDefinition<U, S>, "kind" | "file">): WorkflowDefinition<U, S>;
+/**
+ * The file of the code that called the function calling this one (`defineWorkflow`'s caller),
+ * from V8's call sites, as a path; undefined where there is none.
+ */
+export declare function callerFile(): string | undefined;
+/** A V8 script name (a `file:` URL for a module, a path for a script) as a path; undefined for none. */
+export declare function scriptPath(script: string | undefined): string | undefined;
+export {};

package/dist/define.js

@@ -0,0 +1,103 @@
+import { fileURLToPath } from "node:url";
+import { getCallSites } from "node:util";
+import { z } from "zod";
+import { isOp } from "./op.js";
+import { approverLabel } from "./shared.js";
+export const Principal = z.object({
+    id: z.string().regex(/\S/, "id must not be blank"),
+    groups: z.array(z.string()).optional(),
+});
+export const Approver = z.union([z.string().regex(/\S/), z.object({ group: z.string().regex(/\S/) })], { error: 'needs an approver: a name, or { group: "name" }' });
+/** Why `by` may not decide the approval, naming who may. */
+export const notApprover = ({ approver }, by) => typeof approver === "string"
+    ? `${by.id} is not the approver; ${approverLabel(approver)} is`
+    : `${by.id} is not in ${approverLabel(approver)}`;
+/** True when the two name the same approver: the same id, or the same group. */
+export const sameApprover = (a, b) => typeof a === "string" || typeof b === "string" ? a === b : a.group === b.group;
+const notOps = "covers must be a list of operations";
+/** `covers` as given (operations), parsed to their ids. */
+export const Covers = z
+    .array(z.object({ id: z.string() }, { error: notOps }).transform((op) => op.id), { error: notOps })
+    .optional();
+/**
+ * Checks a `ctx.approval` request as a workflow may give it, so the UI and the ledger get what
+ * the types say, and turns `covers` into op ids.
+ */
+export const ApprovalRequestSchema = z.object({
+    approver: Approver,
+    covers: Covers,
+    links: z.array(z.string(), { error: "links must be a list of strings" }).optional(),
+    details: z.string({ error: "details must be a string" }).optional(),
+}, { error: "needs a request: { approver, covers?, links?, details? }" });
+const time = "must be an ISO 8601 date-time with an offset, such as 2026-10-07T09:00:00Z, or epoch milliseconds";
+const duration = z.number({ error: "must be a number" }).nonnegative("must not be negative").optional();
+/** Checks a `ctx.sleep` request that names a time. */
+export const SleepUntil = z.strictObject({
+    until: z.union([z.iso.datetime({ offset: true, error: time }), z.number({ error: time })], { error: time }),
+});
+/** Checks a `ctx.sleep` request that names a duration. */
+export const SleepFor = z.strictObject({
+    ms: duration,
+    seconds: duration,
+    minutes: duration,
+    hours: duration,
+    days: duration,
+});
+/** Checks a `ctx.all` argument: a list of functions, each one member. */
+export const AllMembers = z.array(z.custom((m) => typeof m === "function", "each member must be a function, such as () => ctx.…"), { error: "needs a list of functions: ctx.all([() => …, () => …])" });
+/**
+ * A schema as JSON Schema (draft 2020-12). By default it describes what a caller sends
+ * (`io: "input"`: defaults stay optional); `io: "output"` describes what parsing returns.
+ * What JSON Schema can't express is left open. Throws when zod can't convert the schema at all.
+ */
+export function jsonSchemaOf(schema, io = "input", refs) {
+    return z.toJSONSchema(schema, {
+        io,
+        target: "draft-2020-12",
+        unrepresentable: "any",
+        // A schema `refs` names, inside another, becomes a `$ref` to it (a resource type's state).
+        ...(refs?.size && {
+            override: ({ zodSchema, jsonSchema, path }) => {
+                const ref = path.length > 0 ? refs.get(zodSchema) : undefined;
+                if (ref === undefined)
+                    return;
+                for (const key of Object.keys(jsonSchema))
+                    delete jsonSchema[key];
+                Object.assign(jsonSchema, { $ref: ref });
+            },
+        }),
+    });
+}
+/** The ids of the operations a workflow `uses`, in the order declared. */
+export const opIdsOf = (wf) => wf.uses.filter(isOp).map((op) => op.id);
+export function defineWorkflow(def) {
+    if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
+        throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
+    }
+    const file = callerFile();
+    if (file === undefined) {
+        throw new Error(`Workflow "${def.name}" was defined from code with no file (an eval, or a bundle without one): ` +
+            "its outline is read from the file, and a run is held to the outline");
+    }
+    return Object.freeze({ kind: "workflow", ...def, file });
+}
+/**
+ * The file of the code that called the function calling this one (`defineWorkflow`'s caller),
+ * from V8's call sites, as a path; undefined where there is none.
+ */
+export function callerFile() {
+    // Frame 0 is this function, frame 1 its caller, frame 2 theirs: by index, since a bundle may hold all three.
+    return scriptPath(getCallSites(3)[2]?.scriptName);
+}
+/** A V8 script name (a `file:` URL for a module, a path for a script) as a path; undefined for none. */
+export function scriptPath(script) {
+    if (!script?.startsWith("file:"))
+        return script || undefined;
+    try {
+        return fileURLToPath(script);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

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

package/dist/describe.d.ts

@@ -0,0 +1,135 @@
+import { type LintProblem } from "./ast.ts";
+import { type SanomaConfig } from "./config.ts";
+import { type Builtin } from "./define.ts";
+import { type Effect } from "./op.ts";
+import { type Outline } from "./outline.ts";
+import { type ResourceFields } from "./resource.ts";
+import { type DeclaredResource, type ResourceProblem } from "./resources.ts";
+export { outlineWorkflow, type Outline, type OutlineNode, type Span } from "./outline.ts";
+export type { LintProblem } from "./ast.ts";
+export { readDataFiles, readResources, type DataFiles, type DeclaredResource, type ResourceProblem, } from "./resources.ts";
+/** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
+export interface WorkflowEntry {
+    name: string;
+    title?: string;
+    trigger: "manual";
+    /**
+     * Set for a workflow the runtime adds itself, `drift`, rather than the config: a label. It
+     * starts like any other.
+     */
+    builtin?: true;
+    /** The input, as JSON Schema (draft 2020-12), from the zod schema. */
+    input: Record<string, unknown>;
+    /** Operation ids the workflow may call, in the order declared. */
+    ops: string[];
+    /** Built-ins the workflow may call. */
+    builtins: Builtin[];
+    /** The file that defined it, absolute. */
+    file: string;
+    /** What its `run` calls, in order, read from its file (`outlineWorkflow`), which the worker holds its runs to. */
+    outline: Outline;
+    /**
+     * What is wrong in its file, by position: what `lintWorkflow` finds (syntax, an import a
+     * workflow may not make, `instanceof` against the runtime's error classes, what the outline
+     * cannot draw in each `run`), read the one way the outline is, so a check sees what the
+     * worker refuses; and, at 1:1, an outline error that is the file's (it cannot be read, or holds
+     * no workflow of this name). A file defining several workflows gives each its problems. Empty
+     * for the built-in `drift`, which the package's tests hold to the lint.
+     */
+    problems: LintProblem[];
+    /**
+     * The text the outline's spans index into: the workflow's file, with `\n` line endings.
+     * Absent only when the outline is `{ error }`. Whole files: a server may keep it from clients.
+     */
+    source?: string;
+}
+/** What an operation is, read from its connector: enough to badge it and show its contract. */
+export interface OpEntry {
+    id: string;
+    vendor: string;
+    resource: string;
+    name: string;
+    effect: Effect;
+    idempotent: boolean;
+    description?: string;
+    /** How a scenario's steps name it: Cucumber expressions over its input's fields. */
+    phrases?: {
+        given?: string;
+        expect?: string;
+    };
+    /** What a call sends, as JSON Schema (`io: "input"`: fields with defaults are optional). */
+    input: Record<string, unknown>;
+    /** What a call returns once its schema has parsed the vendor's reply (`io: "output"`). */
+    output: Record<string, unknown>;
+}
+/** Who a vendor is, from its connector's `VendorInfo`: enough to name it, show its logo and link to its connector. */
+export interface VendorEntry {
+    /** The connector's `title`, else the vendor's id. */
+    title: string;
+    /** The logo as `data:image/svg+xml` URLs, for an `<img>`: `dark` is for dark backgrounds. */
+    logo?: {
+        src: string;
+        dark?: string;
+    };
+    /** The connector's npm package name. */
+    package?: string;
+    /** The connector package's `homepage` from its package.json: where its code and README are, as an https URL. */
+    homepage?: string;
+    /** Whether the vendor's connector attaches a fake (`withSetup`), for sandbox runs. */
+    fake: boolean;
+}
+/** A resource type a connector declares with `defineResource`. */
+export interface ResourceTypeEntry {
+    /** `<vendor>.<type>`, such as `github.repository`. */
+    id: string;
+    vendor: string;
+    type: string;
+    title: string;
+    /** How a declared resource's import id is made, such as `name` or `repository_id:pattern`. */
+    identity: string;
+    /** Its flagged fields, by dotted path. */
+    fields: ResourceFields;
+    /**
+     * Its state, as a read returns it, as JSON Schema (`io: "output"`), with `$id`
+     * `sanoma:resource-type/<id>`: the operations' contracts `$ref` it instead of repeating it.
+     */
+    schema: Record<string, unknown>;
+    /** Its operations' ids: `<id>.import` and `<id>.read`. */
+    ops: string[];
+}
+/**
+ * A plain-JSON description of what a config can do: its workflows, the operations they call,
+ * and whether a policy gates them. The app server builds it from the config and sends it to the
+ * browser, so the UI shows exactly what the worker enforces. Never written by hand.
+ */
+export interface ConfigDescription {
+    appName: string;
+    /** The application version runs started now are stamped with. */
+    version: string;
+    workflows: WorkflowEntry[];
+    ops: OpEntry[];
+    /** Every vendor the operations are from, by its id (an `OpEntry`'s `vendor`). */
+    vendors: Record<string, VendorEntry>;
+    /** The resource types the connectors declare, by `id`. */
+    resourceTypes: ResourceTypeEntry[];
+    /**
+     * The resources the data files under `resources/` declare, by file and then in file order,
+     * less any with a problem and any that names one.
+     */
+    resources: DeclaredResource[];
+    /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
+    problems: ResourceProblem[];
+    /** `defined` is false for `allowAll`. */
+    policy: {
+        defined: boolean;
+        version?: string;
+    };
+}
+/**
+ * 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
+ * file, which the worker refuses when it reads the outline: that is data, on each workflow's
+ * entry, as the data files' problems are, `problems`, beside the resources read without any.
+ * Each workflow's file is read and parsed once, however many workflows it defines.
+ */
+export declare function describeConfig(config: SanomaConfig): ConfigDescription;