@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/org.js

@@ -1,3 +1,4 @@
+import { floatingTagBlocked } from './bootstrap/versions.js';
 /** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
 export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
 /** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
@@ -39,11 +40,27 @@ export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 export function appEntry(hosting) {
     return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
 }
+/**
+ * Two sources are secrets. `sharedSecret` is {@link EnvSharedSecret}.
+ * `platformMailKey` is the platform's held Lettermint key, handed over as the
+ * value of the declared env name (the platform's own apps call it
+ * `LETTERMINT_API_TOKEN`). Any hosting entry of any customer org may name it
+ * (William, 2026-10-04): mail is Lettermint, and the key is the platform's.
+ */
 export const APP_ENV_SOURCES = new Set([
     'filesOrganisationId',
     'aiOrganisationId',
     'mailDomain',
+    'sharedSecret',
+    'platformMailKey',
 ]);
+/** The sources whose value is a secret: resolved at apply time, never recorded. */
+export const SECRET_APP_ENV_SOURCES = new Set([
+    'sharedSecret',
+    'platformMailKey',
+]);
+/** The held-key ref of an org's shared secret. */
+export const sharedSecretRef = (orgId, name) => `foundry:shared-secret:${orgId}:${name}`;
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -267,6 +284,9 @@ function validateHostingEntry(entry, enabled) {
             if (!APP_ENV_SOURCES.has(value?.from)) {
                 return `${at} env '${name}' has an unknown source '${value?.from}'`;
             }
+            if (value.from === 'sharedSecret' && !ENTRY_KEY.test(value.name ?? '')) {
+                return `${at} env '${name}' sharedSecret needs a name (lowercase letters, digits and hyphens)`;
+            }
         }
         else if (SECRET_ENV_NAME.test(name) || (name.endsWith('_URL') && urlHasPassword(value))) {
             return `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`;
@@ -464,6 +484,9 @@ export function validateDomain(domain) {
  * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
  *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
  *   `zitadel:app:cms` key, and the two would overwrite each other.
+ * - `site.repo`, if set, must be a repo under `wtfalch` (#245), the same
+ *   `REPO` rule {@link validateHostingEntry} already holds `HostingEntry.repo`
+ *   to.
  */
 export function validateSite(org) {
     if (org.site.enabled && !org.domain) {
@@ -478,6 +501,32 @@ export function validateSite(org) {
     if (org.site.enabled && org.hosting.issuerApps.some((app) => app.name === 'cms')) {
         return "site.enabled reserves the issuerApps name 'cms'";
     }
+    if (org.site.repo != null && !REPO.test(org.site.repo)) {
+        return 'site.repo must be a repo under wtfalch, or null';
+    }
+    return null;
+}
+/**
+ * #259: `calls.versionPin` holds this org's calls Matrix stack on an older
+ * release during an ordered rollout. A pin is a tag, held to the same
+ * "no floating tag" rule the pinned releases in `versions.json` already
+ * follow ({@link floatingTagBlocked}) -- a pin that floats would defeat the
+ * reason to pin at all.
+ */
+export function validateCalls(org) {
+    const pin = org.calls.versionPin;
+    if (!pin)
+        return null;
+    if (pin.synapse !== undefined) {
+        const blocked = floatingTagBlocked('Synapse', pin.synapse, 'v1.161.0');
+        if (blocked)
+            return `calls.versionPin ${blocked}`;
+    }
+    if (pin.mas !== undefined) {
+        const blocked = floatingTagBlocked('matrix-authentication-service', pin.mas, '1.24.0');
+        if (blocked)
+            return `calls.versionPin ${blocked}`;
+    }
     return null;
 }
 const ORG_NUMBER_PATTERN = /^\d{9}$/;
@@ -636,9 +685,21 @@ function validateOwnerMailboxes(org) {
  * two rules `validateHosting` already applies to `issuerApps`' names, for
  * the same reason: a duplicate or blank entry can never mean anything
  * different from leaving it out.
+ *
+ * A domain plus `mail.mode === 'received'` is tier 2 (own domain, MX stays
+ * at Google or Microsoft), which William dropped on 2026-10-04 (#422):
+ * only tier 1 (no domain) and tier 3 (own domain, `hosted`) are offered.
+ * Refused unless `opts.allowExistingTier2` says this exact combination was
+ * already the stored state before this write -- `store/postgres.ts`'s
+ * `update` passes that for an org already grandfathered into tier 2, so a
+ * patch that does not touch `domain` or `mail.mode` still goes through.
+ * `create` never passes it: a brand new org cannot already be grandfathered.
  */
-export function validateMail(org) {
+export function validateMail(org, opts) {
     const { mail } = org;
+    if (org.domain && mail.mode === 'received' && !opts?.allowExistingTier2) {
+        return `mail.mode 'received' (tier 2, own domain with mail elsewhere) is not offered; use 'hosted' or leave the domain off`;
+    }
     const address = mail.ownerMailboxAddress ?? null;
     if (address !== null) {
         if (!OWNER_EMAIL_PATTERN.test(address)) {

package/dist/plan/adopt.d.ts

@@ -0,0 +1,76 @@
+import type { DeclaredOrg } from '../org.js';
+import type { Plan } from '../plan.js';
+import type { LiveResource } from './live.js';
+/**
+ * Adopt a live app and its database in place (archon#271). The caller names
+ * what already runs in Coolify; foundry reads it, checks it is what it would
+ * have created for the entry, and records the ids so the next plan finds them
+ * instead of planning a create. Nothing here calls Coolify to change anything.
+ *
+ * No redeploy happens at adopt. The next normal plan may still propose
+ * updates to the adopted app (log volume, env push, hostnames, labels) because
+ * foundry's applied markers are absent; applying those redeploys the app. The
+ * host must show that plan to the operator before it is applied.
+ */
+export interface AdoptInput {
+    /** The declared hosting entry (`HostingEntry.key`) that takes the app over. It must have `database: true`. */
+    entryKey: string;
+    /** The Coolify application uuid. */
+    applicationUuid: string;
+    /** The Coolify Postgres database uuid. */
+    databaseUuid: string;
+    /** The Coolify project both live in. Optional when the org already records one. */
+    projectUuid?: string;
+}
+/** What the adopted resources looked like when adopted: the reader's output, never a secret. */
+export interface AdoptSnapshot {
+    adoptedAt: string;
+    projectUuid: string;
+    /** True when adopt recorded `coolify_project` itself, so release takes it out again. */
+    projectRecorded: boolean;
+    application: {
+        uuid: string;
+        config: Record<string, unknown>;
+    };
+    database: {
+        uuid: string;
+        config: Record<string, unknown>;
+    };
+}
+/** The flat scope key (no `:`) holding an entry's {@link AdoptSnapshot} as JSON. Its presence means "adopted". */
+export declare function adoptedScopeKey(entryKey: string): string;
+/** `null` when absent, or when it is not a snapshot (callers that delete must treat the latter as an error: see {@link adoptedKeysUnreadable}). */
+export declare function parseAdoptSnapshot(raw: string | undefined): AdoptSnapshot | null;
+/** The `adopted.<entry>` keys of `serviceIds` whose value is not a readable snapshot. */
+export declare function adoptedKeysUnreadable(serviceIds: Readonly<Record<string, string>>): string[];
+export declare function snapshotConfig(config: Record<string, unknown>): Record<string, unknown>;
+export declare class AdoptRefusedError extends Error {
+    readonly reasons: string[];
+    constructor(reasons: string[]);
+}
+export interface AdoptPlan {
+    plan: Plan;
+    /** Empty when the live resources match the entry. A non-empty list refuses `adopt` and the plan has no steps. */
+    mismatches: string[];
+    /** What `adopt` would record; absent with mismatches. */
+    snapshot?: AdoptSnapshot;
+}
+/** A live app or database in the project that this org has not recorded, for Archon's "Live, not theirs". */
+export interface AdoptCandidate {
+    kind: 'application' | 'database';
+    uuid: string;
+    name: string;
+    status?: string;
+    /** True when its name is the one foundry would have given it for the entry. */
+    matchesName: boolean;
+}
+/** Live applications and databases in the project that no recorded id of this org names. */
+export declare function adoptCandidates(org: DeclaredOrg, entryKey: string, recordedIds: Readonly<Record<string, string>>, live: readonly LiveResource[]): AdoptCandidate[];
+/**
+ * Checks `input` against the declaration, the recorded ids and the live
+ * resources of the project, and builds the plan steps. `live` is the reader's
+ * output for the project (`null` when the reader cannot read a project).
+ */
+export declare function planAdoptFrom(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, input: AdoptInput, live: readonly LiveResource[] | null, now: Date, 
+/** What another org already records among the three uuids, one reason each (`FoundryPlanApply.computeAdopt`). */
+claimedElsewhere?: readonly string[]): AdoptPlan;

package/dist/plan/adopt.js

@@ -0,0 +1,184 @@
+import { appNameFor, appStepKey } from './platform-diff.js';
+import { withStepSystem } from './step-system.js';
+/** The flat scope key (no `:`) holding an entry's {@link AdoptSnapshot} as JSON. Its presence means "adopted". */
+export function adoptedScopeKey(entryKey) {
+    return `adopted.${entryKey}`;
+}
+/** `null` when absent, or when it is not a snapshot (callers that delete must treat the latter as an error: see {@link adoptedKeysUnreadable}). */
+export function parseAdoptSnapshot(raw) {
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        return typeof v?.application?.uuid === 'string' && typeof v?.database?.uuid === 'string'
+            ? v
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The `adopted.<entry>` keys of `serviceIds` whose value is not a readable snapshot. */
+export function adoptedKeysUnreadable(serviceIds) {
+    return Object.entries(serviceIds)
+        .filter(([k, v]) => k.startsWith('adopted.') && parseAdoptSnapshot(v) === null)
+        .map(([k]) => k);
+}
+/** The only reader fields a snapshot keeps, and only as plain values: never an env value, password or URL with a credential. */
+const SNAPSHOT_FIELDS = [
+    'name',
+    'status',
+    'fqdn',
+    'image',
+    'docker_registry_image_name',
+    'git_repository',
+    'git_branch',
+    'is_auto_deploy_enabled',
+    'environment_id',
+    'server',
+    'server_uuid',
+    'destination',
+    'destination_uuid',
+];
+export function snapshotConfig(config) {
+    const out = {};
+    for (const field of SNAPSHOT_FIELDS) {
+        const v = config[field];
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+            out[field] = v;
+    }
+    return out;
+}
+export class AdoptRefusedError extends Error {
+    reasons;
+    constructor(reasons) {
+        super(`adopt refused: ${reasons.join('; ')}`);
+        this.reasons = reasons;
+        this.name = 'AdoptRefusedError';
+    }
+}
+function databaseNameFor(org) {
+    return `${org.slug}-db`;
+}
+function nameOf(r) {
+    return typeof r.config.name === 'string' ? r.config.name : '';
+}
+/** Live applications and databases in the project that no recorded id of this org names. */
+export function adoptCandidates(org, entryKey, recordedIds, live) {
+    const entry = org.hosting.entries.find((e) => e.key === entryKey);
+    const taken = new Set(Object.values(recordedIds));
+    const out = [];
+    for (const r of live) {
+        if ((r.kind !== 'application' && r.kind !== 'database') || taken.has(r.key))
+            continue;
+        const want = r.kind === 'application' ? (entry ? appNameFor(org, entry) : null) : databaseNameFor(org);
+        out.push({
+            kind: r.kind,
+            uuid: r.key,
+            name: nameOf(r),
+            ...(typeof r.config.status === 'string' ? { status: r.config.status } : {}),
+            matchesName: want !== null && nameOf(r) === want,
+        });
+    }
+    return out;
+}
+/**
+ * Checks `input` against the declaration, the recorded ids and the live
+ * resources of the project, and builds the plan steps. `live` is the reader's
+ * output for the project (`null` when the reader cannot read a project).
+ */
+export function planAdoptFrom(org, recordedIds, input, live, now, 
+/** What another org already records among the three uuids, one reason each (`FoundryPlanApply.computeAdopt`). */
+claimedElsewhere = []) {
+    const mismatches = [...claimedElsewhere];
+    const entry = org.hosting.enabled
+        ? org.hosting.entries.find((e) => e.key === input.entryKey)
+        : undefined;
+    if (!entry)
+        mismatches.push(`${org.slug} declares no hosting entry ${input.entryKey}`);
+    else if (!entry.database) {
+        mismatches.push(`entry ${input.entryKey} declares no database, so there is none to adopt`);
+    }
+    const appKey = `coolify:app:${appStepKey(org, input.entryKey)}`;
+    const dbKey = `coolify:database:${org.id}`;
+    if (recordedIds[appKey] || recordedIds[dbKey] || recordedIds[adoptedScopeKey(input.entryKey)]) {
+        mismatches.push(`entry ${input.entryKey} is already applied (ids are recorded); release it first or let apply manage it`);
+    }
+    const recordedProject = recordedIds.coolify_project;
+    const projectUuid = input.projectUuid ?? recordedProject;
+    if (!projectUuid)
+        mismatches.push('no Coolify project: name projectUuid');
+    else if (recordedProject && recordedProject !== projectUuid) {
+        mismatches.push(`project ${projectUuid} is not the org's recorded project ${recordedProject}`);
+    }
+    let app;
+    let db;
+    if (projectUuid && live === null) {
+        mismatches.push('the Coolify reader cannot read a project, so nothing can be verified');
+    }
+    else if (projectUuid && live) {
+        app = live.find((r) => r.kind === 'application' && r.key === input.applicationUuid);
+        db = live.find((r) => r.kind === 'database' && r.key === input.databaseUuid);
+        if (!app) {
+            mismatches.push(`application ${input.applicationUuid} is not in project ${projectUuid}`);
+        }
+        else if (entry && nameOf(app) !== appNameFor(org, entry)) {
+            mismatches.push(`application is named ${nameOf(app)}, foundry would name it ${appNameFor(org, entry)}`);
+        }
+        if (!db) {
+            mismatches.push(`database ${input.databaseUuid} is not in project ${projectUuid}`);
+        }
+        else if (nameOf(db) !== databaseNameFor(org)) {
+            mismatches.push(`database is named ${nameOf(db)}, foundry would name it ${databaseNameFor(org)}`);
+        }
+    }
+    if (mismatches.length > 0 || !app || !db || !projectUuid) {
+        return {
+            plan: {
+                orgId: org.id,
+                steps: [],
+                unmanaged: mismatches.map((description) => ({ description, key: 'adopt:mismatch' })),
+            },
+            mismatches,
+        };
+    }
+    const drafts = [
+        {
+            action: {
+                system: 'coolify',
+                kind: 'adopt-app',
+                key: appStepKey(org, input.entryKey),
+                desired: { applicationUuid: input.applicationUuid },
+            },
+            step: {
+                description: `adopt ${org.slug}'s ${input.entryKey} app (Coolify ${input.applicationUuid}) in place: record it, no redeploy`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        {
+            action: {
+                system: 'coolify',
+                kind: 'adopt-database',
+                key: org.id,
+                desired: { databaseUuid: input.databaseUuid },
+            },
+            step: {
+                description: `adopt ${org.slug}'s database (Coolify ${input.databaseUuid}) in place: record it, no restart`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+    ];
+    return {
+        plan: { orgId: org.id, steps: drafts.map((d) => withStepSystem(d).step), unmanaged: [] },
+        mismatches,
+        snapshot: {
+            adoptedAt: now.toISOString(),
+            projectUuid,
+            projectRecorded: recordedProject === undefined,
+            application: { uuid: app.key, config: snapshotConfig(app.config) },
+            database: { uuid: db.key, config: snapshotConfig(db.config) },
+        },
+    };
+}

package/dist/plan/agora.d.ts

@@ -183,3 +183,24 @@ export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Rec
 };
 /** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
 export declare function agoraEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+/**
+ * #442: recorded once a restart has confirmed the org's live Agora process
+ * actually serves {@link agoraEnvRevision}'s digest of the env the executor
+ * last wrote -- distinct from Coolify's own env store, which `bulkUpsertEnvs`
+ * always leaves matching desired the moment the write succeeds, whether or
+ * not the running container was ever restarted onto it. Before this, a plan
+ * comparing only the live Coolify env (`agoraEnvDrift` above) could read a
+ * step as converged the instant the env was written, so a crash between that
+ * write and the restart -- or simply never restarting at all -- left the
+ * running process on the old config forever, with nothing left to replan
+ * against (#442's own probe: "one env write, zero restarts, zero deploys").
+ */
+export declare const AGORA_ACTIVATED_ENV_SCOPE_KEY = "coolify_agora_activated_env";
+/**
+ * A stable digest of `env`, for comparison against what was last recorded
+ * under {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}. `AGORA_CONFIG` is compared by
+ * its parsed structure rather than its raw string, the same rule
+ * {@link agoraEnvDrift}'s own `sameEnvValue` follows, so a cosmetic key-order
+ * difference in that JSON never forces a spurious restart.
+ */
+export declare function agoraEnvRevision(env: Readonly<Record<string, string>>): string;

package/dist/plan/agora.js

@@ -1,4 +1,5 @@
 import { chatUpstreams } from './chat-matrix.js';
+import { FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY } from './core-files.js';
 /**
  * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's Agora -- the hostname, the values the host
@@ -218,6 +219,13 @@ export function desiredAgoraEnv(org, recorded, rawHost) {
     if (!clientId)
         missing.push('clientId');
     missing.push(...agoraHostMissing(host));
+    // #437: the core Files audience and the core collection
+    // (`core-files.ts`), both optional on `Agora` itself (`agoras.ts`) --
+    // unlike `messagingProjectId`, an org whose `files:organisation` step has
+    // not run yet (or not recorded either one) simply gets an Agora with
+    // Files off, never a blocked `AGORA_CONFIG`.
+    const filesProjectId = recorded[ZITADEL_FILES_PROJECT_SCOPE_KEY];
+    const filesCollectionId = recorded[FILES_CORE_COLLECTION_SCOPE_KEY];
     if (missing.length === 0) {
         env.AGORA_CONFIG = JSON.stringify({
             name: org.displayName,
@@ -227,6 +235,8 @@ export function desiredAgoraEnv(org, recorded, rawHost) {
             organisationId: zitadelOrgId,
             mailProjectId: host.mailProjectId,
             messagingProjectId: host.messagingProjectId,
+            ...(filesProjectId ? { filesProjectId } : {}),
+            ...(filesCollectionId ? { filesCollectionId } : {}),
             // Agora hides all chat UI unless this is true.
             chat: { enabled: org.chat.enabled },
             // Agora draws call buttons only when this is true.
@@ -282,3 +292,30 @@ export function agoraEnvDrift(desired, live) {
     })
         .map(([key]) => key);
 }
+/**
+ * #442: recorded once a restart has confirmed the org's live Agora process
+ * actually serves {@link agoraEnvRevision}'s digest of the env the executor
+ * last wrote -- distinct from Coolify's own env store, which `bulkUpsertEnvs`
+ * always leaves matching desired the moment the write succeeds, whether or
+ * not the running container was ever restarted onto it. Before this, a plan
+ * comparing only the live Coolify env (`agoraEnvDrift` above) could read a
+ * step as converged the instant the env was written, so a crash between that
+ * write and the restart -- or simply never restarting at all -- left the
+ * running process on the old config forever, with nothing left to replan
+ * against (#442's own probe: "one env write, zero restarts, zero deploys").
+ */
+export const AGORA_ACTIVATED_ENV_SCOPE_KEY = 'coolify_agora_activated_env';
+/**
+ * A stable digest of `env`, for comparison against what was last recorded
+ * under {@link AGORA_ACTIVATED_ENV_SCOPE_KEY}. `AGORA_CONFIG` is compared by
+ * its parsed structure rather than its raw string, the same rule
+ * {@link agoraEnvDrift}'s own `sameEnvValue` follows, so a cosmetic key-order
+ * difference in that JSON never forces a spurious restart.
+ */
+export function agoraEnvRevision(env) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(env)) {
+        normalized[key] = key === 'AGORA_CONFIG' ? stable(JSON.parse(value)) : value;
+    }
+    return stable(normalized);
+}

package/dist/plan/broker-entries.d.ts

@@ -1,5 +1,5 @@
 import type { DeclaredOrg, HostingEntry } from '../org.js';
-import type { PlatformStore } from '../store.js';
+import type { DeclaredOrgStore, PlatformStore } from '../store.js';
 import type { CoolifyPort } from './executor.js';
 /**
  * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
@@ -71,9 +71,17 @@ export declare class PlatformBrokerPort implements BrokerPort {
     constructor(options: {
         store: Pick<PlatformStore, 'getServiceIds' | 'putServiceIds'>;
         coolify: Pick<CoolifyPort, 'listEnvs' | 'bulkUpsertEnvs' | 'deploy'>;
+        /**
+         * #441: the lease store (the `DeclaredOrgStore`). With it, `recordDeploy`
+         * holds the `platform` lease and fences its write; while another platform
+         * change holds it the record is skipped, and the broker's next deploy
+         * records it. Without it the write is unfenced, as before.
+         */
+        leases?: Pick<DeclaredOrgStore, 'acquireMutationLease' | 'releaseMutationLease'>;
     });
     appId(): Promise<string>;
     listEnvs(): Promise<{
+        uuid?: string;
         key: string;
         value: string;
         is_preview: boolean;

package/dist/plan/broker-entries.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { entryClientIdScopeKey } from './agora.js';
 import { entryHostnames } from './hostnames.js';
 import { PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
@@ -99,11 +100,18 @@ export class PlatformBrokerPort {
         return (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY];
     }
     async recordDeploy(value) {
-        const ids = await this.options.store.getServiceIds();
-        await this.options.store.putServiceIds({
-            ...ids,
-            [PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]: value,
-        });
+        const { leases, store } = this.options;
+        const lease = await leases?.acquireMutationLease('platform', randomUUID(), 60_000);
+        if (lease && !('token' in lease))
+            return;
+        try {
+            const ids = await store.getServiceIds();
+            await store.putServiceIds({ ...ids, [PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]: value }, lease);
+        }
+        finally {
+            if (lease)
+                await leases?.releaseMutationLease(lease).catch(() => undefined);
+        }
     }
 }
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/plan/chat-matrix.d.ts

@@ -62,7 +62,7 @@ export interface ChatSynapseHomeserverInput {
     masHost: string;
     masSharedSecret: string;
 }
-/** `homeserver.yaml`: federation and presence off, MAS for auth, the chat gate module on. */
+/** `homeserver.yaml`: federation off, presence on (stable Synapse features only -- no MSC3026 `busy`, foundry#41), MAS for auth, the chat gate module on. */
 export declare function chatSynapseHomeserverYaml(input: ChatSynapseHomeserverInput): string;
 export interface ChatMasConfigInput {
     orgSlug: string;

package/dist/plan/chat-matrix.js

@@ -43,7 +43,7 @@ export function chatAdminUser(orgSlug) {
     return `@chat-admin:${chatServerName(orgSlug)}`;
 }
 const q = (value) => JSON.stringify(value);
-/** `homeserver.yaml`: federation and presence off, MAS for auth, the chat gate module on. */
+/** `homeserver.yaml`: federation off, presence on (stable Synapse features only -- no MSC3026 `busy`, foundry#41), MAS for auth, the chat gate module on. */
 export function chatSynapseHomeserverYaml(input) {
     return [
         '# Generated by @wtfalch/foundry (executor.ts, coolify:chat). Do not edit',
@@ -77,9 +77,17 @@ export function chatSynapseHomeserverYaml(input) {
         '# An empty list is the recommended way of disabling federation.',
         'federation_domain_whitelist: []',
         '',
-        '# Presence is out of scope for v1 (foundry#41).',
+        // foundry#41, decided 2026-10-01: on for every company, stable Synapse
+        // features only. No `msc3026_enabled` here -- that experimental flag
+        // only gates the wire value `org.matrix.msc3026.busy`, and
+        // `ChatClient.announcePresence` (chat/src/chat/client.ts) only ever
+        // writes `online`/`unavailable`, never `busy`, so this homeserver has
+        // nothing to accept that flag would unlock. `ChatClient`'s `Presence`
+        // type still reads a foreign `busy` off `m.presence` if one ever
+        // arrives; dropping that read path per the same decision is
+        // wtfalch/chat's own follow-up, not this file's.
         'presence:',
-        '  enabled: false',
+        '  enabled: true',
         '',
         'enable_authenticated_media: true',
         'max_upload_size: "50M"',

package/dist/plan/core-files.d.ts

@@ -0,0 +1,25 @@
+/**
+ * #437: the core Files contract every company gets, not only one with a
+ * custom hosting entry declaring `uses.files` -- the one ZITADEL audience
+ * Agora requests to read/browse Files (`agoras.ts`'s `filesProjectId`, the
+ * same `urn:zitadel:iam:org:project:id:<id>:aud` shape `messagingProjectId`
+ * already uses) and the one collection every file Agora itself uploads goes
+ * into (`agoras.ts`'s `filesCollectionId`; Files has no route to list an
+ * organisation's collections and an ordinary member cannot create one, so
+ * this has to exist before Agora ever tries).
+ *
+ * Both are idempotent by name: the ZITADEL project is found-or-created by
+ * `${org.slug}-files` the same way `coolifyChat`'s own messaging project is,
+ * and the collection by `CORE_FILES_COLLECTION_NAME` through
+ * `FilesOrganisationPort.ensureCollection` (SDK `ensureCollection`,
+ * wtfalch/files#127 -- already exposed on the port, no new Files capability
+ * needed). `executor.ts`'s `filesOrganisation` creates both, every apply,
+ * right after the organisation itself -- the same "regardless of whether it
+ * already ran" shape that method's own doc comment already describes.
+ */
+/** The one collection every file Agora uploads through Files goes into, inside the org's own Files organisation (scoped there, so the name needs nothing org-specific). */
+export declare const CORE_FILES_COLLECTION_NAME = "agora";
+/** Recorded id of {@link CORE_FILES_COLLECTION_NAME}, read by `agora.ts`'s `desiredAgoraEnv` as `filesCollectionId`. */
+export declare const FILES_CORE_COLLECTION_SCOPE_KEY = "files_core_collection";
+/** Recorded id of the org's `${org.slug}-files` ZITADEL project, read by `agora.ts`'s `desiredAgoraEnv` as `filesProjectId`. */
+export declare const ZITADEL_FILES_PROJECT_SCOPE_KEY = "zitadel_files_project";

package/dist/plan/core-files.js

@@ -0,0 +1,25 @@
+/**
+ * #437: the core Files contract every company gets, not only one with a
+ * custom hosting entry declaring `uses.files` -- the one ZITADEL audience
+ * Agora requests to read/browse Files (`agoras.ts`'s `filesProjectId`, the
+ * same `urn:zitadel:iam:org:project:id:<id>:aud` shape `messagingProjectId`
+ * already uses) and the one collection every file Agora itself uploads goes
+ * into (`agoras.ts`'s `filesCollectionId`; Files has no route to list an
+ * organisation's collections and an ordinary member cannot create one, so
+ * this has to exist before Agora ever tries).
+ *
+ * Both are idempotent by name: the ZITADEL project is found-or-created by
+ * `${org.slug}-files` the same way `coolifyChat`'s own messaging project is,
+ * and the collection by `CORE_FILES_COLLECTION_NAME` through
+ * `FilesOrganisationPort.ensureCollection` (SDK `ensureCollection`,
+ * wtfalch/files#127 -- already exposed on the port, no new Files capability
+ * needed). `executor.ts`'s `filesOrganisation` creates both, every apply,
+ * right after the organisation itself -- the same "regardless of whether it
+ * already ran" shape that method's own doc comment already describes.
+ */
+/** The one collection every file Agora uploads through Files goes into, inside the org's own Files organisation (scoped there, so the name needs nothing org-specific). */
+export const CORE_FILES_COLLECTION_NAME = 'agora';
+/** Recorded id of {@link CORE_FILES_COLLECTION_NAME}, read by `agora.ts`'s `desiredAgoraEnv` as `filesCollectionId`. */
+export const FILES_CORE_COLLECTION_SCOPE_KEY = 'files_core_collection';
+/** Recorded id of the org's `${org.slug}-files` ZITADEL project, read by `agora.ts`'s `desiredAgoraEnv` as `filesProjectId`. */
+export const ZITADEL_FILES_PROJECT_SCOPE_KEY = 'zitadel_files_project';