@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/release/run.js

@@ -25,6 +25,10 @@ export async function runRelease(input) {
         actions,
         steps: input.entry.steps,
         stepHoldMinutes: input.entry.stepHoldMinutes,
+        advance: input.entry.advance,
+        minRequests: input.entry.minRequests,
+        errorMargin: input.entry.errorMargin,
+        staffFirst: input.entry.staffFirst,
         now,
         observation: { health, ...seen },
         ...(input.hardOnly ? { hardOnly: true } : {}),

package/dist/release/state.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { Recorded } from './decide.js';
+import { type Recorded, resolveReleaseConfig } from './decide.js';
 import type { Color, ReleaseAction, ReleaseSignal, ReleaseState, WindowState } from './types.js';
 /**
  * The persistence the release runner and Archon share. `getScopeIds` is the
@@ -52,6 +52,8 @@ export declare function readSignal(ids: Record<string, string>, entryKey: string
 export declare function readReleaseState(store: ReleaseStore, input: {
     orgId: string;
     entryKey: string;
+    /** The entry's `blueGreen` as declared; defaults are resolved into `config`. */
+    entry?: Parameters<typeof resolveReleaseConfig>[0];
 }): Promise<ReleaseState | null>;
 declare const actionSchema: z.ZodType<ReleaseAction>;
 /** C2: ask the runner to apply an action on its next run. Archon audits it. */

package/dist/release/state.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { STAGE_REF_PATTERN, resolveReleaseConfig } from './decide.js';
 /** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
 export function releaseKeys(entry) {
     if (!/^[a-z0-9][a-z0-9-]*$/.test(entry))
@@ -33,6 +34,7 @@ const storedWindow = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('passed'), at: z.string() }),
     z.object({ kind: z.literal('rolled_back'), at: z.string(), reason: z.string() }),
     z.object({ kind: z.literal('cap'), since: z.string() }),
+    z.object({ kind: z.literal('staff'), since: z.string() }),
 ]);
 const releaseField = z
     .object({
@@ -110,6 +112,7 @@ export async function readReleaseState(store, input) {
         window: r.window,
         signal: readSignal(ids, input.entryKey),
         held: r.held,
+        config: resolveReleaseConfig(input.entry),
     };
 }
 const actionSchema = z.discriminatedUnion('kind', [
@@ -117,6 +120,9 @@ const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('rollback') }),
     z.object({ kind: z.literal('clear_held'), digest: z.string().min(1) }),
     z.object({ kind: z.literal('decide_at_cap'), decision: z.enum(['pass', 'rollback']) }),
+    z.object({ kind: z.literal('approve_step') }),
+    z.object({ kind: z.literal('open') }),
+    z.object({ kind: z.literal('deploy_stage'), ref: z.string().regex(STAGE_REF_PATTERN) }),
 ]);
 /** C2: ask the runner to apply an action on its next run. Archon audits it. */
 export async function requestReleaseAction(store, input) {

package/dist/release/types.d.ts

@@ -22,6 +22,11 @@ export type WindowState = {
 } | {
     kind: 'cap';
     since: string;
+}
+/** Deployed on the idle color at weight 0, waiting for an `open` action (staffFirst). */
+ | {
+    kind: 'staff';
+    since: string;
 };
 export interface ReleaseSignal {
     requests: number;
@@ -29,6 +34,13 @@ export interface ReleaseSignal {
     baselineRate: number | null;
     verdict: 'pass' | 'fail' | 'hard_fail' | 'inconclusive';
 }
+/** The release kind of an entry, defaults resolved. */
+export interface ReleaseConfig {
+    advance: 'time' | 'signal' | 'approval';
+    steps: number[];
+    stepHoldMinutes: number;
+    staffFirst: boolean;
+}
 export interface ReleaseState {
     entryKey: string;
     live: Color;
@@ -38,6 +50,7 @@ export interface ReleaseState {
     window: WindowState;
     signal: ReleaseSignal | null;
     held: string[];
+    config: ReleaseConfig;
 }
 export type ReleaseAction = {
     kind: 'promote';
@@ -49,6 +62,13 @@ export type ReleaseAction = {
 } | {
     kind: 'decide_at_cap';
     decision: 'pass' | 'rollback';
+} | {
+    kind: 'approve_step';
+} | {
+    kind: 'open';
+} | {
+    kind: 'deploy_stage';
+    ref: string;
 };
 export declare const COLORS: readonly Color[];
 export declare function otherColor(color: Color): Color;

package/dist/requested-changes.d.ts

@@ -16,7 +16,7 @@ import type { PlanDetail } from './plan/diff.js';
  * lowering or leaving a limit unchanged -- raising either one needs
  * approval too, until a billing field exists to say what the raise costs.
  */
-export type RequestableField = 'calls' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier' | 'app' | 'build';
+export type RequestableField = 'calls' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier' | 'app' | 'build' | 'bouleApps';
 export declare const REQUESTABLE_FIELDS: readonly RequestableField[];
 /** Turn the org's own calls Matrix stack (`org.ts`'s `CallsConfig.enabled`) on or off. */
 export interface CallsChange {
@@ -75,12 +75,21 @@ export interface BuildChange {
     release: string;
     build: BuildJson;
 }
+/**
+ * Turn `org.boule.apps` on or off (`org.ts`'s `BouleApp.apps`). The company's own Boule turns it on when it makes
+ * its first app, so no infra is provisioned that is not in use. On is `auto`. Off retires the edge key, both
+ * registrar keys and the apps database route (steps with `destroys: true`), so it always needs a person.
+ */
+export interface BouleAppsChange {
+    field: 'bouleApps';
+    enabled: boolean;
+}
 /**
  * One company-requested change to its own declared org, keyed by
  * {@link RequestableField}. `classifyChange` and the store both switch on
  * `.field`.
  */
-export type RequestedChangeValue = CallsChange | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange | AppChange | BuildChange;
+export type RequestedChangeValue = CallsChange | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange | AppChange | BuildChange | BouleAppsChange;
 /**
  * `auto`: nothing further is required -- archon may carry the request
  * straight into a plan and apply it. `approval`: a human must approve the

package/dist/requested-changes.js

@@ -8,6 +8,7 @@ export const REQUESTABLE_FIELDS = [
     'mailTier',
     'app',
     'build',
+    'bouleApps',
 ];
 /**
  * Thrown by {@link classifyChange} (and by the requested-change store's
@@ -44,6 +45,8 @@ function applyRequestedChange(org, change) {
             return { ...org, domain: change.domain };
         case 'mailTier':
             return { ...org, mail: { ...org.mail, mode: change.mode } };
+        case 'bouleApps':
+            return { ...org, boule: { ...org.boule, apps: change.enabled } };
         case 'app':
         case 'build':
             return org;
@@ -123,6 +126,14 @@ export function classifyChange(org, change, plan) {
     // Archon validates the whole company for these; nothing waits for approval.
     if (change.field === 'app' || change.field === 'build')
         return 'auto';
+    if (change.field === 'bouleApps') {
+        if (typeof change.enabled !== 'boolean') {
+            throw new RequestedChangeError('bouleApps needs enabled, true or false');
+        }
+        // Turning on provisions only what the first app needs. Turning off retires credentials and routes
+        // (`destroys: true` steps), so it needs a person whether or not a plan was given.
+        return change.enabled ? 'auto' : 'approval';
+    }
     if (change.field === 'customers') {
         validateCustomersChange(change);
         // The org after the change must still pass the rule apply checks, for example open registration

package/dist/service-labels.d.ts

@@ -0,0 +1,4 @@
+/** The labels an own org's services answer on, so no hosting entry may take them. */
+export declare const OWN_SERVICE_LABELS: readonly ["auth", "mail", "files", "sfu"];
+/** The first label of every name foundry itself serves for a company: its own services, Agora, Boule, the cms studio, calls, the sign-in host and file shares. */
+export declare const FOUNDRY_SERVICE_LABELS: ReadonlySet<string>;

package/dist/service-labels.js

@@ -0,0 +1,11 @@
+/** The labels an own org's services answer on, so no hosting entry may take them. */
+export const OWN_SERVICE_LABELS = ['auth', 'mail', 'files', 'sfu'];
+/** The first label of every name foundry itself serves for a company: its own services, Agora, Boule, the cms studio, calls, the sign-in host and file shares. */
+export const FOUNDRY_SERVICE_LABELS = new Set([
+    ...OWN_SERVICE_LABELS,
+    'agora',
+    'boule',
+    'cms',
+    'calls',
+    'share',
+]);

package/dist/slug.d.ts

@@ -2,6 +2,8 @@
 export declare const RESERVED_SLUGS: ReadonlySet<string>;
 /** Every platform app, tunnel, project and database name starts `platform-`, so no company slug may. */
 export declare const RESERVED_SLUG_PREFIX = "platform-";
+/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
+export declare function hasBarredSlugSuffix(label: string): boolean;
 /**
  * Why {@link validateSlug} refused a candidate slug, by name so a caller —
  * `store/postgres.ts`'s `DeclaredOrgError`, eventually the operator page —

package/dist/slug.js

@@ -151,6 +151,15 @@ const OWN_SERVICE_SUFFIX = /-(auth|mail|files|sfu|cms)$/;
  * `names-`.
  */
 const NAMES_PREFIX = /^names(-|$)/;
+/** Whether `label` ends in a suffix reserved for another org's own hostname (`-stage`, `-pr-<n>`, `-calls`, `-agora`, `-boule`, `-auth`, `-mail`, `-files`, `-sfu`, `-cms`). */
+export function hasBarredSlugSuffix(label) {
+    return (STAGE_SUFFIX.test(label) ||
+        PR_SUFFIX.test(label) ||
+        CALLS_SUFFIX.test(label) ||
+        AGORA_SUFFIX.test(label) ||
+        BOULE_SUFFIX.test(label) ||
+        OWN_SERVICE_SUFFIX.test(label));
+}
 /**
  * Validates a candidate org slug against every rule #28 decided. Returns
  * `null` when the slug is acceptable, or a {@link SlugRejection} naming
@@ -177,12 +186,7 @@ export function validateSlug(slug) {
             message: `slug '${slug}' is 'names' or starts with 'names-', a prefix edge reserves for its own platform tunnels and refuses to create a company tunnel under (#535)`,
         };
     }
-    if (STAGE_SUFFIX.test(slug) ||
-        PR_SUFFIX.test(slug) ||
-        CALLS_SUFFIX.test(slug) ||
-        AGORA_SUFFIX.test(slug) ||
-        BOULE_SUFFIX.test(slug) ||
-        OWN_SERVICE_SUFFIX.test(slug)) {
+    if (hasBarredSlugSuffix(slug)) {
         return {
             reason: 'environment-suffix',
             message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora', '-boule', '-auth', '-mail', '-files', '-sfu' or '-cms') reserved for another org's own hostname (#28, #145, #164, #161) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, never as an org slug in its own right`,

package/dist/store/postgres.js

@@ -161,8 +161,15 @@ function rowToOrg(row) {
             ? { customers: { enabled: row.customersEnabled, signUp: row.customersSignUp } }
             : {}),
         // Omitted while unset. Validated on read: a stored value is not trusted.
-        ...(row.bouleBlueGreen
-            ? { boule: { blueGreen: readBlueGreen(row.bouleBlueGreen, 'boule') } }
+        ...(row.bouleBlueGreen || row.bouleApps
+            ? {
+                boule: {
+                    ...(row.bouleBlueGreen
+                        ? { blueGreen: readBlueGreen(row.bouleBlueGreen, 'boule') }
+                        : {}),
+                    ...(row.bouleApps ? { apps: true } : {}),
+                },
+            }
             : {}),
         ...(row.agoraBlueGreen
             ? { agora: { blueGreen: readBlueGreen(row.agoraBlueGreen, 'agora') } }
@@ -177,6 +184,7 @@ function rowToOrg(row) {
             entries: row.hostingEntries.map((entry) => storedEntryToEntry(entry, row.hostingUsesDomain)),
             gateLimit: row.hostingGateLimit,
             repos: row.hostingRepos,
+            ...(row.hostingGithub ? { github: row.hostingGithub } : {}),
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -230,6 +238,7 @@ function orgToRow(org) {
         customersEnabled: org.customers?.enabled ?? false,
         customersSignUp: org.customers?.signUp ?? false,
         bouleBlueGreen: org.boule?.blueGreen ?? null,
+        bouleApps: org.boule?.apps ?? false,
         agoraBlueGreen: org.agora?.blueGreen ?? null,
         servicesOwn: org.services?.own ?? false,
         servicesSfuSlot: org.services?.sfuSlot ?? null,
@@ -243,6 +252,7 @@ function orgToRow(org) {
         hostingEntries: org.hosting.entries,
         hostingGateLimit: org.hosting.gateLimit,
         hostingRepos: normalizeHostingRepos(org.hosting.repos),
+        hostingGithub: org.hosting.github ?? null,
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
-import type { AppEnvSource, BlueGreenConfig, HostingEntry, IssuerApp, OwnerIdentity } from '../org.js';
+import type { AppEnvSource, BlueGreenConfig, HostingEntry, HostingGithub, IssuerApp, OwnerIdentity } from '../org.js';
 import type { Plan } from '../plan.js';
 import type { Checkpoint, DestroyRecord } from '../state.js';
 /**
@@ -444,6 +444,23 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: BlueGreenConfig | null;
         }>;
+        bouleApps: import("drizzle-orm/pg-core").PgColumn<{
+            name: "boule_apps";
+            tableName: "foundry_declared_orgs";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         versionPin: import("drizzle-orm/pg-core").PgColumn<{
             name: "version_pin";
             tableName: "foundry_declared_orgs";
@@ -711,6 +728,25 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: string[];
         }>;
+        hostingGithub: import("drizzle-orm/pg-core").PgColumn<{
+            name: "hosting_github";
+            tableName: "foundry_declared_orgs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: HostingGithub | null;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: HostingGithub | null;
+        }>;
         ssoEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sso_enabled";
             tableName: "foundry_declared_orgs";

package/dist/store/schema.js

@@ -46,6 +46,8 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     // OrgBuiltinApp.blueGreen (org.ts) of Boule and Agora; `migrations/0059_org_builtin_blue_green.sql`. Null is off.
     bouleBlueGreen: jsonb('boule_blue_green').$type(),
     agoraBlueGreen: jsonb('agora_blue_green').$type(),
+    // BouleApp.apps (org.ts): Boule runs apps for the company; `migrations/0063_boule_apps.sql`.
+    bouleApps: boolean('boule_apps').notNull().default(false),
     // VersionPin (org.ts): null follows the platform. `migrations/0053_org_version_pin.sql`.
     versionPin: jsonb('version_pin').$type(),
     // SiteConfig (org.ts, T10). A brand new org has no cms site.
@@ -76,6 +78,8 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     hostingGateLimit: integer('hosting_gate_limit').notNull().default(3),
     // HostingConfig.repos (org.ts); migrations/0060. Lowercase `wtfalch/<name>` strings.
     hostingRepos: jsonb('hosting_repos').notNull().default([]).$type(),
+    // HostingConfig.github (org.ts); migrations/0062. Null: the company has no GitHub App installation.
+    hostingGithub: jsonb('hosting_github').$type(),
     ssoEnabled: boolean('sso_enabled').notNull().default(false),
     guestsEnabled: boolean('guests_enabled').notNull().default(false),
     soloEnabled: boolean('solo_enabled').notNull().default(false),

package/dist/worker-app-config.d.ts

@@ -60,10 +60,14 @@ export interface WorkerAppConfig {
      * or truncate. `migrationsSha256` (64 lowercase hex) pins the release's
      * `migrations.json`: required when the release has one, and foundry refuses
      * to parse bytes whose sha256 differs. Omit it only for a release with no
-     * `migrations.json`; one that has the file is then refused.
+     * `migrations.json`; one that has the file is then refused. `grants` names
+     * functions the runtime role may execute, as `name(type, ...)` or
+     * `schema.name(type, ...)`: the security definer functions a migration
+     * revoked from public, such as `@wtfalch/audit`'s ledger functions.
      */
     database?: {
         appendOnly?: string[];
+        grants?: string[];
         migrationsSha256?: string;
     };
     /** Plain vars. Never secrets. */
@@ -76,14 +80,8 @@ export declare const WORKER_APP_COMPATIBILITY_FLAGS: ReadonlySet<string>;
 export declare const WORKER_APP_INSTANCE_TYPES: ReadonlySet<string>;
 /** The most instances one container class may scale to. */
 export declare const WORKER_APP_MAX_INSTANCES = 100;
-/** The secret that carries a `keysCustody` source: the custody Worker credential. */
-export declare const WORKER_APP_KEYS_SECRET = "KEYS_CREDENTIAL";
+export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
 export declare const WORKER_APP_KEYS_URL_VAR = "KEYS_URL";
-/**
- * Names foundry writes into a Worker app's environment itself, so a
- * declaration may not use them as a binding, secret or var.
- */
-export declare const WORKER_APP_RESERVED_NAMES: RegExp;
 /** True when the entry needs the org's Postgres database: a Coolify app with `database`, or a Worker app with `workerApp.database`. */
 export declare const entryHasDatabase: (entry: {
     database: boolean;
@@ -93,8 +91,6 @@ export declare const entryHasDatabase: (entry: {
 }) => boolean;
 /** The Hyperdrive binding of a Worker app with `database`. */
 export declare const WORKER_APP_HYPERDRIVE_BINDING = "HYPERDRIVE";
-/** The most tables `database.appendOnly` may name, and the shape of one name (`table` or `schema.table`). */
-export declare const WORKER_APP_APPEND_ONLY_MAX = 100;
 /** Hex characters of the org id's sha256 in a host id. */
 export declare const WORKER_APP_HOST_ID_HASH_LENGTH = 12;
 /**

package/dist/worker-app-config.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { WORKER_APP_ENV_NAME as ENV_NAME, WORKER_APP_FUNCTION_SIGNATURE as FUNCTION_SIGNATURE, SECRET_LIKE_NAME as SECRET_NAME, WORKER_APP_TABLE_NAME as TABLE_NAME, WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
 import { validateSlug } from './slug.js';
 /** The compatibility flags a Worker app may ask for. */
 export const WORKER_APP_COMPATIBILITY_FLAGS = new Set(['nodejs_compat']);
@@ -12,21 +13,12 @@ export const WORKER_APP_INSTANCE_TYPES = new Set([
 ]);
 /** The most instances one container class may scale to. */
 export const WORKER_APP_MAX_INSTANCES = 100;
-/** The secret that carries a `keysCustody` source: the custody Worker credential. */
-export const WORKER_APP_KEYS_SECRET = 'KEYS_CREDENTIAL';
+export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
 export const WORKER_APP_KEYS_URL_VAR = 'KEYS_URL';
-/**
- * Names foundry writes into a Worker app's environment itself, so a
- * declaration may not use them as a binding, secret or var.
- */
-export const WORKER_APP_RESERVED_NAMES = /^(AUTH_.*|KEYS_.*|MCP_.*|HYPERDRIVE)$/;
 /** True when the entry needs the org's Postgres database: a Coolify app with `database`, or a Worker app with `workerApp.database`. */
 export const entryHasDatabase = (entry) => entry.database || Boolean(entry.workerApp?.database);
 /** The Hyperdrive binding of a Worker app with `database`. */
 export const WORKER_APP_HYPERDRIVE_BINDING = 'HYPERDRIVE';
-/** The most tables `database.appendOnly` may name, and the shape of one name (`table` or `schema.table`). */
-export const WORKER_APP_APPEND_ONLY_MAX = 100;
-const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}(\.[A-Za-z_][A-Za-z0-9_]{0,62})?$/;
 /** The custody Worker's host id shape for a derived (app) host, and its limit. */
 const HOST_ID = /^app-[a-z0-9]+(-[a-z0-9]+)*$/;
 const HOST_ID_MAX_LENGTH = 64;
@@ -55,12 +47,10 @@ const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const RELEASE_ASSET_URL = /^https:\/\/github\.com\/wtfalch\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+)$/;
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 const DIGEST = /^sha256:[0-9a-f]{64}$/;
-const ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
 const CLASS_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 const MIGRATION_TAG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const IMAGE_REPOSITORY = /^[a-z0-9]+([._-][a-z0-9]+)*(:[0-9]+)?(\/[a-z0-9]+([._-][a-z0-9]+)*)+$/;
 const COMPAT_DATE = /^\d{4}-\d{2}-\d{2}$/;
-const SECRET_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
 const VAR_MAX_LENGTH = 1000;
 /**
  * Checks an artifact reference: an https URL with no userinfo, query or
@@ -203,9 +193,9 @@ export function validateEntryWorkerApp(entry, hosting, names) {
     if (Object.keys(entry.env).length > 0) {
         return `${at} has no Coolify app, so env does not apply: use workerApp.vars or workerApp.secrets`;
     }
-    const unsupported = Object.keys(entry.uses ?? {}).find((use) => use !== 'auth');
+    const unsupported = Object.keys(entry.uses ?? {}).find((use) => use !== 'auth' && use !== 'audit');
     if (unsupported)
-        return `${at} supports uses.auth only, not uses.${unsupported}`;
+        return `${at} supports uses.auth and uses.audit only, not uses.${unsupported}`;
     if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
         return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "${WORKER_APP_NAME_SUFFIX}") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`;
     }
@@ -342,11 +332,26 @@ function validateWorkerAppDatabase(at, app) {
     if (database === undefined)
         return null;
     if (typeof database !== 'object' || database === null || Array.isArray(database)) {
-        return `${at} database must be an object: { appendOnly?: string[]; migrationsSha256?: string }`;
+        return `${at} database must be an object: { appendOnly?: string[]; grants?: string[]; migrationsSha256?: string }`;
     }
-    const unknown = Object.keys(database).find((key) => key !== 'appendOnly' && key !== 'migrationsSha256');
+    const unknown = Object.keys(database).find((key) => key !== 'appendOnly' && key !== 'grants' && key !== 'migrationsSha256');
     if (unknown) {
-        return `${at} database.${unknown} is not a setting: only appendOnly and migrationsSha256`;
+        return `${at} database.${unknown} is not a setting: only appendOnly, grants and migrationsSha256`;
+    }
+    const grants = database.grants;
+    if (grants !== undefined) {
+        if (!Array.isArray(grants) || grants.length > WORKER_APP_GRANTS_MAX) {
+            return `${at} database.grants must be a list of at most ${WORKER_APP_GRANTS_MAX} function signatures`;
+        }
+        const seenGrants = new Set();
+        for (const signature of grants) {
+            if (typeof signature !== 'string' || !FUNCTION_SIGNATURE.test(signature)) {
+                return `${at} database.grants names '${String(signature).slice(0, 80)}', which is not a function signature (name(type, ...) or schema.name(type, ...))`;
+            }
+            if (seenGrants.has(signature))
+                return `${at} database.grants names '${signature}' twice`;
+            seenGrants.add(signature);
+        }
     }
     const sha = database.migrationsSha256;
     if (sha !== undefined && (typeof sha !== 'string' || !SHA256_HEX.test(sha))) {

package/dist/worker-app-migrations.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A Worker app's database changes (the release's `migrations.json`), pure and shared: the
+ * platform apply (`plan/worker-app-database.ts`) and `@wtfalch/foundry/apps` both run them
+ * through `runWorkerAppMigrations` with their own SQL runner. No node beyond crypto, no network.
+ */
+/** One migration of a release's `migrations.json`. */
+export interface DatabaseMigration {
+    id: string;
+    sql: string;
+}
+/**
+ * The SQL a Worker app's database changes need, as the owner `O` of the database: the platform
+ * path reaches it through an Access tunnel (`HyperdriveOrigin`), a company's own Postgres by URL
+ * (`@wtfalch/foundry/apps`). Every method is idempotent.
+ */
+export interface WorkerAppMigrationRunner<O> {
+    /** The migration ids the database's ledger holds, in the order applied. */
+    appliedMigrationIds(owner: O): Promise<string[]>;
+    /** Runs `migration.sql` and records `migration.id` in the ledger in one transaction. */
+    applyMigration(owner: O, migration: DatabaseMigration): Promise<void>;
+    /**
+     * Creates or updates the `runtime.user` role with `runtime.password`, grants it DML on the
+     * tables, revokes UPDATE, DELETE and TRUNCATE from it on each `appendOnly` table, and grants
+     * it EXECUTE on each `grants` function.
+     */
+    ensureRuntimeRole(input: {
+        owner: O;
+        runtime: {
+            user: string;
+            password: string;
+        };
+        appendOnly: string[];
+        grants: string[];
+    }): Promise<void>;
+}
+export declare const WORKER_APP_MIGRATION_TIMEOUT_MS = 300000;
+export declare const MIGRATIONS_ASSET_NAME = "migrations.json";
+/**
+ * Reads a release's `migrations.json`. `null` text is an absent file: no migrations. A file that is
+ * not a list of `{id, sql}` with unique ids is refused, naming no SQL.
+ */
+export declare function parseMigrations(text: string | null): DatabaseMigration[];
+/**
+ * A present `migrations.json` runs as the database owner, so its bytes must be the ones the
+ * declaration pinned. No file needs no digest; a file with no declared digest, or a different
+ * one, is refused before it is parsed. The message names neither the SQL nor the wanted digest.
+ */
+export declare function verifyMigrationsDigest(text: string | null, declared: string | undefined): void;
+/** The URL of `migrations.json` beside the module: the same release, another file. */
+export declare const migrationsUrl: (artifactUrl: string) => string;
+/**
+ * The migrations the database does not hold, in order. The applied ledger must be the first
+ * migrations of the file: a missing or reordered one is refused (migrations are append-only).
+ */
+export declare function unappliedDatabaseMigrations(all: readonly DatabaseMigration[], applied: readonly string[]): DatabaseMigration[];
+/** A migration the platform adds for a module (today `uses.audit`: the pinned `@wtfalch/audit` migrations). */
+export interface PlatformMigration extends DatabaseMigration {
+}
+/** A platform migration not run because the app already ships it, and how that was known. */
+export interface SkippedPlatformMigration {
+    id: string;
+    /** `same id` or `same sql` (a copy under another id), plain words for the log. */
+    why: string;
+}
+/**
+ * The platform migrations still to run, in order, and the ones skipped because the release's own list carries
+ * them (same id, or the same SQL under another id: Candor ships its own copy of the audit migrations).
+ * A platform migration the database's ledger already holds is neither: it ran before. Never applies twice.
+ */
+export declare function pendingPlatformMigrations(platform: readonly PlatformMigration[], own: readonly DatabaseMigration[], applied: readonly string[]): {
+    pending: PlatformMigration[];
+    skipped: SkippedPlatformMigration[];
+};
+/**
+ * The build's database changes, shared by the platform apply and `@wtfalch/foundry/apps`:
+ * `text` (the release's `migrations.json`, `null` when it has none) is checked against
+ * `want.migrationsSha256`, parsed, the unapplied migrations run in order as the owner (each
+ * recorded by the runner's ledger), then the runtime role is made true. A failed migration
+ * throws; those before it stay applied. Messages start with `at` and name no SQL.
+ */
+export declare function runWorkerAppMigrations<O>(runner: WorkerAppMigrationRunner<O>, owner: O, text: string | null, want: {
+    appendOnly: readonly string[];
+    grants?: readonly string[];
+    migrationsSha256?: string;
+}, runtime: {
+    user: string;
+    password: string;
+}, opts: {
+    at: string;
+    call: <T>(label: string, task: () => Promise<T>, ms?: number) => Promise<T>;
+    migrationTimeoutMs?: number;
+    /** After each migration, with every id applied so far. */
+    onApplied?: (done: string[]) => Promise<void>;
+    /**
+     * Migrations a module needs that the app need not ship (`uses.audit`). They run first, each once, unless the
+     * release's own list carries the same one; their ids are not part of the release's append-only check.
+     */
+    platform?: readonly PlatformMigration[];
+    /** One plain line per skipped platform migration. */
+    log?: (line: string) => void;
+}): Promise<{
+    applied: string[];
+    ran: string[];
+    skipped: SkippedPlatformMigration[];
+}>;