@wtfalch/foundry 0.34.0 → 0.35.2

package/dist/bootstrap/bootstrap.d.ts

@@ -47,7 +47,7 @@ export interface BootstrapCompanyDeps {
     readers: LiveReaders;
     executor: StepExecutor;
     /** The same flags `FoundryPlanApply` takes: a step whose port the host did not build is reported blocked. */
-    options?: Pick<FoundryPlanApplyOptions, 'ownerInviteMail' | 'broker'>;
+    options?: Pick<FoundryPlanApplyOptions, 'ownerInviteMail' | 'broker' | 'ownServices'>;
 }
 export interface BootstrapPlatformDeps {
     /** Foundry's tables live here, already migrated by the host; the store, the audit log and the plan all use it. */

package/dist/bootstrap/bootstrap.js

@@ -59,13 +59,18 @@ function allowBootstrapApply(withCompany) {
     };
 }
 /**
- * The org steps phase two applies: the sign-in org and its domain, the owner
+ * The org steps phase two applies: the owner's own sign-in server and its zone,
+ * the sign-in org and its domain, the owner
  * (whose user id Boule's `AUTHZ_FIRST_OWNER` carries), Boule's sign-in client,
  * and Boule with its database. Everything else the company declares (chat,
  * mail, Boule's broker entry, which waits for the org's mail domain, ...) is
  * for a later, ordinary org apply.
  */
 const COMPANY_SLICE_STEPS = new Set([
+    // The owner's own sign-in server, before anyone can sign in. Own mail, files,
+    // jobs and sfu follow after sign-in, as for every company.
+    'cloudflare:zone',
+    'coolify:own-auth',
     'zitadel:issuer',
     'zitadel:registration-closed',
     'zitadel:domain',
@@ -77,8 +82,10 @@ const companySliceOnly = {
     step: (action) => COMPANY_SLICE_STEPS.has(`${action.system}:${action.kind}`) ||
         COMPANY_SLICE_STEPS.has(`${action.system}:${action.kind}:${action.key}`),
     // `coolify:boule:mail` only says Boule runs without mail for now.
-    blocked: (key) => key !== 'coolify:boule:mail' &&
-        [...COMPANY_SLICE_STEPS].some((step) => key === step || key.startsWith(`${step}:`)),
+    // `own-auth` is the unmanaged key `planOwnAuth` uses for a blocked sign-in server.
+    blocked: (key) => key === 'own-auth' ||
+        (key !== 'coolify:boule:mail' &&
+            [...COMPANY_SLICE_STEPS].some((step) => key === step || key.startsWith(`${step}:`))),
 };
 /** Shown instead of a phase-two error that could carry a value; the failing step's own name and redacted text are in `failed`. */
 const COMPANY_NOT_FINISHED = "the company's own slice did not finish, so Archon has no people-store keys yet; run onboarding again";
@@ -118,6 +125,10 @@ function trackedOrgExecutor(inner, progress, redactor) {
             }
         },
         ...(inner.ownEdgePorts ? { ownEdgePorts: () => inner.ownEdgePorts?.() ?? {} } : {}),
+        // The own sign-in step plans without a held Lettermint key only when the executor can mint one.
+        ...(inner.ownMailKeyMintable
+            ? { ownMailKeyMintable: () => inner.ownMailKeyMintable?.() ?? false }
+            : {}),
     };
 }
 /** The audit log with every free-text field run through the redactor before it is stored. */
@@ -334,10 +345,14 @@ export async function bootstrapPlatform(input, deps) {
                 return result;
             },
             ...(inner.blockedSteps
-                ? { blockedSteps: (platform, ids) => inner.blockedSteps?.(platform, ids) ?? {} }
+                ? {
+                    blockedSteps: (platform, ids, owner) => inner.blockedSteps?.(platform, ids, owner) ?? {},
+                }
                 : {}),
             ...(inner.driftedSteps
-                ? { driftedSteps: (platform, ids) => inner.driftedSteps?.(platform, ids) ?? {} }
+                ? {
+                    driftedSteps: (platform, ids, owner) => inner.driftedSteps?.(platform, ids, owner) ?? {},
+                }
                 : {}),
         };
         let orgProgress = { started: 0, completed: 0 };
@@ -392,10 +407,11 @@ export async function bootstrapPlatform(input, deps) {
         const blockedRaw = (driven.failed ? [] : (driven.lastPlan?.unmanaged ?? []))
             .filter((item) => item.key !== undefined)
             .map((item) => ({ step: item.key, message: item.description }));
+        const platformBlockedCount = blockedRaw.length;
         if (companyDeps && !failed) {
             // Phase two: the platform's own org. Its Boule needs the platform's
             // sign-in, and Archon's people-store keys need that Boule.
-            const company = await driveApply({
+            const driveCompany = (label) => driveApply({
                 plan: () => planApply.plan(COMPANY_INCLUDED_ORG_ID),
                 apply: (plan, stepProgress) => {
                     orgProgress = stepProgress;
@@ -406,27 +422,30 @@ export async function bootstrapPlatform(input, deps) {
                     phase: 'plan',
                     system: roundSystem(plan),
                     round,
-                    message: `company round ${round}: ${plan.steps.length} step(s) planned`,
+                    message: `${label}company round ${round}: ${plan.steps.length} step(s) planned`,
                     steps: plan.steps.map((s) => s.description),
                 }),
                 onApplied: (round, plan) => emit({
                     phase: 'apply',
                     system: roundSystem(plan),
                     round,
-                    message: `company round ${round}: applied`,
+                    message: `${label}company round ${round}: applied`,
                     steps: plan.steps.map((s) => s.description),
                 }),
             });
+            const company = await driveCompany('');
             applied.push(...company.applied);
             if (company.failed) {
                 failed = company.failed;
                 blockedRaw.push({ step: 'company', message: COMPANY_NOT_FINISHED });
             }
             else {
+                const companyBlockedStart = blockedRaw.length;
                 for (const item of company.lastPlan?.unmanaged ?? []) {
                     if (item.key !== undefined)
                         blockedRaw.push({ step: item.key, message: item.description });
                 }
+                const companyBlockedCount = blockedRaw.length - companyBlockedStart;
                 // Boule's broker entry needs the org's mail domain, which only the org's mail step
                 // records, so it is outside this slice. Until it is applied nobody can sign in to Boule:
                 // say so, and never report the onboarding complete.
@@ -444,12 +463,31 @@ export async function bootstrapPlatform(input, deps) {
                 failed = again.failed;
                 lastPlan = again.lastPlan;
                 if (!again.failed) {
-                    for (const item of again.lastPlan?.unmanaged ?? []) {
-                        if (item.key !== undefined && !blockedRaw.some((b) => b.step === item.key)) {
-                            blockedRaw.push({ step: item.key, message: item.description });
+                    // Archon's registration put the first entry on the owner's broker. Only now can the
+                    // owner's sign-in mint its login client and start that broker, so its plan runs once more.
+                    const signIn = await driveCompany('after Archon: ');
+                    applied.push(...signIn.applied);
+                    if (signIn.failed) {
+                        failed = signIn.failed;
+                        blockedRaw.push({ step: 'company', message: COMPANY_NOT_FINISHED });
+                    }
+                    else {
+                        const fresh = [];
+                        for (const item of signIn.lastPlan?.unmanaged ?? []) {
+                            if (item.key !== undefined)
+                                fresh.push({ step: item.key, message: item.description });
                         }
+                        blockedRaw.splice(companyBlockedStart, companyBlockedCount, ...fresh);
                     }
                 }
+                if (!failed) {
+                    // Archon was blocked on the owner's sign-in in phase one; this plan is the current truth.
+                    blockedRaw.splice(0, platformBlockedCount);
+                    const platformBlocked = (again.lastPlan?.unmanaged ?? [])
+                        .filter((item) => item.key !== undefined)
+                        .map((item) => ({ step: item.key, message: item.description }));
+                    blockedRaw.unshift(...platformBlocked);
+                }
             }
         }
         const blocked = blockedRaw.map((item) => ({

package/dist/bootstrap/declare.d.ts

@@ -38,6 +38,11 @@ export interface BootstrapCompany {
     name: string;
     slug: string;
     apex: string;
+    /**
+     * The owner company's own domain: absent means `apex`, `null` means none (it
+     * then runs on oikos.host). `apex` stays the platform's.
+     */
+    domain?: string | null;
 }
 export interface BootstrapOwner {
     givenName: string;
@@ -54,13 +59,15 @@ export interface BootstrapOwner {
  */
 export declare function ownerIdentity(owner: BootstrapOwner): OwnerIdentity;
 /**
- * Company Included's declared org: the platform's owner, tier 3 on the
- * platform's own apex from the start (#512) -- it runs on that domain with
- * hosted mail, not a level-1 org whose domain gets set by hand afterward.
+ * Company Included's declared org: the platform's owner, a company like any
+ * other (`services.own`: its own sign-in, mail, files and jobs). Tier 3 on the
+ * platform's apex from the start (#512) -- it runs on that domain with
+ * hosted mail, not a level-1 org whose domain gets set by hand afterward --
+ * unless `company.domain` is `null`, which runs it on oikos.host.
  * `issuer`/`calls`/`site` go on the domain too, the same tier-3 defaults
  * archon#388 gives every company declared there. `calls` and `site` stay
- * disabled (calls is not in v1; no site is declared), so `usesDomain` is
- * inert on both until one is switched on. Chat stays off the domain: its
+ * disabled (calls is not in v1; no site is declared). Without a domain
+ * `calls.usesDomain` is off, as `validateCalls` requires. Chat stays off the domain: its
  * re-key onto a per-org homeserver is not built yet (#463). The org's own
  * sign-in still never collides with the shared ZITADEL instance's host --
  * `loginHostnameFor` (#488) falls back to `<slug>-auth.oikos.host` whenever

package/dist/bootstrap/declare.js

@@ -36,10 +36,11 @@ export const DEFAULT_MAIL_IMAGE_TAG = VERSIONS.stalwart;
  */
 export const DEFAULT_HC_IMAGE_TAG = VERSIONS.hc;
 /**
- * Every platform service except `sfu` is enabled, like the other steps: a
- * service whose dependencies the host did not supply is reported blocked,
- * not planned. `sfu` stays off because it needs a held SSH key and host
- * fingerprint, a separate human step (issue 170). `edge` is on because every
+ * Every platform service is enabled except `auth`, `mail`, `files`, `jobs`
+ * and `sfu`: the owner company runs its own copies of those like any
+ * company (`validatePlatform` refuses them on), so the platform keeps only
+ * what no company owns. A service whose dependencies the host did not supply
+ * is reported blocked, not planned. `edge` is on because every
  * platform DNS record is written through it (F4.dns); its own Cloudflare API
  * token is a held key (`cloudflare:edge:apiToken`), and until a human holds
  * it the planner reports edge blocked, and auth, mail and archon with it.
@@ -47,16 +48,23 @@ export const DEFAULT_HC_IMAGE_TAG = VERSIONS.hc;
  * the same as mail and archon.
  */
 const SERVICES_ENABLED_BY_DEFAULT = new Set([
-    'auth',
-    'mail',
-    'files',
     'ai',
-    'jobs',
     'integrations',
     'archon',
     'edge',
     'hc',
 ]);
+/**
+ * The services every company deploys its own copy of. Their platform entries
+ * are off but still carry the release the own steps deploy
+ * (`serviceGitRefsOf`); with an empty one `own-auth` is blocked.
+ */
+const OWN_SERVICE_KEYS = new Set([
+    'auth',
+    'mail',
+    'files',
+    'jobs',
+]);
 /**
  * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the
  * field when one is empty or an address is not an address. The work address
@@ -75,33 +83,36 @@ export function ownerIdentity(owner) {
     return identity;
 }
 /**
- * Company Included's declared org: the platform's owner, tier 3 on the
- * platform's own apex from the start (#512) -- it runs on that domain with
- * hosted mail, not a level-1 org whose domain gets set by hand afterward.
+ * Company Included's declared org: the platform's owner, a company like any
+ * other (`services.own`: its own sign-in, mail, files and jobs). Tier 3 on the
+ * platform's apex from the start (#512) -- it runs on that domain with
+ * hosted mail, not a level-1 org whose domain gets set by hand afterward --
+ * unless `company.domain` is `null`, which runs it on oikos.host.
  * `issuer`/`calls`/`site` go on the domain too, the same tier-3 defaults
  * archon#388 gives every company declared there. `calls` and `site` stay
- * disabled (calls is not in v1; no site is declared), so `usesDomain` is
- * inert on both until one is switched on. Chat stays off the domain: its
+ * disabled (calls is not in v1; no site is declared). Without a domain
+ * `calls.usesDomain` is off, as `validateCalls` requires. Chat stays off the domain: its
  * re-key onto a per-org homeserver is not built yet (#463). The org's own
  * sign-in still never collides with the shared ZITADEL instance's host --
  * `loginHostnameFor` (#488) falls back to `<slug>-auth.oikos.host` whenever
  * `auth.<domain>` would equal the platform's own auth hostname.
  */
 export function declaredCompanyOrg(company, owner) {
+    const domain = company.domain === undefined ? company.apex : company.domain;
     return {
         id: COMPANY_INCLUDED_ORG_ID,
         slug: company.slug,
         displayName: company.name,
-        domain: company.apex,
+        domain,
         mail: {
             mode: 'hosted',
-            usesDomain: true,
+            usesDomain: domain !== null,
             ownerMailboxAddress: null,
             noReplyLocalPart: 'no-reply',
         },
         chat: { enabled: true, usesDomain: false },
-        calls: { enabled: false, usesDomain: true },
-        issuer: { usesDomain: true },
+        calls: { enabled: false, usesDomain: domain !== null },
+        issuer: { usesDomain: domain !== null },
         site: { enabled: false, usesDomain: true },
         hosting: {
             enabled: false,
@@ -119,6 +130,7 @@ export function declaredCompanyOrg(company, owner) {
         buyer: { legalName: null, orgNumber: null, address: null, vatRegistered: null },
         bespokeAppRepo: null,
         adoptedApp: null,
+        services: { own: true },
         owners: [ownerIdentity(owner)],
         test: false,
     };
@@ -134,7 +146,7 @@ export function declaredPlatformFor(apex, serverIpv4) {
         services[key] = {
             enabled,
             hostname: defaultPlatformHostname(key, apex),
-            gitRef: !enabled
+            gitRef: !enabled && !OWN_SERVICE_KEYS.has(key)
                 ? ''
                 : key === 'mail'
                     ? DEFAULT_MAIL_IMAGE_TAG
@@ -148,9 +160,12 @@ export function declaredPlatformFor(apex, serverIpv4) {
         apex,
         ...(serverIpv4 ? { serverIpv4 } : {}),
         ...services,
+        // The platform runs no mail server, but every company's mail goes through the shared relay.
+        mail: { ...services.mail, relay: true },
         // Off, like `sfu`: the pin is an Archon release tag and digest, which exist
         // only after Archon runs. Declared on with no pin, it would be reported
         // blocked and the bootstrap would never be complete.
         uptime: { enabled: false, tag: '', sha256: '' },
+        heartbeatsProvider: 'self-hosted',
     };
 }

package/dist/bootstrap/versions.d.ts

@@ -20,6 +20,24 @@ export interface PinnedVersions {
 }
 export declare function loadVersions(): PinnedVersions;
 export declare const VERSIONS: PinnedVersions;
+/**
+ * The multi-arch index digest of each tag in `versions.json`, in
+ * `versions.digests.json` beside it. Kept apart so every tag comparison
+ * (applied refs, version-change lines) stays on the tag. Validated on read:
+ * a malformed digest, or a key of `versions.json` without one, throws.
+ */
+export declare function loadDigests(): PinnedVersions;
+export declare const DIGESTS: PinnedVersions;
+/**
+ * `<tag>@<digest>` for an image string handed to Coolify or a Dockerfile.
+ * Only the image string uses it; the recorded applied ref stays the tag.
+ */
+export declare function pinnedRef(key: keyof PinnedVersions): string;
+/**
+ * A declared tag that equals the pinned one gets its digest; any other
+ * declared tag (an override) is passed through unchanged.
+ */
+export declare function pinnedTagFor(key: keyof PinnedVersions, tag: string): string;
 /**
  * Why an image tag cannot be used, or `null`. #248: generalised out of what
  * was `platform-providers.ts`'s `mailImageTagBlocked`, the one guard
@@ -28,3 +46,5 @@ export declare const VERSIONS: PinnedVersions;
  * `"ZITADEL"`, `"LiveKit"`, ...); `example` is a real pinned tag to suggest.
  */
 export declare function floatingTagBlocked(label: string, tag: string, example: string): string | null;
+/** {@link floatingTagBlocked} for a git ref: it also refuses `main`, `master` and `HEAD`. */
+export declare function floatingRefBlocked(label: string, ref: string, example: string): string | null;

package/dist/bootstrap/versions.js

@@ -10,6 +10,43 @@ export function loadVersions() {
     return JSON.parse(readFileSync(VERSIONS_PATH, 'utf8'));
 }
 export const VERSIONS = loadVersions();
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const DIGESTS_PATH = new URL('../../versions.digests.json', import.meta.url);
+/**
+ * The multi-arch index digest of each tag in `versions.json`, in
+ * `versions.digests.json` beside it. Kept apart so every tag comparison
+ * (applied refs, version-change lines) stays on the tag. Validated on read:
+ * a malformed digest, or a key of `versions.json` without one, throws.
+ */
+export function loadDigests() {
+    const raw = JSON.parse(readFileSync(DIGESTS_PATH, 'utf8'));
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('versions.digests.json must be a JSON object');
+    }
+    const record = raw;
+    for (const key of Object.keys(loadVersions())) {
+        const value = record[key];
+        if (typeof value !== 'string' || !DIGEST_PATTERN.test(value)) {
+            throw new Error(`versions.digests.json: "${key}" must be a sha256:<64 hex> digest`);
+        }
+    }
+    return record;
+}
+export const DIGESTS = loadDigests();
+/**
+ * `<tag>@<digest>` for an image string handed to Coolify or a Dockerfile.
+ * Only the image string uses it; the recorded applied ref stays the tag.
+ */
+export function pinnedRef(key) {
+    return `${VERSIONS[key]}@${DIGESTS[key]}`;
+}
+/**
+ * A declared tag that equals the pinned one gets its digest; any other
+ * declared tag (an override) is passed through unchanged.
+ */
+export function pinnedTagFor(key, tag) {
+    return tag === VERSIONS[key] ? pinnedRef(key) : tag;
+}
 /**
  * Tag spellings that resolve to whatever the registry currently has, not a
  * fixed image -- a re-apply of the same declaration can silently run a
@@ -41,3 +78,12 @@ export function floatingTagBlocked(label, tag, example) {
     }
     return null;
 }
+/** Branch names that move, refused for a git ref on top of the floating image tags. */
+const FLOATING_GIT_REFS = new Set(['main', 'master', 'head']);
+/** {@link floatingTagBlocked} for a git ref: it also refuses `main`, `master` and `HEAD`. */
+export function floatingRefBlocked(label, ref, example) {
+    if (FLOATING_GIT_REFS.has(ref.trim().toLowerCase())) {
+        return `the ${label} image tag "${ref}" floats; declare a pinned release (for example ${example})`;
+    }
+    return floatingTagBlocked(label, ref, example);
+}

package/dist/calls-sfu.js

@@ -52,7 +52,7 @@
  * `calls-sfu-deploy-support.ts`'s `fileWriteMode`), never logged, scrubbed
  * from any error `calls-sfu-deploy.mjs` prints.
  */
-import { VERSIONS } from './bootstrap/versions.js';
+import { VERSIONS, pinnedRef } from './bootstrap/versions.js';
 import { SFU_SLOT_MAX } from './org.js';
 // ---------------------------------------------------------------------------
 // The guard
@@ -214,7 +214,7 @@ const CLOUDFLARED_METRICS_ADDRESS = '127.0.0.1:20241';
 export function dockerComposeYaml() {
     return `services:
   livekit:
-    image: ${LIVEKIT_IMAGE_REF}
+    image: livekit/livekit-server:${pinnedRef('livekit')}
     restart: unless-stopped
     network_mode: host
     volumes:
@@ -227,7 +227,7 @@ export function dockerComposeYaml() {
       retries: 3
       start_period: 30s
   cloudflared:
-    image: ${CLOUDFLARED_IMAGE_REF}
+    image: cloudflare/cloudflared:${pinnedRef('cloudflared')}
     restart: unless-stopped
     network_mode: host
     env_file:

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, } from './org.js';
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateSite, } from './org.js';
-export type { DeclaredPlatform, PlatformService, PlatformServiceKey, PlatformSfuService, } from './platform.js';
-export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceSchema, ServicesConfig, VersionPin, VersionPinPart, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
+export type { DeclaredPlatform, PlatformService, PlatformServiceKey, PlatformSfuService, HeartbeatsProvider, } from './platform.js';
+export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 import { type PinnedVersions } from './bootstrap/versions.js';
 export type { PinnedVersions };
 export declare const PINNED_VERSIONS: Readonly<PinnedVersions>;
@@ -19,7 +19,10 @@ export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, 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, StepSystem, PlanDetail, OrgPostgresPlan, PlatformPlanDetail, MailRoute, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, FoundryApplyOptions, UnconfirmedUpgrade, } from './plan/index.js';
+export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
+export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
+export type { BackupGatePorts } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
 export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, DnsPort, EdgePlatformAccess, EdgePlatformDns, EdgePlatformRateLimits, EdgePlatformWorkers, EdgePlatformZones, EdgeZonesOptions, ZonePort, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, EdgeWorkersOptions, EdgePlatformTunnels, TunnelPort, } from './plan/index.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, 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, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
@@ -35,6 +38,8 @@ export type { PlanOwnSfuOptions, SfuAppDeps, SfuAppInput } from './plan/index.js
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuPortsMappings, } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
+export { NO_DOMAIN_ZONE, ownHostnames } from './plan/index.js';
+export type { OwnHostnames } from './plan/index.js';
 export type { EnsureSignInOrgOptions } from './plan/index.js';
 export { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ensureSignInOrg, registerSignInDomain, signInOrgDomain, } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateSite, } from './org.js';
-export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateVersionPin, validateSite, } from './org.js';
+export { PLATFORM_SERVICE_KEYS, HEARTBEATS_PROVIDERS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 // archon#273: the pinned platform service versions the planner deploys, so a
 // host can show declared against running. Readonly: it is the planner's own
 // object, not a copy.
@@ -11,7 +11,9 @@ export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
+export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
+export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, 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, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './plan/index.js';
@@ -20,6 +22,7 @@ export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICE
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, provisionFilesHost, provisionJobsHost, provisionMailServer, } from './plan/index.js';
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuPortsMappings, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
+export { NO_DOMAIN_ZONE, ownHostnames } from './plan/index.js';
 export { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ensureSignInOrg, registerSignInDomain, signInOrgDomain, } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
 export { healthTargets, platformHealthTargets } from './plan/index.js';

package/dist/migrations/0053_heartbeats_provider.sql

@@ -0,0 +1,9 @@
+-- @wtfalch/foundry: foundry#544 -- which Healthchecks instance manages the
+-- platform's heartbeat checks, decoupled from whether foundry also deploys
+-- its own self-hosted server (`hc_enabled`, foundry#540). 'self-hosted' is
+-- the default and today's only behaviour; 'hosted' needs no self-hosted
+-- server applied at all. Mirrors `src/store/schema.ts`'s
+-- `foundryDeclaredPlatform` table addition.
+
+alter table foundry_declared_platform
+  add column if not exists heartbeats_provider text not null default 'self-hosted';

package/dist/migrations/0053_org_version_pin.sql

@@ -0,0 +1,6 @@
+-- @wtfalch/foundry: a company's version hold. `version_pin` is a json object of
+-- part to git ref or image tag (auth, mail, files, jobs, sfu, calls); null
+-- follows the platform. Additive. Mirrors src/store/schema.ts's `declaredOrgs`.
+
+alter table foundry_declared_orgs
+  add column if not exists version_pin jsonb;

package/dist/org.d.ts

@@ -316,7 +316,14 @@ export interface HostingEntry {
     hostnames: string[];
     /** A Postgres database beside the app. At most one entry per org. */
     database: boolean;
-    /** Deploy on every push to `branch`. Default: `true`. */
+    /**
+     * The Linux capabilities of the entry's app container. Absent or `'restricted'`: all dropped, then only the
+     * few a web server or node entrypoint needs added back. `'standard'`: Docker's defaults minus raw sockets,
+     * device nodes, file capabilities, chroot and audit writes. A fallback for an image that will not start
+     * restricted.
+     */
+    capabilities?: 'restricted' | 'standard';
+    /** Deploy on every push to `branch`. A host should declare `false`; foundry creates every other app with auto-deploy off. */
     autoDeploy: boolean;
     /**
      * Cloudflare Access gates on this entry's own `hostnames`. Empty means no
@@ -486,13 +493,11 @@ export declare function appEntry(hosting: HostingConfig): HostingEntry | undefin
  * sends from. Each is read from `StepExecutionContext.recordedIds()` in
  * `executor.ts`'s `pushAppEnv`, never minted again there.
  */
-export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret' | 'platformMailKey';
+export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret';
 /**
- * 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.
+ * `sharedSecret` is the one secret source: {@link EnvSharedSecret}. The
+ * platform's Lettermint key is not a source any more (2026-10-11): each
+ * company uses its own mail key.
  */
 export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
 /** The sources whose value is a secret: resolved at apply time, never recorded. */
@@ -516,6 +521,29 @@ export declare function validateHosting(hosting: HostingConfig, names?: {
     locked: ReadonlySet<string>;
 }): string | null;
 export declare function validateDomain(domain: string): string | null;
+/**
+ * A broker entry name foundry writes itself: Archon's, and any company's Boule.
+ * A hosting entry may not declare that it replaces one.
+ */
+export declare function isFoundryOwnedBrokerEntryName(name: string): boolean;
+/**
+ * `null` when `domain` may be claimed by company `orgId`, given the platform's
+ * apex and owner company and every other company's declared domain; otherwise
+ * the reason it may not. The platform's apex and anything under it belong to
+ * the owner company alone, and no company takes a parent or subdomain of
+ * another's, since Cloudflare would resolve both to one zone.
+ */
+export declare function validateDomainClaim(domain: string, claim: {
+    orgId: string;
+    platform: {
+        apex: string;
+        ownerOrgId: string;
+    } | null;
+    others: readonly {
+        id: string;
+        domain: string | null;
+    }[];
+}): string | null;
 /**
  * `null` when `site` is valid; otherwise the reason it is not (#101).
  *
@@ -526,11 +554,9 @@ export declare function validateDomain(domain: string): string | null;
  * and cms there (`site`), never both -- both would otherwise fight over the
  * same hostname (https://github.com/wtfalch/foundry/issues/99).
  *
- * - `site.enabled` requires `domain` to be set -- a site with nowhere to
- *   live is not a site.
- * - `site.enabled` requires `site.usesDomain` -- unlike mail, chat, calls
- *   and the issuer, the site has no meaning anywhere but the org's own
- *   domain, so turning it on always means the domain opt-in too.
+ * - `site.enabled` with a `domain` requires `site.usesDomain`: the site then
+ *   lives on the domain. Without a `domain` it lives on `<slug>.oikos.host`
+ *   and `site.usesDomain` must be off.
  * - `site.enabled` and `hosting.enabled` cannot both be on.
  * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
  *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
@@ -548,7 +574,25 @@ export declare function validateSite(org: DeclaredOrg): string | null;
  * reason to pin at all.
  */
 export declare function validateCalls(org: DeclaredOrg): string | null;
-/** A company with a domain runs its own sign-in, mail, files, jobs and calls SFU in its own containers. */
+/** The parts of a company that can be held on their own version. */
+export declare const VERSION_PIN_PARTS: readonly ["auth", "mail", "files", "jobs", "sfu", "calls"];
+export type VersionPinPart = (typeof VERSION_PIN_PARTS)[number];
+/**
+ * A part held at a git ref (auth, files, jobs) or an image tag (mail, sfu, calls). Absent part: the platform's value.
+ * `calls` is the Synapse tag of the calls stack. It is used when the stack is created; a running stack is not moved
+ * (nothing patches the image tag of an existing app, see the Synapse create in `plan/executor.ts`).
+ */
+export type VersionPin = Partial<Record<VersionPinPart, string>>;
+/**
+ * `versionPin` holds parts of a company on an older release while others move.
+ * Every value is a fixed ref or tag: a floating one would defeat the hold.
+ * Also run on a stored value when it is read, so a bad row is not trusted.
+ */
+export declare function validateVersionPin(org: Pick<DeclaredOrg, 'versionPin'>): string | null;
+/**
+ * Every company runs its own sign-in, mail, files, jobs and calls SFU in its own containers, the platform's owner company too.
+ * A company without a domain runs them on oikos.host.
+ */
 export interface ServicesConfig {
     /** true: own copies of the services. false (default): the platform's shared ones. */
     own: boolean;
@@ -560,7 +604,7 @@ export interface ServicesConfig {
     sfuSlot?: number | null;
 }
 export declare const SFU_SLOT_MAX = 20;
-/** The only reader of `services.own`: an org without `services` runs the platform's shared services. */
+/** The only reader of `services.own`. Every company runs its own services, the platform's owner company too; a company without a domain runs them on oikos.host. */
 export declare function ownsServices(org: Pick<DeclaredOrg, 'services'>): boolean;
 /** The pure part of the `services` rules; that no two orgs share an `sfuSlot` is the store's check. */
 export declare function validateServices(org: DeclaredOrg): string | null;
@@ -840,6 +884,8 @@ export interface DeclaredOrg {
     hosting: HostingConfig;
     /** Absent means `{ own: false }`. Optional so every existing literal and test fixture compiles unchanged, as `calls.versionPin` and `MailConfig.mailApps` do. */
     services?: ServicesConfig;
+    /** Parts of this company held on their own version. Absent or null follows the platform. Ignored for the owner company. */
+    versionPin?: VersionPin | null;
     sso: SsoConfig;
     guests: GuestsConfig;
     solo: SoloConfig;