@wtfalch/foundry 0.60.0 → 0.62.0

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;
@@ -121,8 +124,17 @@ export function classifyChange(org, change, plan) {
         throw new RequestedChangeError(`'${change.field}' is not a requestable field`);
     }
     // Archon validates the whole company for these; nothing waits for approval.
-    if (change.field === 'app' || change.field === 'build')
+    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`, `-kosmos`, `-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

@@ -138,6 +138,14 @@ const AGORA_SUFFIX = /-agora$/;
  * one that opts in.
  */
 const BOULE_SUFFIX = /-boule$/;
+/**
+ * `<something>-kosmos` — a level-1 org's own kosmos hostname
+ * (`<slug>-kosmos.oikos.host`, foundry#949). Kosmos is opt-in, the same way
+ * {@link CALLS_SUFFIX} guards a feature an org can decline: a slug ending
+ * `-kosmos` is only barred because it collides with that one org's own
+ * hostname once kosmos is on, not because every org gets one.
+ */
+const KOSMOS_SUFFIX = /-kosmos$/;
 /** `<something>-auth|-mail|-files|-sfu|-cms` — an own company's service hostnames on oikos.host (`plan/own-hostnames.ts`). */
 const OWN_SERVICE_SUFFIX = /-(auth|mail|files|sfu|cms)$/;
 /**
@@ -151,6 +159,16 @@ 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`, `-kosmos`, `-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) ||
+        KOSMOS_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,15 +195,10 @@ 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`,
+            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora', '-boule', '-kosmos', '-auth', '-mail', '-files', '-sfu' or '-cms') reserved for another org's own hostname (#28, #145, #164, #161, #949) — '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, 'acme-kosmos' only as acme's kosmos hostname, never as an org slug in its own right`,
         };
     }
     return null;

package/dist/store/postgres.js

@@ -161,12 +161,30 @@ 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') } }
             : {}),
+        // Omitted while unset, as `boule`/`agora` are. Validated on read, the same way.
+        ...(row.kosmosBlueGreen || row.kosmosEnabled
+            ? {
+                kosmos: {
+                    ...(row.kosmosBlueGreen
+                        ? { blueGreen: readBlueGreen(row.kosmosBlueGreen, 'kosmos') }
+                        : {}),
+                    ...(row.kosmosEnabled ? { enabled: true } : {}),
+                },
+            }
+            : {}),
         ...(row.versionPin ? { versionPin: readVersionPin(row) } : {}),
         site: { enabled: row.siteEnabled, usesDomain: row.siteUsesDomain },
         hosting: {
@@ -177,6 +195,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,7 +249,10 @@ 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,
+        kosmosEnabled: org.kosmos?.enabled ?? false,
+        kosmosBlueGreen: org.kosmos?.blueGreen ?? null,
         servicesOwn: org.services?.own ?? false,
         servicesSfuSlot: org.services?.sfuSlot ?? null,
         versionPin: org.versionPin && Object.keys(org.versionPin).length > 0 ? org.versionPin : null,
@@ -243,6 +265,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,59 @@ 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;
+        }, {}, {}>;
+        kosmosEnabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kosmos_enabled";
+            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;
+        }, {}, {}>;
+        kosmosBlueGreen: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kosmos_blue_green";
+            tableName: "foundry_declared_orgs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: BlueGreenConfig | null;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: BlueGreenConfig | null;
+        }>;
         versionPin: import("drizzle-orm/pg-core").PgColumn<{
             name: "version_pin";
             tableName: "foundry_declared_orgs";
@@ -711,6 +764,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,11 @@ 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),
+    // KosmosApp (org.ts, foundry#949): the company's own kosmos, set up only when asked; `migrations/0066_org_kosmos.sql`.
+    kosmosEnabled: boolean('kosmos_enabled').notNull().default(false),
+    kosmosBlueGreen: jsonb('kosmos_blue_green').$type(),
     // 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 +81,11 @@ 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(),
+    // migrations/0065 added `hosting_native_apps` for foundry#948; foundry#951 dropped the column from
+    // use (Boule owns native settings now, estate#262) but not from the database -- a migration only
+    // adds in this release, since idle and live share one database. The column stays, unread.
     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

@@ -80,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;
@@ -97,10 +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;
-/** The most functions `database.grants` may name, and the shape of one signature. It is spliced into SQL, so nothing else passes. */
-export declare const WORKER_APP_GRANTS_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,24 +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 most functions `database.grants` may name, and the shape of one signature. It is spliced into SQL, so nothing else passes. */
-export const WORKER_APP_GRANTS_MAX = 100;
-const FUNCTION_SIGNATURE = /^[A-Za-z_][A-Za-z0-9_]{0,62}(\.[A-Za-z_][A-Za-z0-9_]{0,62})?\(([a-z][a-z0-9_]*( [a-z][a-z0-9_]*)?(, [a-z][a-z0-9_]*( [a-z][a-z0-9_]*)?)*)?\)$/;
 /** 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;
@@ -58,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
@@ -206,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`;
     }

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[];
+}>;