@sanoma-ai/workflows 0.5.0 → 0.7.0

package/dist/deadlines.d.ts

@@ -0,0 +1,88 @@
+import type { Db } from "./db.ts";
+import type { ResolvedConfig } from "./config.ts";
+import type { DriverFn, Op } from "./op.ts";
+import type { Secrets } from "./secret.ts";
+/** What a run blocked in a `ctx` wait waits for: a sleep, until its deadline, or an approval's decision, which has none. */
+export type Wait = {
+    kind: "sleep";
+    until: number;
+} | {
+    kind: "approval";
+};
+/** A deadline besides the sleeping runs', such as a schedule's next fire; undefined for none. */
+export type DeadlineSource = () => Date | undefined;
+/** What a worker shows of its runs' deadlines (`Worker.deadlines`). */
+export interface Deadlines {
+    /**
+     * Adds a deadline besides the sleeping runs', read each time `nextDeadline` is: a fixed time
+     * (a schedule's next fire), never one counted from now, which would never let the worker stop.
+     */
+    addSource(source: DeadlineSource): void;
+    /** The earliest deadline: a sleeping run's `until`, or a source's. Undefined when there is none. */
+    nextDeadline(): Date | undefined;
+    /** How many runs are inside their body and in no wrapped wait: executing, or replaying. */
+    readonly busy: number;
+    /** What the run waits for while it is blocked in a wrapped wait; undefined otherwise. */
+    waitOf(runId: string): Wait | undefined;
+}
+/** The registry a worker's runs report to, through `running` and `waiting`. */
+export interface DeadlineRegistry extends Deadlines {
+    /** Runs a run's body, counted busy but while it is in `waiting`. */
+    running<T>(runId: string, body: () => Promise<T>): Promise<T>;
+    /** Runs `fn`, the live wait itself (`DBOS.sleep`, `DBOS.recv`), with the run counted as waiting for `wait`. */
+    waiting<T>(runId: string, wait: Wait, fn: () => Promise<T>): Promise<T>;
+}
+/** A registry of its own for each worker: two copies of the package in one process never share one. */
+export declare function deadlineRegistry(): DeadlineRegistry;
+/** The worker `idle` asks about: the app, the version it runs, and its queue. */
+export type IdleScope = Pick<ResolvedConfig, "appName" | "version" | "queueName">;
+/**
+ * True when a run on `queue` (none for a run started outside a queue) is this worker's to run: on
+ * its own queue, or on one of DBOS's, where recovery puts runs.
+ */
+export declare const onOwnQueue: (queue: string | undefined, queueName: string) => boolean;
+/**
+ * True when nothing this worker would run can run within `horizonMs`: no run of its is executing
+ * or replaying; none of its version is queued (or queued without one, while it is the latest) on
+ * its queue or DBOS's own (recovery queues there); each PENDING run of its version is blocked in
+ * a wrapped wait; and the next deadline is past the horizon. A run of another version or queue
+ * is not this worker's to run, so it never holds the worker up.
+ */
+export declare function idle(deadlines: Deadlines, scope: IdleScope, horizonMs: number): Promise<boolean>;
+/** What `onStopped` hears when the worker stopped itself: the deadline it registered (null for none) and its generation. */
+export interface SelfStop {
+    at: string | null;
+    generation: number;
+}
+/** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
+export interface StopRule {
+    /** The wakeup row's database. */
+    db: () => Promise<Db>;
+    /** This worker's id on the row (`owner`), fresh for each worker. */
+    owner: string;
+    /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
+    wakeup: string;
+    /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
+    register: {
+        op: Op;
+        fn: DriverFn | undefined;
+    };
+    secrets: Secrets;
+    deadlines: Deadlines;
+    idle: () => Promise<boolean>;
+    everyMs: number;
+    /** Stops the worker (`Worker.stop`). */
+    stop: () => Promise<void>;
+    onStopped?: ((stopped: SelfStop) => void) | undefined;
+}
+/**
+ * Checks every `everyMs` whether the worker is `idle`; when it is, counts the wakeup row's
+ * generation up, registers the next deadline with the wakeup (none when there is no deadline at
+ * all), and stops the worker, then tells `onStopped`. A failed registration is recorded on the
+ * row and logged once for each new message, and the worker keeps running: the next check tries
+ * again with a new generation. A run that arrives while it registers keeps the worker up, since
+ * the worker must be idle twice, with the same deadline, before it stops. `close` ends the checks.
+ */
+export declare function stopWhenIdle(rule: StopRule): {
+    close(): void;
+};

package/dist/deadlines.js

@@ -0,0 +1,171 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { dbosStatusesOf } from "./client.js";
+import { nextWakeupGeneration, recordWakeupError, recordWakeupRegistration, recordWakeupStop } from "./db.js";
+import { warn } from "./log.js";
+import { errorMessage, WAKEUP_AGENT } from "./shared.js";
+/** A registry of its own for each worker: two copies of the package in one process never share one. */
+export function deadlineRegistry() {
+    // Each run inside its body, with what it waits for while it is blocked.
+    const runs = new Map();
+    const sources = [];
+    return {
+        addSource(source) {
+            sources.push(source);
+        },
+        nextDeadline() {
+            const times = [
+                ...[...runs.values()].flatMap((wait) => (wait?.kind === "sleep" ? [wait.until] : [])),
+                ...sources.flatMap((source) => source()?.getTime() ?? []),
+            ];
+            return times.length ? new Date(Math.min(...times)) : undefined;
+        },
+        get busy() {
+            return [...runs.values()].filter((wait) => wait === undefined).length;
+        },
+        waitOf: (runId) => runs.get(runId),
+        async running(runId, body) {
+            runs.set(runId, undefined);
+            try {
+                return await body();
+            }
+            finally {
+                runs.delete(runId);
+            }
+        },
+        async waiting(runId, wait, fn) {
+            // Every wait is inside a run's body; one outside is left uncounted rather than counted busy for good.
+            if (!runs.has(runId))
+                return fn();
+            runs.set(runId, wait);
+            try {
+                return await fn();
+            }
+            finally {
+                if (runs.has(runId))
+                    runs.set(runId, undefined);
+            }
+        },
+    };
+}
+/**
+ * True when a run on `queue` (none for a run started outside a queue) is this worker's to run: on
+ * its own queue, or on one of DBOS's, where recovery puts runs.
+ */
+export const onOwnQueue = (queue, queueName) => !queue || queue === queueName || queue.startsWith("_dbos_");
+/**
+ * True when nothing this worker would run can run within `horizonMs`: no run of its is executing
+ * or replaying; none of its version is queued (or queued without one, while it is the latest) on
+ * its queue or DBOS's own (recovery queues there); each PENDING run of its version is blocked in
+ * a wrapped wait; and the next deadline is past the horizon. A run of another version or queue
+ * is not this worker's to run, so it never holds the worker up.
+ */
+export async function idle(deadlines, scope, horizonMs) {
+    if (deadlines.busy > 0)
+        return false;
+    const next = deadlines.nextDeadline();
+    if (next && next.getTime() <= Date.now() + horizonMs)
+        return false;
+    const runs = await DBOS.listWorkflows({
+        applicationName: scope.appName,
+        status: dbosStatusesOf("queued", "running"),
+        loadInput: false,
+        loadOutput: false,
+    });
+    const ours = runs.filter((r) => onOwnQueue(r.queueName, scope.queueName));
+    if (ours.some((r) => r.status === "PENDING" && r.applicationVersion === scope.version && !deadlines.waitOf(r.workflowID)))
+        return false;
+    const queued = ours.filter((r) => r.status !== "PENDING");
+    if (queued.some((r) => r.applicationVersion === scope.version))
+        return false;
+    // DBOS gives a run queued without a version to the app's latest version.
+    if (!queued.some((r) => !r.applicationVersion))
+        return true;
+    return (await DBOS.getLatestApplicationVersion()).versionName !== scope.version;
+}
+/**
+ * Checks every `everyMs` whether the worker is `idle`; when it is, counts the wakeup row's
+ * generation up, registers the next deadline with the wakeup (none when there is no deadline at
+ * all), and stops the worker, then tells `onStopped`. A failed registration is recorded on the
+ * row and logged once for each new message, and the worker keeps running: the next check tries
+ * again with a new generation. A run that arrives while it registers keeps the worker up, since
+ * the worker must be idle twice, with the same deadline, before it stops. `close` ends the checks.
+ */
+export function stopWhenIdle(rule) {
+    let closed = false;
+    let timer;
+    let lastProblem;
+    const problem = (message) => {
+        if (message !== lastProblem)
+            warn(message);
+        lastProblem = message;
+    };
+    const tryStop = async () => {
+        if (!(await rule.idle()))
+            return false;
+        const next = rule.deadlines.nextDeadline();
+        const at = next?.toISOString() ?? null;
+        const db = await rule.db();
+        const generation = await nextWakeupGeneration(db, rule.owner);
+        if (generation === undefined) {
+            // A worker claims the row only when it starts, so this one never gets it back.
+            warn("another worker registers this instance's wakeups now, so this one keeps running and stops checking");
+            closed = true;
+            return false;
+        }
+        if (at !== null) {
+            try {
+                await registerWakeup(rule, { at, generation });
+            }
+            catch (err) {
+                const message = errorMessage(err);
+                await recordWakeupError(db, rule.owner, generation, message);
+                problem(`could not register the wakeup at ${at}, so the worker keeps running: ${message}`);
+                return false;
+            }
+            await recordWakeupRegistration(db, rule.owner, generation, at);
+        }
+        lastProblem = undefined;
+        if (closed || !(await rule.idle()) || rule.deadlines.nextDeadline()?.toISOString() !== next?.toISOString())
+            return false;
+        await recordWakeupStop(db, rule.owner, generation);
+        await rule.stop().catch((err) => warn(`the worker could not stop cleanly: ${errorMessage(err)}`));
+        rule.onStopped?.({ at, generation });
+        return true;
+    };
+    const check = async () => {
+        timer = undefined;
+        if (closed)
+            return;
+        const stopped = await tryStop().catch((err) => {
+            problem(`could not check whether the worker may stop: ${errorMessage(err)}`);
+            return false;
+        });
+        if (!stopped && !closed)
+            schedule();
+    };
+    const schedule = () => {
+        timer = setTimeout(() => void check(), rule.everyMs);
+        timer.unref();
+    };
+    schedule();
+    return {
+        close() {
+            closed = true;
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
+ * a `CallContext` of the runtime's, and no ledger record, which is a run's. The idempotency key
+ * is the generation's, so a retried registration is one registration.
+ */
+async function registerWakeup({ register: { op, fn }, secrets, wakeup }, registration) {
+    if (!fn)
+        throw new Error(`${op.id} has no driver: the connector package must attach one`);
+    // Every database counts generations from 0, so the key names the wakeup too.
+    const key = `wakeup:${wakeup}:${registration.generation}`;
+    const context = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
+    await fn(op.input.parse(registration), context);
+}
+//# sourceMappingURL=deadlines.js.map

package/dist/deadlines.js.map

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

package/dist/define.d.ts

@@ -72,12 +72,23 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
     input?: unknown;
     /** For a policy request: the policies that held the call, by id, when the policy names them. */
     reasons?: string[];
-    status: "pending" | "approved" | "rejected";
+    /**
+     * `withdrawn`: it no longer stands, as when its change got a new commit. A pending approval is
+     * withdrawn by a message (`SanomaClient.withdraw`), an approved one by its run
+     * (`withdrawApprovals`); either way it lets nothing through and takes no decision.
+     */
+    status: "pending" | "approved" | "rejected" | "withdrawn";
+    /** Why it was withdrawn, once it is. */
+    withdrawnReason?: string;
+    /** When it was withdrawn, once it is. */
+    withdrawnAt?: number;
+    /** Who withdrew it, when someone did rather than its run (`withdrawApprovals`). */
+    withdrawnBy?: string;
     requestedAt: number;
     decidedBy?: string;
     decidedAt?: number;
     note?: string;
-    /** The `id` of the decision message the run decided with, when it had one. */
+    /** The `id` of the decision or withdrawal message the run decided with, when it had one. */
     decidedWith?: string;
     /** Set when the run's own actor decided it: nobody else could (`mayDecide`). */
     alone?: true;
@@ -154,7 +165,7 @@ type CtxOps<O extends Op> = {
     };
 };
 interface ApprovalCtx {
-    /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection. */
+    /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection, `WithdrawnError` on a withdrawal. */
     approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
 }
 interface SleepCtx {
@@ -186,11 +197,21 @@ export type Ctx<U extends readonly Use[]> = BaseCtx & CtxOps<OpsOf<U>> & ("appro
  * 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>;
+/**
+ * How a workflow starts: `manual` (by hand, or from code), or on a schedule, `schedule` a cron
+ * expression of five fields (minute, hour, day of month, month, day of week) read in `timezone`,
+ * an IANA time zone (`Europe/Amsterdam`), UTC without one. A scheduled run is started by the
+ * runtime's `schedule` agent with the input `{}`, as the policy allows; it can still be started by hand.
+ */
+export type Trigger = "manual" | {
+    readonly schedule: string;
+    readonly timezone?: string;
+};
 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 trigger: Trigger;
     readonly input: S;
     /** Every operation and built-in the workflow may call. `ctx` is built from this list and nothing else. */
     readonly uses: U;

package/dist/define.js

@@ -70,6 +70,11 @@ 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`);
     }
+    checkTrigger(def.name, def.trigger);
+    // A scheduled run starts with no input of its own.
+    if (def.trigger !== "manual" && !acceptsEmpty(def.input)) {
+        throw new Error(`Workflow "${def.name}": a scheduled run starts with the input {}, which its input schema refuses: make each field optional or give it a default`);
+    }
     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): ` +
@@ -77,6 +82,41 @@ export function defineWorkflow(def) {
     }
     return Object.freeze({ kind: "workflow", ...def, file });
 }
+/** True when `{}` parses: a schema zod can check only asynchronously is taken as accepting it, and the run parses it. */
+function acceptsEmpty(schema) {
+    try {
+        return schema.safeParse({}).success;
+    }
+    catch {
+        return true;
+    }
+}
+/** Throws what is wrong with a workflow's `trigger`: not `manual` or a schedule, five fields, in a time zone there is. */
+function checkTrigger(name, trigger) {
+    if (trigger === "manual")
+        return;
+    const { schedule, timezone } = (typeof trigger === "object" && trigger !== null ? trigger : {});
+    if (typeof schedule !== "string") {
+        throw new Error(`Workflow "${name}": its trigger is "manual" or { schedule, timezone? }`);
+    }
+    if (schedule.trim().split(/\s+/).length !== 5) {
+        throw new Error(`Workflow "${name}": its schedule "${schedule}" is a cron expression of five fields: minute, hour, day of month, month, day of week`);
+    }
+    if (timezone !== undefined && !isTimeZone(timezone)) {
+        throw new Error(`Workflow "${name}": its timezone "${String(timezone)}" is no IANA time zone, such as "Europe/Amsterdam"`);
+    }
+}
+const isTimeZone = (zone) => {
+    // An offset (`+05:30`), which Intl takes too, is no IANA zone name.
+    if (typeof zone !== "string" || /^[+-]/.test(zone))
+        return false;
+    try {
+        return Boolean(new Intl.DateTimeFormat("en", { timeZone: zone }));
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * 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.

package/dist/define.js.map

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

package/dist/demo.d.ts

@@ -0,0 +1,28 @@
+import type { SanomaClient } from "./client.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { type Moment } from "./scenario.ts";
+/** What the last `reseed` of an instance did: what the demo's banner shows. */
+export interface DemoState {
+    /** When it was seeded, as an ISO timestamp. */
+    seededAt: string;
+    /** The worlds applied, by scenario name. */
+    worlds: string[];
+    /** Each moment started and left waiting: who it is for, where they land, its scenario and its run. */
+    moments: (Moment & {
+        scenario: string;
+        runId: string;
+    })[];
+    /** What could not be done, one line each: a feature file that did not load, a world or a moment that failed. */
+    problems: string[];
+}
+/**
+ * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
+ * saved through the collections' driver, its vendor objects put in the fakes), then starts each
+ * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
+ * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
+ * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ */
+export declare function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState>;
+/** What the instance's last `reseed` did, or undefined before its first. */
+export declare const demoState: (resolved: ResolvedConfig) => DemoState | undefined;

package/dist/demo.js

@@ -0,0 +1,72 @@
+import { DATA_TABLE } from "./db.js";
+import { applyGivens } from "./sandbox.js";
+import { loadScenarios } from "./scenario.js";
+import { memorySecrets } from "./secret.js";
+import { errorMessage } from "./shared.js";
+/** Each instance's last reseed, by its resolution. */
+const states = new WeakMap();
+/**
+ * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
+ * saved through the collections' driver, its vendor objects put in the fakes), then starts each
+ * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
+ * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
+ * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ */
+export async function reseed(client, resolved) {
+    const fakes = resolved.instanceFakes;
+    if (!fakes)
+        throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+    // Read first, so scenarios that cannot be read at all leave the instance as it was.
+    const { scenarios, errors } = await loadScenarios(resolved);
+    if (resolved.dataStore)
+        await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+    for (const fake of fakes.values())
+        fake.reset();
+    const state = {
+        seededAt: new Date().toISOString(),
+        worlds: [],
+        moments: [],
+        problems: errors.map((e) => e.message),
+    };
+    const secrets = memorySecrets();
+    for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+        try {
+            await applyGivens(world, {
+                kind: "instance",
+                drivers: resolved.drivers,
+                fakes,
+                ops: resolved.ops,
+                call: (i, opId) => ({
+                    idempotencyKey: `world:${world.name}:${i}`,
+                    runId: `world:${world.name}`,
+                    opId,
+                    attempt: 1,
+                    secrets,
+                    // Who its records are by: whoever it says is acting, else the runtime's own agent.
+                    by: world.startedBy ?? "scenarios",
+                }),
+            });
+            state.worlds.push(world.name);
+        }
+        catch (err) {
+            state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
+        }
+    }
+    for (const s of scenarios) {
+        if (!s.moment || s.workflow === undefined)
+            continue;
+        try {
+            const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });
+            state.moments.push({ ...s.moment, scenario: s.name, runId });
+        }
+        catch (err) {
+            state.problems.push(`moment "${s.name}": ${errorMessage(err)}`);
+        }
+    }
+    states.set(resolved, state);
+    return state;
+}
+/** What the instance's last `reseed` did, or undefined before its first. */
+export const demoState = (resolved) => states.get(resolved);
+//# sourceMappingURL=demo.js.map

package/dist/demo.js.map

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

package/dist/describe.d.ts

@@ -1,7 +1,7 @@
 import { type LintProblem } from "./ast.ts";
 import { type Field } from "./collection.ts";
 import { type SanomaConfig } from "./config.ts";
-import { type Builtin } from "./define.ts";
+import { type Builtin, type Trigger } from "./define.ts";
 import { type Effect } from "./op.ts";
 import { type Outline } from "./outline.ts";
 import { type ResourceFields } from "./resource.ts";
@@ -19,15 +19,18 @@ export { Reference, type DataValue } from "./datafile.ts";
  */
 export declare function readResources(config: SanomaConfig): DeclaredResource[];
 export { LOCKFILE, readLockfile, serializeLockfile, writeLockfile, diffLockfiles, type Binding, type Bindings, type Rebind, } from "./lockfile.ts";
-export { readSites, type SiteCall, type SiteEntry } from "./sites.ts";
+export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPages, siteLocales } from "./sites.ts";
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
 export { SCHEMA_FILE, schemaOf, schemaText, type CedarSchemaJson } from "./schema.ts";
+export { columnPrincipal, permissionsGrid, type PermissionsGrid, type PermissionsRow } from "./grid.ts";
+export { previewRequests } from "./shared.ts";
 export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.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";
+    /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
+    trigger: Trigger;
     /**
      * Set for a workflow the runtime adds itself, `drift`, `apply` or `call`, rather than the config: a label. It
      * starts like any other.

package/dist/describe.js

@@ -34,11 +34,14 @@ export function readResources(config) {
 }
 export { LOCKFILE, readLockfile, serializeLockfile, writeLockfile, diffLockfiles, } from "./lockfile.js";
 // What the sites call, read from their source: a workflow's Used by.
-export { readSites } from "./sites.js";
+export { readSites, siteContentPages, siteLocales } from "./sites.js";
 // The generated SDK, `.sanoma/api.ts`: a site's `api` typed from this description.
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.js";
 // The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
 export { SCHEMA_FILE, schemaOf, schemaText } from "./schema.js";
+// The Permissions grid: the app's page and `sanoma check`'s `checked` event compute it the one way.
+export { columnPrincipal, permissionsGrid } from "./grid.js";
+export { previewRequests } from "./shared.js";
 /**
  * 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
@@ -169,15 +172,16 @@ function domainProblems(root, declared, types, sites, read) {
             const others = `${names.length === 2 ? "both " : ""}${names.slice(0, -1).join(", ")}`;
             messages.push(`${domain} is the domain of ${others} and ${names.at(-1)}`);
         }
-        if (!messages.length || root === undefined)
-            continue;
-        const file = read(join(root, resource.file));
-        const at = typeof file === "string" ? {} : file.at(resource.span[0]);
-        for (const message of messages)
-            problems.push({ file: resource.file, ...at, message });
+        if (root !== undefined)
+            problems.push(...messages.map((message) => problemAt(root, resource, read, message)));
     }
     return problems;
 }
+/** `message` at a declaration's `export const`. */
+function problemAt(root, resource, read, message) {
+    const file = read(join(root, resource.file));
+    return { file: resource.file, ...(typeof file === "string" ? {} : file.at(resource.span[0])), message };
+}
 /**
  * A site's `api` names each workflow `apiNameOf(name)` beside the vendors' operations and the
  * collections (`api.data`), so a workflow whose name comes out as another's, a vendor's id or