@wtfalch/foundry 0.14.0 → 0.16.0

package/dist/bootstrap/declare.d.ts

@@ -27,8 +27,8 @@ export interface BootstrapOwner {
  */
 export declare function ownerIdentity(owner: BootstrapOwner): OwnerIdentity;
 /**
- * Company Included's declared org: the platform's owner, running no app, mail
- * or chat of its own.
+ * Company Included's declared org: the platform's owner, running no app or
+ * mail of its own. Chat is on, like every org's.
  */
 export declare function declaredCompanyOrg(company: BootstrapCompany, owner: BootstrapOwner): DeclaredOrg;
 /**

package/dist/bootstrap/declare.js

@@ -1,4 +1,4 @@
-import { validateOwner } from '../org.js';
+import { validateOwners } from '../org.js';
 import { PLATFORM_SERVICE_KEYS, defaultPlatformHostname } from '../platform.js';
 import { VERSIONS } from './versions.js';
 /** Company Included's own org id, the same literal `test/fakes.ts`'s `basePlatform()` uses for `ownerOrgId`. */
@@ -37,14 +37,14 @@ export function ownerIdentity(owner) {
         givenName: owner.givenName?.trim() ?? '',
         familyName: owner.familyName?.trim() ?? '',
     };
-    const problem = validateOwner(identity);
+    const problem = validateOwners([identity]);
     if (problem)
         throw new Error(`bootstrapPlatform: ${problem}`);
     return identity;
 }
 /**
- * Company Included's declared org: the platform's owner, running no app, mail
- * or chat of its own.
+ * Company Included's declared org: the platform's owner, running no app or
+ * mail of its own. Chat is on, like every org's.
  */
 export function declaredCompanyOrg(company, owner) {
     return {
@@ -58,7 +58,7 @@ export function declaredCompanyOrg(company, owner) {
             ownerMailboxAddress: null,
             noReplyLocalPart: 'no-reply',
         },
-        chat: { enabled: false, usesDomain: false },
+        chat: { enabled: true, usesDomain: false },
         calls: { enabled: false, usesDomain: false },
         issuer: { usesDomain: false },
         site: { enabled: false, usesDomain: false },
@@ -77,7 +77,7 @@ export function declaredCompanyOrg(company, owner) {
         buyer: { legalName: null, orgNumber: null, address: null, vatRegistered: null },
         bespokeAppRepo: null,
         adoptedApp: null,
-        owner: ownerIdentity(owner),
+        owners: [ownerIdentity(owner)],
         test: false,
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingEntryUses, EntryAuth, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
-export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, } from './org.js';
+export { APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, appEntry, ownerMailboxes, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export type { RequestableField, CallsChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
@@ -15,7 +15,7 @@ export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, PlanDetail, PlatformPlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';
@@ -27,7 +27,7 @@ export type { MailIdentityApp, MailIdentityAudienceCheck } from './plan/index.js
 export { checkMailIdentityAudience } from './plan/index.js';
 export type { MailAllowlistApp } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, createZitadelProjectRoles, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './plan/index.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './plan/index.js';

package/dist/index.js

@@ -1,18 +1,18 @@
-export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
+export { APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, appEntry, ownerMailboxes, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateSite, } from './org.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
 export { checkMailIdentityAudience } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, createZitadelProjectRoles, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './plan/index.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './plan/index.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';

package/dist/migrations/0034_owners.sql

@@ -0,0 +1,42 @@
+-- @wtfalch/foundry: an org holds a list of current owners instead of one.
+-- Mirrors `src/store/schema.ts`'s `declaredOrgs.owners`.
+--
+-- Storage is one jsonb array on `foundry_declared_orgs`, the way
+-- `hosting_entries` (0029) holds its list: owners are an ordered list read
+-- and written whole with the org, never joined or queried by owner, and the
+-- first one is the primary. A table would add a join and an ordering column
+-- for nothing. Past owners are not kept.
+--
+-- Moves the 0010 columns (`owner_email`, `owner_given_name`,
+-- `owner_family_name`) into a one-element array for each org that has all
+-- three, and drops them. Numbered 0034 so it cannot collide with a 0033 that
+-- lands first. Safe to run twice: the backfill only touches rows still
+-- holding the old columns, and every drop is `if exists`. Run it in the same
+-- deploy as this version.
+
+alter table foundry_declared_orgs
+  add column if not exists owners jsonb not null default '[]'::jsonb;
+
+do $$
+begin
+  if exists (
+    select 1 from information_schema.columns
+    where table_schema = current_schema()
+      and table_name = 'foundry_declared_orgs'
+      and column_name = 'owner_email'
+  ) then
+    update foundry_declared_orgs
+       set owners = jsonb_build_array(jsonb_build_object(
+         'email', owner_email,
+         'givenName', owner_given_name,
+         'familyName', owner_family_name))
+     where owner_email is not null
+       and owner_given_name is not null
+       and owner_family_name is not null;
+  end if;
+end $$;
+
+alter table foundry_declared_orgs
+  drop column if exists owner_email,
+  drop column if exists owner_given_name,
+  drop column if exists owner_family_name;

package/dist/migrations/0035_chat_on_by_default.sql

@@ -0,0 +1,10 @@
+-- @wtfalch/foundry: chat is on by default for a new org. Mirrors
+-- `src/store/schema.ts`'s `chatEnabled`. Changes the column default only, so
+-- an org row that exists keeps the value it has: every org is provisioned
+-- fresh, so nothing is backfilled and no live org is switched on by this
+-- migration.
+--
+-- Safe to run twice.
+
+alter table foundry_declared_orgs
+  alter column chat_enabled set default true;

package/dist/org.d.ts

@@ -100,9 +100,10 @@ export declare const DEFAULT_NO_REPLY_LOCAL_PART = "no-reply";
  */
 export interface ChatConfig {
     /**
-     * Chat is not in v1 (decided 2026-10-01): off by default for every org.
-     * While off, `apply` plans no chat step and leaves a live chat resource
-     * alone, listed in `unmanaged`; Agora hides all chat and call UI.
+     * On by default for a new org (migration 0035; Decided 2026-10-03: every
+     * company gets working chat before go-live). While off, `apply` plans no
+     * chat step and leaves a live chat resource alone, listed in `unmanaged`;
+     * Agora hides all chat UI.
      */
     enabled: boolean;
     usesDomain: boolean;
@@ -272,8 +273,44 @@ export interface EntryAuth {
     registration: 'open' | 'closed';
     replacesBrokerEntry?: string;
 }
+/**
+ * AI for one entry: a key below the org's own ai key, the `AI_*` env and,
+ * with `webhookPath`, the ai webhook. `offerings` is what the app may call,
+ * delivered as `AI_OFFERINGS_JSON`. `permissions` is a subset of
+ * {@link AI_ENTRY_PERMISSIONS}, which is also the default. ai keeps one
+ * webhook per organisation, so one entry per org may set `webhookPath`.
+ */
+export interface EntryAi {
+    offerings: string[];
+    permissions?: string[];
+    webhookPath?: string;
+}
+/** What an entry's ai key may hold: the most the org's own key holds. */
+export declare const AI_ENTRY_PERMISSIONS: readonly ["ai.offerings:invoke", "ai.runs:create"];
+/** The env names `uses.ai` writes; `env` may not name them. */
+export declare const AI_ENTRY_ENV_NAMES: readonly ["AI_URL", "AI_ORGANISATION_ID", "AI_API_KEY", "AI_WEBHOOK_SECRET", "AI_OFFERINGS_JSON"];
+/**
+ * Files for one entry: a key below the org's own files key, the `FILES_*`
+ * env and one collection per name in `collections`. A name is uppercase
+ * `[A-Z0-9_]`; its id is delivered as `FILES_COLLECTION_<NAME>_ID`.
+ * `permissions` is a subset of {@link FILES_ENTRY_PERMISSIONS}, which is also
+ * the default. `shareHost` asks for `share.<domain>`; it is reported blocked
+ * until the platform files host serves that name.
+ */
+export interface EntryFiles {
+    collections: string[];
+    permissions?: string[];
+    shareHost?: boolean;
+}
+/** What an entry's files key may hold: read and write on its collections, and the most the org's own key holds besides minting. */
+export declare const FILES_ENTRY_PERMISSIONS: readonly ["files.collections:read", "files.files:read", "files.files:download", "files.files:upload", "files.files:replace", "files.files:delete"];
+/** The env names `uses.files` always writes, besides one `FILES_COLLECTION_<NAME>_ID` per collection. */
+export declare const FILES_ENTRY_ENV_NAMES: readonly ["FILES_URL", "FILES_ORGANISATION_ID", "FILES_API_KEY"];
+export declare const filesCollectionEnvName: (name: string) => string;
 export interface HostingEntryUses {
     auth?: EntryAuth;
+    ai?: EntryAi;
+    files?: EntryFiles;
 }
 /**
  * A plain string is pushed as it is, so `validateHosting` refuses one that
@@ -439,28 +476,52 @@ export interface BuyerIdentity {
  */
 export declare function validateBuyerIdentity(buyer: BuyerIdentity): string | null;
 /**
- * The org's owner: the one person a real org is created for, invited into
- * its ZITADEL org by email so they can set their own first credential (a
- * passkey) without a password ever passing through foundry. `null` until an
- * operator names one -- an org can exist declared before its owner is known.
+ * One of the org's current owners: a person a real org is created for,
+ * invited into its ZITADEL org by email so they can set their own first
+ * credential (a passkey) without a password ever passing through foundry.
+ * An org holds a list of them (`DeclaredOrg.owners`), empty until an operator
+ * names one -- an org can exist declared before its owners are known. Past
+ * owners are not kept: removing one from the list forgets them.
  *
- * `apply`'s `zitadel:owner` step (`plan/diff.ts`'s `planOwner`) calls
+ * `apply`'s `zitadel:owner` steps (`plan/diff.ts`'s `planOwner`) call
  * `ZitadelClient.inviteOrgOwner(zitadelOrgId, owner)` once the org's ZITADEL
- * org exists, then never touches this again -- a re-run is idempotent on the
- * recorded invited user id, not on this declared value, so editing `owner`
+ * org exists, then never touch it again -- a re-run is idempotent on the
+ * recorded invited user id, not on this declared value, so editing an owner
  * after the invite has gone out does not send a second one.
+ *
+ * `mailboxAddress` is the owner's own mailbox, when mail is on. The first
+ * owner falls back to `mail.ownerMailboxAddress` when it is unset.
  */
 export interface OwnerIdentity {
     email: string;
     givenName: string;
     familyName: string;
+    mailboxAddress?: string;
 }
 /**
- * `null` when `owner` is valid; otherwise the reason it is not, same shape as
- * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. `owner:
- * null` (no owner named yet) is always valid.
+ * `null` when `owners` is valid; otherwise the reason it is not, same shape as
+ * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. An empty
+ * list (no owner named yet) is always valid. Each owner needs a valid email
+ * and non-empty names; emails are distinct (compared case-insensitively).
  */
-export declare function validateOwner(owner: OwnerIdentity | null): string | null;
+export declare function validateOwners(owners: readonly OwnerIdentity[]): string | null;
+/**
+ * One owner's mailbox to give: the owner's own `mailboxAddress`, or for the
+ * first owner `mail.ownerMailboxAddress`. `address` is `null` when none is
+ * declared. `scopeKey` is keyed by the owner's email, never by position.
+ */
+export interface OwnerMailbox {
+    owner: OwnerIdentity;
+    address: string | null;
+    scopeKey: string;
+}
+export declare function ownerMailboxes(org: Pick<DeclaredOrg, 'owners' | 'mail'>): OwnerMailbox[];
+/**
+ * True when this mailbox is already made: its own key is recorded, or another
+ * owner's key records the same address (the `mail.ownerMailboxAddress` fallback
+ * moves to a new first owner on reorder; the mail port refuses a duplicate).
+ */
+export declare function ownerMailboxRecorded(box: OwnerMailbox, recordedIds: Readonly<Record<string, string>>): boolean;
 /**
  * `null` when `mail` is valid; otherwise the reason it is not (#162,
  * decided 2026-09-29).
@@ -491,7 +552,9 @@ export declare function validateOwner(owner: OwnerIdentity | null): string | nul
  * the same reason: a duplicate or blank entry can never mean anything
  * different from leaving it out.
  */
-export declare function validateMail(org: Pick<DeclaredOrg, 'mail' | 'domain'>): string | null;
+export declare function validateMail(org: Pick<DeclaredOrg, 'mail' | 'domain'> & {
+    owners?: readonly OwnerIdentity[];
+}): string | null;
 /**
  * The form an app foundry does not own takes. Decided in #7's `#15`
  * refinement comment:
@@ -577,8 +640,8 @@ export interface DeclaredOrg {
     bespokeAppRepo: string | null;
     /** `null` when the org has none. */
     adoptedApp: AdoptedApp | null;
-    /** The org's owner, invited by ZITADEL email. `null` until an operator names one. See {@link OwnerIdentity}. */
-    owner: OwnerIdentity | null;
+    /** The org's current owners, each invited by ZITADEL email. Empty until an operator names one; the first is the one `OWNER_USER_ID` names. See {@link OwnerIdentity}. */
+    owners: OwnerIdentity[];
     /**
      * Marks this org as a test org rather than a real customer's. Purely
      * declarative -- it changes nothing about what `apply` provisions -- but it

package/dist/org.js

@@ -4,6 +4,32 @@ export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
 export const DEFAULT_NO_REPLY_LOCAL_PART = 'no-reply';
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export const APP_ENTRY_KEY = 'app';
+/** What an entry's ai key may hold: the most the org's own key holds. */
+export const AI_ENTRY_PERMISSIONS = ['ai.offerings:invoke', 'ai.runs:create'];
+/** The env names `uses.ai` writes; `env` may not name them. */
+export const AI_ENTRY_ENV_NAMES = [
+    'AI_URL',
+    'AI_ORGANISATION_ID',
+    'AI_API_KEY',
+    'AI_WEBHOOK_SECRET',
+    'AI_OFFERINGS_JSON',
+];
+/** What an entry's files key may hold: read and write on its collections, and the most the org's own key holds besides minting. */
+export const FILES_ENTRY_PERMISSIONS = [
+    'files.collections:read',
+    'files.files:read',
+    'files.files:download',
+    'files.files:upload',
+    'files.files:replace',
+    'files.files:delete',
+];
+/** The env names `uses.files` always writes, besides one `FILES_COLLECTION_<NAME>_ID` per collection. */
+export const FILES_ENTRY_ENV_NAMES = [
+    'FILES_URL',
+    'FILES_ORGANISATION_ID',
+    'FILES_API_KEY',
+];
+export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 /** The org's `app` entry: today's one app. */
 export function appEntry(hosting) {
     return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
@@ -72,6 +98,15 @@ export function validateHosting(hosting, names) {
         const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
         if (invalidAuth)
             return invalidAuth;
+        const invalidAi = validateEntryAi(entry, hosting, names?.domain);
+        if (invalidAi)
+            return invalidAi;
+        const invalidFiles = validateEntryFiles(entry, hosting, names?.domain);
+        if (invalidFiles)
+            return invalidFiles;
+    }
+    if (hosting.entries.filter((entry) => entry.uses?.ai?.webhookPath !== undefined).length > 1) {
+        return 'at most one hosting entry may set uses.ai webhookPath: ai keeps one webhook per organisation';
     }
     const invalidNames = validateEntryHostnames(hosting, names);
     if (invalidNames)
@@ -92,6 +127,14 @@ function validateEntryHostnames(hosting, names) {
     const taken = new Set();
     for (const entry of hosting.entries) {
         const at = `hosting.entries '${entry.key}'`;
+        if (entry.hostnames.includes('*')) {
+            if (!hosting.usesDomain || (names && !names.domain)) {
+                return `${at} hostname '*' needs hosting.usesDomain and an org domain: it serves any name under the domain`;
+            }
+            if (hosting.entries.filter((e) => e.hostnames.includes('*')).length > 1) {
+                return `hostname '*' is held by two entries: an org has one wildcard`;
+            }
+        }
         if (!hosting.usesDomain && entry.key !== APP_ENTRY_KEY && entry.hostnames.length > 0) {
             return `${at} hostnames need hosting.usesDomain: without it only the '${APP_ENTRY_KEY}' entry is served, at its own address`;
         }
@@ -209,12 +252,9 @@ function validateEntryAuth(entry, hosting, domain) {
         (typeof auth.replacesBrokerEntry !== 'string' || auth.replacesBrokerEntry === '')) {
         return `${at} replacesBrokerEntry must be the non-empty name of a broker entry`;
     }
-    // With no domain the hostnames are not read (`entryHostnames`).
-    const hasName = hosting.usesDomain && domain !== null
-        ? entry.hostnames.some((name) => name !== '*')
-        : entry.key === APP_ENTRY_KEY;
-    if (!hasName)
+    if (!hasExactHostname(entry, hosting, domain)) {
         return `${at} needs an exact hostname to sign in at`;
+    }
     if (entry.key === 'agora' ||
         entry.key === 'cms' ||
         hosting.issuerApps.some((app) => app.name === entry.key)) {
@@ -222,6 +262,89 @@ function validateEntryAuth(entry, hosting, domain) {
     }
     return null;
 }
+/** With no domain the hostnames are not read (`entryHostnames`). */
+function hasExactHostname(entry, hosting, domain) {
+    return hosting.usesDomain && domain !== null
+        ? entry.hostnames.some((name) => name !== '*')
+        : entry.key === APP_ENTRY_KEY;
+}
+/**
+ * `uses.ai`: at least one offering, permissions from the known set, a
+ * webhook path that is a plain path on an exact hostname, and no `env` entry
+ * that names a value `uses.ai` writes.
+ */
+function validateEntryAi(entry, hosting, domain) {
+    const ai = entry.uses?.ai;
+    if (!ai)
+        return null;
+    const at = `hosting.entries '${entry.key}' uses.ai`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    const isNames = (value) => Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((v) => typeof v === 'string' && v !== '') &&
+        new Set(value).size === value.length;
+    if (!isNames(ai.offerings))
+        return `${at} offerings must be a list of distinct, non-empty names`;
+    if (ai.permissions !== undefined) {
+        const known = AI_ENTRY_PERMISSIONS;
+        if (!isNames(ai.permissions) || !ai.permissions.every((p) => known.includes(p))) {
+            return `${at} permissions must be distinct values of: ${known.join(', ')}`;
+        }
+    }
+    if (ai.webhookPath !== undefined) {
+        if (typeof ai.webhookPath !== 'string' ||
+            !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,199}$/.test(ai.webhookPath) ||
+            ai.webhookPath.startsWith('//')) {
+            return `${at} webhookPath must be a path that starts with one '/', with no query or fragment`;
+        }
+        if (!hasExactHostname(entry, hosting, domain)) {
+            return `${at} webhookPath needs an exact hostname to receive the webhook at`;
+        }
+    }
+    const named = Object.keys(entry.env ?? {}).find((name) => AI_ENTRY_ENV_NAMES.includes(name));
+    if (named)
+        return `${at} writes ${named}; remove it from env`;
+    return null;
+}
+/**
+ * `uses.files`: distinct collection names of uppercase letters, digits and
+ * `_`, permissions from the known set, `shareHost` only with a domain, and no
+ * `env` entry that names a value `uses.files` writes.
+ */
+function validateEntryFiles(entry, hosting, domain) {
+    const files = entry.uses?.files;
+    if (!files)
+        return null;
+    const at = `hosting.entries '${entry.key}' uses.files`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    const names = (value) => Array.isArray(value) &&
+        value.every((v) => typeof v === 'string' && v !== '') &&
+        new Set(value).size === value.length;
+    if (!names(files.collections) || !files.collections.every((n) => /^[A-Z][A-Z0-9_]*$/.test(n))) {
+        return `${at} collections must be distinct names of uppercase letters, digits and '_', starting with a letter`;
+    }
+    if (files.permissions !== undefined) {
+        const known = FILES_ENTRY_PERMISSIONS;
+        if (!names(files.permissions) ||
+            files.permissions.length === 0 ||
+            !files.permissions.every((p) => known.includes(p))) {
+            return `${at} permissions must be distinct values of: ${known.join(', ')}`;
+        }
+    }
+    if (files.shareHost !== undefined && typeof files.shareHost !== 'boolean') {
+        return `${at} shareHost must be true or false`;
+    }
+    if (files.shareHost && !(hosting.usesDomain && domain)) {
+        return `${at} shareHost needs hosting.usesDomain and a domain: it is served at share.<domain>`;
+    }
+    const written = [...FILES_ENTRY_ENV_NAMES, ...files.collections.map(filesCollectionEnvName)];
+    const named = Object.keys(entry.env ?? {}).find((name) => written.includes(name));
+    if (named)
+        return `${at} writes ${named}; remove it from env`;
+    return null;
+}
 function urlHasPassword(value) {
     try {
         return new URL(value).password !== '';
@@ -254,7 +377,7 @@ function urlHasPassword(value) {
  * case both exist to be compared in the first place.
  *
  * `null` when `domain` is valid; otherwise the reason it is not, same shape
- * as {@link validateBuyerIdentity}/{@link validateOwner}.
+ * as {@link validateBuyerIdentity}/{@link validateOwners}.
  */
 const DOMAIN_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 export function validateDomain(domain) {
@@ -339,24 +462,101 @@ export function validateBuyerIdentity(buyer) {
 /** A deliberately loose email shape check -- foundry never sends mail itself, ZITADEL does; this only catches an obviously malformed address before it reaches the invite call. */
 const OWNER_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /**
- * `null` when `owner` is valid; otherwise the reason it is not, same shape as
- * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. `owner:
- * null` (no owner named yet) is always valid.
+ * `null` when `owners` is valid; otherwise the reason it is not, same shape as
+ * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. An empty
+ * list (no owner named yet) is always valid. Each owner needs a valid email
+ * and non-empty names; emails are distinct (compared case-insensitively).
  */
-export function validateOwner(owner) {
-    if (owner === null)
-        return null;
-    if (!OWNER_EMAIL_PATTERN.test(owner.email)) {
-        return `owner email '${owner.email}' is not a valid email address`;
+export function validateOwners(owners) {
+    const seen = new Set();
+    const boxes = new Set();
+    for (const owner of owners) {
+        if (!OWNER_EMAIL_PATTERN.test(owner.email)) {
+            return `owner email '${owner.email}' is not a valid email address`;
+        }
+        if (!owner.givenName.trim())
+            return `owner ${owner.email} givenName must not be empty`;
+        if (!owner.familyName.trim())
+            return `owner ${owner.email} familyName must not be empty`;
+        if (owner.mailboxAddress !== undefined && !OWNER_EMAIL_PATTERN.test(owner.mailboxAddress)) {
+            return `owner ${owner.email} mailboxAddress '${owner.mailboxAddress}' is not a valid email address`;
+        }
+        if (owner.mailboxAddress !== undefined) {
+            const box = owner.mailboxAddress.toLowerCase();
+            if (boxes.has(box))
+                return `owner mailboxAddress '${owner.mailboxAddress}' is listed more than once`;
+            boxes.add(box);
+        }
+        const key = owner.email.toLowerCase();
+        if (seen.has(key))
+            return `owner email '${owner.email}' is listed more than once`;
+        seen.add(key);
     }
-    if (!owner.givenName.trim())
-        return 'owner.givenName must not be empty';
-    if (!owner.familyName.trim())
-        return 'owner.familyName must not be empty';
     return null;
 }
+/**
+ * Each owner's mailbox is recorded under `mail_owner_mailbox.<lowercased email>`, the
+ * same key as the owner's sign-in, so reordering owners moves no mailbox. Removing an
+ * owner revokes nothing: their ZITADEL user, mailbox and recorded keys stay (they can
+ * still sign in), and adding the same email back is skipped as already done. Shared by
+ * `plan/diff.ts` and `plan/executor.ts` through {@link ownerMailboxes}.
+ */
+const OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+export function ownerMailboxes(org) {
+    return org.owners.map((owner, index) => ({
+        owner,
+        address: owner.mailboxAddress ?? (index === 0 ? (org.mail.ownerMailboxAddress ?? null) : null),
+        scopeKey: `${OWNER_MAILBOX_SCOPE_KEY}.${owner.email.toLowerCase()}`,
+    }));
+}
+/**
+ * True when this mailbox is already made: its own key is recorded, or another
+ * owner's key records the same address (the `mail.ownerMailboxAddress` fallback
+ * moves to a new first owner on reorder; the mail port refuses a duplicate).
+ */
+export function ownerMailboxRecorded(box, recordedIds) {
+    if (recordedIds[box.scopeKey])
+        return true;
+    const address = box.address?.toLowerCase();
+    return (address !== undefined &&
+        Object.entries(recordedIds).some(([key, value]) => key.startsWith(`${OWNER_MAILBOX_SCOPE_KEY}.`) && value.toLowerCase() === address));
+}
 /** A local part has no `@` and no whitespace -- loose on purpose, the same restraint {@link OWNER_EMAIL_PATTERN}'s own doc comment states. */
 const LOCAL_PART_PATTERN = /^[^\s@]+$/;
+/**
+ * Each owner's own `mailboxAddress` is on the org's domain (when mail uses it, as
+ * `mail.ownerMailboxAddress` must be), and is not `mail.ownerMailboxAddress`, a
+ * role mailbox or the no-reply address. Addresses compare case-insensitively.
+ * Owner-vs-owner duplicates are {@link validateOwners}' job.
+ */
+function validateOwnerMailboxes(org) {
+    const { mail } = org;
+    const localPart = (a) => a.slice(0, a.indexOf('@')).toLowerCase();
+    const roles = new Set((mail.roleMailboxes ?? []).map((r) => r.toLowerCase()));
+    const noReply = (mail.noReplyLocalPart ?? DEFAULT_NO_REPLY_LOCAL_PART).toLowerCase();
+    for (const owner of org.owners ?? []) {
+        const address = owner.mailboxAddress;
+        if (address === undefined || !OWNER_EMAIL_PATTERN.test(address))
+            continue;
+        if (mail.usesDomain && org.domain) {
+            const addressDomain = address.slice(address.indexOf('@') + 1).toLowerCase();
+            if (addressDomain !== org.domain.toLowerCase()) {
+                return `owner ${owner.email} mailboxAddress '${address}' must be on ${org.domain}`;
+            }
+        }
+        if (mail.ownerMailboxAddress &&
+            address.toLowerCase() === mail.ownerMailboxAddress.toLowerCase()) {
+            return `owner ${owner.email} mailboxAddress '${address}' clashes with mail.ownerMailboxAddress`;
+        }
+        if (roles.has(localPart(address))) {
+            return `owner ${owner.email} mailboxAddress '${address}' clashes with a role mailbox`;
+        }
+        if (localPart(address) === noReply) {
+            return `owner ${owner.email} mailboxAddress '${address}' clashes with the no-reply mailbox`;
+        }
+    }
+    return null;
+}
 /**
  * `null` when `mail` is valid; otherwise the reason it is not (#162,
  * decided 2026-09-29).
@@ -425,6 +625,9 @@ export function validateMail(org) {
             seen.add(name.toLowerCase());
         }
     }
+    const ownerProblem = validateOwnerMailboxes(org);
+    if (ownerProblem)
+        return ownerProblem;
     if (mail.mailApps) {
         const seen = new Set();
         for (const name of mail.mailApps) {

package/dist/plan/agora.d.ts

@@ -12,6 +12,24 @@ import type { DeclaredOrg, OrgId } from '../org.js';
  * (recorded by `executor.ts`'s `zitadelApp`).
  */
 export declare const ZITADEL_ORG_SCOPE_KEY = "zitadel_org";
+/**
+ * The org's ZITADEL messaging project: the audience chat-service requires in
+ * a token's `aud`, and Agora's `messagingProjectId`. `executor.ts`'s
+ * `coolifyChat` finds or creates it (`<slug>-messaging`) and records its id
+ * here; a host value for the same id wins when it supplies one.
+ */
+export declare const ZITADEL_MESSAGING_PROJECT_SCOPE_KEY = "zitadel_messaging_project";
+/**
+ * Recorded by `coolifyChat` last, once chat's three apps carry their fixed
+ * internal names: the chat service's address. `desiredAgoraEnv` waits for it
+ * (equal to the address the current slug gives), so Agora is never handed an
+ * address that does not resolve yet.
+ */
+export declare const CHAT_SERVICE_URL_SCOPE_KEY = "coolify_chat_service_url";
+/** Whether the recorded marker says chat's apps carry the names the org's current slug gives them. */
+export declare function chatHasUpstreams(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): boolean;
+/** `host` with the recorded messaging project filled in when the host supplies none. */
+export declare function withRecordedMessagingProject(host: AgoraHostValues, recorded: Readonly<Record<string, string>>): AgoraHostValues;
 export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
 /**
  * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
@@ -159,7 +177,7 @@ export declare function callsServiceHasTokenEnv(host: CallsTokenHost | null, rec
  * not `host`: present only when calls are on and this org's calls service
  * app carries its internal name ({@link callsServiceHasName}).
  */
-export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, host: AgoraHostValues): {
+export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, rawHost: AgoraHostValues): {
     env: Record<string, string>;
     missing: string[];
 };