@wtfalch/foundry 0.61.0 → 0.63.0

package/dist/bootstrap/declare.js

@@ -53,6 +53,7 @@ const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'archon',
     'edge',
     'hc',
+    'registry',
 ]);
 /**
  * The services every company deploys its own copy of. Their platform entries
@@ -153,7 +154,9 @@ export function declaredPlatformFor(apex, serverIpv4) {
                     ? DEFAULT_MAIL_IMAGE_TAG
                     : key === 'hc'
                         ? DEFAULT_HC_IMAGE_TAG
-                        : DEFAULT_GIT_REF,
+                        : key === 'registry'
+                            ? VERSIONS.registry
+                            : DEFAULT_GIT_REF,
         };
     }
     return {

package/dist/bootstrap/versions.d.ts

@@ -12,6 +12,8 @@ export interface PinnedVersions {
     cloudflared: string;
     stalwart: string;
     hc: string;
+    /** The platform's image registry (`registry:3`, Docker's `distribution`). */
+    registry: string;
     /** The mail relay's base image (an exact Alpine release); Postfix comes from its package repository. */
     alpine: string;
     /** A static busybox, copied into the MAS image so its health check has an HTTP client. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingGithub, BlueGreenConfig, OrgBuiltinApp, BouleApp, OrgRefusal, OrgRefusalCode, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryAuthRoom, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, EntryWorkspace, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingGithub, BlueGreenConfig, OrgBuiltinApp, BouleApp, KosmosApp, OrgRefusal, OrgRefusalCode, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryAuthRoom, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, EntryWorkspace, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
 export { APP_ENTRY_KEY, APPS_DOMAIN, DEFAULT_GATE_LIMIT, MAX_WORKSPACE_TESTERS, isLiveEntry, normalizeTesters, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, isMainEntry, mainEntry, companyGithubFor, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, normalizeHostingRepos, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
 export { refuseOrg } from './refuse-org.js';
 export { workerAppHasBuild } from './worker-app-config.js';
@@ -15,6 +15,8 @@ export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState, DestroyRecord, DestroyStepRecord, } from './state.js';
 export type { PlanStep, UnmanagedItem, PlanNote, Plan, VersionChangeItem } from './plan.js';
+export type { NativeBuildDispatchDeps } from './native-build.js';
+export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, } from './native-build.js';
 export type { AppliedVersion, AppliedVersionsStore, DeclaredOrgStore, HeldLease, MutationLease, PlatformStore, RequestedChangeStore, StaleUpdate, UpdateOptions, } from './store.js';
 export { StaleLeaseError } from './store.js';
 export type { PlanApply, DestroyProgress } from './apply.js';
@@ -23,6 +25,8 @@ export { createPostgresAuditLog } from './store/audit.js';
 export type { Color, ReleaseAction, ReleaseSignal, ReleaseState, WindowState, } from './release/types.js';
 export type { ReleaseStore } from './release/state.js';
 export { readReleaseState, requestReleaseAction } from './release/state.js';
+export type { DeclaredClassRemoval, MigrationCompatibilityInput, MigrationCompatibilityProblem, MigrationCompatibilityResult, } from './release/migration-compatibility.js';
+export { checkMigrationCompatibility } from './release/migration-compatibility.js';
 export { createPostgresReleaseStore } from './store/postgres.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryReleaseRequests, 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';
@@ -36,6 +40,8 @@ export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError
 export type { StageCopyInput, StageCopyPort, StageCopyProduction, StageCopyRunRecord, UndoStageCopyInput, } from './plan/index.js';
 export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
 export type { Runner, StageCopyPortDeps } from './plan/index.js';
+export type { PlatformRegistryDeps, PlatformRegistryRuntime } from './plan/index.js';
+export { PLATFORM_REGISTRY_PULL_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_USER, platformRegistryPushCredential, } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export type { OrgPostgresMigrationConfirmation } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
@@ -55,6 +61,8 @@ export type { PlanOwnSfuOptions, SfuAppDeps, SfuAppInput } from './plan/index.js
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuCompose, } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, KeysRegistrarPort, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
+export type { StageProbePort, ReleasePreviewMembers } from './plan/stage-guards.js';
+export type { StageCopyHostConfig } from './plan/stage-copy-host.js';
 export { NO_DOMAIN_ZONE, entryMachinePaths, ownHostnames, privatePageGateKey, workspaceHost, } from './plan/index.js';
 export type { PrivatePageScope } from './plan/index.js';
 export type { HostedLabelRefusal } from './hosted-label.js';

package/dist/index.js

@@ -10,10 +10,12 @@ export const PINNED_VERSIONS = VERSIONS;
 export { buildJsonSchema, parseBuildJson, BuildJsonError } from './build-json.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
+export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_REF, NATIVE_BUILD_DISPATCH_TIMEOUT_MS, NATIVE_BUILD_KEY_ENV, NATIVE_BUILD_KEY_BYTES, NativeBuildDispatchError, dispatchNativeBuild, } from './native-build.js';
 export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { readReleaseState, requestReleaseAction } from './release/state.js';
+export { checkMigrationCompatibility } from './release/migration-compatibility.js';
 export { createPostgresReleaseStore } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryReleaseRequests, 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';
@@ -22,6 +24,7 @@ export { DumpError, dumpNow } from './plan/index.js';
 export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, stageMailEnv, stageSinkAppName, } from './plan/index.js';
 export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './plan/index.js';
 export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
+export { PLATFORM_REGISTRY_PULL_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_PASSWORD_REF, PLATFORM_REGISTRY_PUSH_USER, platformRegistryPushCredential, } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';

package/dist/migrations/0065_native_build_runs.sql

@@ -0,0 +1,32 @@
+-- @wtfalch/foundry: a company's native app settings and its native build runs (foundry#948, estate
+-- `.plans/2026-10-22-app-shells.md`). Additive, like 0060_hosting_repos.sql and
+-- 0055_release_requests.sql: a column with a default plus a new table, so a row written before this
+-- reads back `[]` and an older reader ignores both. Safe on live rows when the container starts.
+--
+-- foundry#951: Boule owns the native settings, build runs and store keys now (estate#262) -- the
+-- column and the table below are unused by this package's code from here on, but foundry#951 also
+-- establishes that a migration only adds in a release where idle and live share a database, so
+-- neither is dropped here. A later release drops both.
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_native_apps jsonb not null default '[]'::jsonb;
+
+create table if not exists foundry_native_build_runs (
+  id          bigserial primary key,
+  org_id      text not null,
+  app         text not null,
+  state       text not null default 'queued',
+  log         text,
+  created_at  timestamptz not null default now(),
+  updated_at  timestamptz not null default now()
+);
+
+alter table foundry_native_build_runs
+  drop constraint if exists foundry_native_build_runs_state_check;
+alter table foundry_native_build_runs
+  add constraint foundry_native_build_runs_state_check
+    check (state in ('queued', 'building', 'uploaded', 'failed'));
+
+-- Listing one app's runs, and (while foundry still checked it, before foundry#951) the `uploaded` look-up.
+create index if not exists foundry_native_build_runs_app_idx
+  on foundry_native_build_runs (org_id, app, id desc);

package/dist/migrations/0066_org_kosmos.sql

@@ -0,0 +1,10 @@
+-- @wtfalch/foundry: `kosmos_enabled` is `org.kosmos.enabled` (foundry#949): the company's own kosmos is set up
+-- only when it asks. `kosmos_blue_green` is `org.kosmos.blueGreen` ({ steps?, stepHoldMinutes? }, as the other
+-- two built-ins' own columns hold it) -- kept even though kosmos always runs blue/green once enabled, so tuning
+-- its steps needs no new column later. Both default to off. Additive like 0059_org_builtin_blue_green.sql and
+-- 0063_boule_apps.sql: `if not exists`, safe to run at container start on live rows.
+-- Mirrors src/store/schema.ts's `declaredOrgs`.
+
+alter table foundry_declared_orgs
+  add column if not exists kosmos_enabled boolean not null default false,
+  add column if not exists kosmos_blue_green jsonb;

package/dist/migrations/0067_requested_changes_kosmos.sql

@@ -0,0 +1,6 @@
+-- @wtfalch/foundry: a company's Boule can request `kosmos` (turn `org.kosmos.enabled` on or off).
+alter table foundry_requested_changes
+  drop constraint if exists foundry_requested_changes_field_check;
+alter table foundry_requested_changes
+  add constraint foundry_requested_changes_field_check
+    check (field in ('calls', 'customers', 'storageLimit', 'aiLimit', 'domain', 'mailTier', 'app', 'build', 'bouleApps', 'kosmos'));

package/dist/migrations/0068_platform_registry.sql

@@ -0,0 +1,17 @@
+-- @wtfalch/foundry: the platform's image registry (`registry:3`), declared with the rest of the
+-- platform. Mirrors `src/store/schema.ts`'s `foundryDeclaredPlatform` additions. Off for the
+-- platform that already exists: foundry deploys nothing new until it is declared on. Backfills
+-- `registry_hostname` the way `0047_platform_coolify.sql` backfilled `coolify_hostname`: the
+-- column must not be empty (`src/platform.ts`'s `validatePlatform`).
+
+alter table foundry_declared_platform
+  add column if not exists registry_enabled boolean not null default false,
+  add column if not exists registry_hostname text,
+  add column if not exists registry_git_ref text not null default '';
+
+update foundry_declared_platform
+  set registry_hostname = 'registry.' || apex
+  where registry_hostname is null;
+
+alter table foundry_declared_platform
+  alter column registry_hostname set not null;

package/dist/modules/sign-in.js

@@ -55,7 +55,7 @@ export const signIn = {
                 label: 'Who can make an account',
                 kind: 'choice',
                 required: true,
-                default: 'open',
+                default: 'closed',
                 choices: [
                     {
                         value: 'open',

package/dist/native-build.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `wtfalch/shell`'s `build-app.yml`: the one GitHub Actions workflow that
+ * builds and signs a company's native app shell (estate
+ * `.plans/2026-10-22-app-shells.md`). Boule now owns the `NativeAppConfig`,
+ * the build runs and the company's store keys (estate#262, foundry#951);
+ * foundry keeps only two things, both in this file: dispatching the
+ * workflow, and the key Boule presents when it asks the host (Archon) to
+ * dispatch it.
+ *
+ * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
+ * route, not foundry's apply loop. The key itself is minted by
+ * `plan/executor.ts`'s `coolifyBoule` (`ensureNativeBuildKey`), reusing the
+ * same `mintIfAbsent` path every other per-company Boule secret goes
+ * through (foundry#970) -- this file keeps only the env name and the byte
+ * length, not a second mint function (foundry#957 review note 2 and
+ * thermo note 1: the earlier `mintNativeBuildKey` was a third, buggy copy
+ * of that same check).
+ */
+export declare const NATIVE_BUILD_REPO = "wtfalch/shell";
+export declare const NATIVE_BUILD_WORKFLOW_FILE = "build-app.yml";
+export declare const NATIVE_BUILD_WORKFLOW_REF = "main";
+/** Every GitHub call this module makes is cut off after this long. */
+export declare const NATIVE_BUILD_DISPATCH_TIMEOUT_MS = 20000;
+/** A `build-app.yml` dispatch that failed. The text is fixed: it never holds the token or a response body. */
+export declare class NativeBuildDispatchError extends Error {
+    readonly status: number | null;
+    constructor(status: number | null);
+}
+export interface NativeBuildDispatchDeps {
+    /** A GitHub token that may dispatch workflows in {@link NATIVE_BUILD_REPO}. */
+    token: string;
+    /** Global fetch by default; tests give their own. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Dispatches `build-app.yml` with exactly `{ runId, origin }` as its inputs:
+ * `runId` is the run the caller (Archon, behind its own `/api/native/builds`
+ * route) already made, `origin` is the company's Boule address the job
+ * reports its status back to and trades its OIDC token for keys at. Foundry
+ * keeps no run store of its own any more -- Boule does -- so this is the one
+ * thing left for foundry to do with a run: start it.
+ */
+export declare function dispatchNativeBuild(deps: NativeBuildDispatchDeps, run: {
+    runId: string;
+    origin: string;
+}): Promise<void>;
+/** The env name Boule presents this key under, to Archon's native-build route. */
+export declare const NATIVE_BUILD_KEY_ENV = "NATIVE_BUILD_KEY";
+export declare const NATIVE_BUILD_KEY_BYTES = 32;

package/dist/native-build.js

@@ -0,0 +1,72 @@
+/**
+ * `wtfalch/shell`'s `build-app.yml`: the one GitHub Actions workflow that
+ * builds and signs a company's native app shell (estate
+ * `.plans/2026-10-22-app-shells.md`). Boule now owns the `NativeAppConfig`,
+ * the build runs and the company's store keys (estate#262, foundry#951);
+ * foundry keeps only two things, both in this file: dispatching the
+ * workflow, and the key Boule presents when it asks the host (Archon) to
+ * dispatch it.
+ *
+ * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
+ * route, not foundry's apply loop. The key itself is minted by
+ * `plan/executor.ts`'s `coolifyBoule` (`ensureNativeBuildKey`), reusing the
+ * same `mintIfAbsent` path every other per-company Boule secret goes
+ * through (foundry#970) -- this file keeps only the env name and the byte
+ * length, not a second mint function (foundry#957 review note 2 and
+ * thermo note 1: the earlier `mintNativeBuildKey` was a third, buggy copy
+ * of that same check).
+ */
+export const NATIVE_BUILD_REPO = 'wtfalch/shell';
+export const NATIVE_BUILD_WORKFLOW_FILE = 'build-app.yml';
+export const NATIVE_BUILD_WORKFLOW_REF = 'main';
+/** Every GitHub call this module makes is cut off after this long. */
+export const NATIVE_BUILD_DISPATCH_TIMEOUT_MS = 20_000;
+/** A `build-app.yml` dispatch that failed. The text is fixed: it never holds the token or a response body. */
+export class NativeBuildDispatchError extends Error {
+    status;
+    constructor(status) {
+        super(status === null
+            ? `dispatching ${NATIVE_BUILD_WORKFLOW_FILE} did not answer`
+            : `dispatching ${NATIVE_BUILD_WORKFLOW_FILE} failed with status ${status}`);
+        this.status = status;
+        this.name = 'NativeBuildDispatchError';
+    }
+}
+/**
+ * Dispatches `build-app.yml` with exactly `{ runId, origin }` as its inputs:
+ * `runId` is the run the caller (Archon, behind its own `/api/native/builds`
+ * route) already made, `origin` is the company's Boule address the job
+ * reports its status back to and trades its OIDC token for keys at. Foundry
+ * keeps no run store of its own any more -- Boule does -- so this is the one
+ * thing left for foundry to do with a run: start it.
+ */
+export async function dispatchNativeBuild(deps, run) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const timeoutMs = deps.timeoutMs ?? NATIVE_BUILD_DISPATCH_TIMEOUT_MS;
+    let response;
+    try {
+        response = await doFetch(`https://api.github.com/repos/${NATIVE_BUILD_REPO}/actions/workflows/${NATIVE_BUILD_WORKFLOW_FILE}/dispatches`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${deps.token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                ref: NATIVE_BUILD_WORKFLOW_REF,
+                inputs: { runId: run.runId, origin: run.origin },
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        console.error(`native build: dispatch did not answer (${error instanceof Error ? error.name : 'error'})`);
+        throw new NativeBuildDispatchError(null);
+    }
+    if (!response.ok)
+        throw new NativeBuildDispatchError(response.status);
+}
+/** The env name Boule presents this key under, to Archon's native-build route. */
+export const NATIVE_BUILD_KEY_ENV = 'NATIVE_BUILD_KEY';
+export const NATIVE_BUILD_KEY_BYTES = 32;

package/dist/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -484,6 +484,18 @@ export interface BouleApp extends OrgBuiltinApp {
 }
 /** True while the company's Boule runs apps (`org.boule.apps`). */
 export declare const appsOn: (org: Pick<DeclaredOrg, "boule">) => boolean;
+/**
+ * The company's kosmos: its own creative workspace (canvas, libraries, photos, pages) that drives the
+ * frontend of its apps. Unlike Boule and Agora, which every company runs, kosmos is set up only when the
+ * company asks (William, 2026-10-22) -- absent, or `enabled` absent or `false`, plans nothing for it.
+ * `enabled: true` plans its ZITADEL client, its database and its live and idle copies; turning it back off
+ * parks the app but keeps the database, the same rule every other switched-off service follows.
+ */
+export interface KosmosApp extends OrgBuiltinApp {
+    enabled?: boolean;
+}
+/** True while the company's kosmos is turned on (`org.kosmos.enabled`). */
+export declare const kosmosOn: (org: Pick<DeclaredOrg, "kosmos">) => boolean;
 /** The traffic steps (percent to the new color) and the hold at each step. Both default in `plan/blue-green.ts`. */
 export interface BlueGreenConfig {
     /** Ascending, each 1..100, ending at 100. */
@@ -798,8 +810,13 @@ export declare function refuseHosting(hosting: HostingConfig, names?: HostingNam
 export declare function companyGithubFor(hosting: Pick<HostingConfig, 'github'>, repo: string | null): HostingGithub | undefined;
 /** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
 export declare function validateBlueGreen(value: unknown, at: string): string | null;
-/** {@link refuseBlueGreen} for the `blueGreen` of the company's Boule and Agora; the same codes. */
-export declare function refuseBuiltinBlueGreen(org: Pick<DeclaredOrg, 'boule' | 'agora'>): OrgRefusal | null;
+/**
+ * {@link refuseBlueGreen} for the `blueGreen` of the company's Boule, Agora and kosmos; the same codes.
+ * Also refuses an `issuerApps` entry named `kosmos` while kosmos is on -- the same reservation
+ * {@link refuseHosting}'s own loop already gives Agora and Boule, but kosmos is opt-in, so it is checked here
+ * instead, the same way {@link validateSite} reserves `cms` only while `site.enabled` is true.
+ */
+export declare function refuseBuiltinBlueGreen(org: Pick<DeclaredOrg, 'boule' | 'agora' | 'kosmos' | 'hosting'>): OrgRefusal | null;
 /** The env names `uses.repo` writes; `env` may not name them. */
 export declare const REPO_ENTRY_ENV_NAMES: readonly ["GIT_REPO_URL", "GIT_SSH_KEY"];
 /** The env name `uses.customerGrants` writes; `env` may not name it. */
@@ -1226,6 +1243,8 @@ export interface DeclaredOrg {
     boule?: BouleApp;
     /** The company's Agora, a static app: its release moves on hard fails and time only. Absent means no blue/green. */
     agora?: OrgBuiltinApp;
+    /** The company's kosmos. Absent or `enabled: false` means it is not set up (2026-10-22). */
+    kosmos?: KosmosApp;
     /** Absent means `{ enabled: false, signUp: false }`. Optional so every existing literal and fixture compiles unchanged. */
     customers?: CustomersConfig;
     /** Parts of this company held on their own version. Absent or null follows the platform. Ignored for the owner company. */

package/dist/org.js

@@ -33,6 +33,8 @@ export function normalizeTesters(testers) {
 }
 /** True while the company's Boule runs apps (`org.boule.apps`). */
 export const appsOn = (org) => org.boule?.apps === true;
+/** True while the company's kosmos is turned on (`org.kosmos.enabled`). */
+export const kosmosOn = (org) => org.kosmos?.enabled === true;
 /** The most volumes one entry may declare. */
 export const MAX_ENTRY_VOLUMES = 8;
 /** The env names `uses.auth.workspaces` writes; `env` may not name them. */
@@ -763,9 +765,14 @@ function refuseBlueGreen(value, at, path) {
     }
     return null;
 }
-/** {@link refuseBlueGreen} for the `blueGreen` of the company's Boule and Agora; the same codes. */
+/**
+ * {@link refuseBlueGreen} for the `blueGreen` of the company's Boule, Agora and kosmos; the same codes.
+ * Also refuses an `issuerApps` entry named `kosmos` while kosmos is on -- the same reservation
+ * {@link refuseHosting}'s own loop already gives Agora and Boule, but kosmos is opt-in, so it is checked here
+ * instead, the same way {@link validateSite} reserves `cms` only while `site.enabled` is true.
+ */
 export function refuseBuiltinBlueGreen(org) {
-    for (const app of ['boule', 'agora']) {
+    for (const app of ['boule', 'agora', 'kosmos']) {
         const value = org[app];
         if (value === undefined)
             continue;
@@ -781,6 +788,15 @@ export function refuseBuiltinBlueGreen(org) {
                 ? 'boule.apps must be true or false'
                 : `${app} has no apps switch: only the company's Boule runs apps`);
         }
+        const enabled = value.enabled;
+        if (enabled !== undefined && (app !== 'kosmos' || typeof enabled !== 'boolean')) {
+            return refusal('builtin_app_invalid', `${app}.enabled`, app === 'kosmos'
+                ? 'kosmos.enabled must be true or false'
+                : `${app} has no enabled switch: it is always on`);
+        }
+    }
+    if (kosmosOn(org) && org.hosting.issuerApps.some((app) => app.name === 'kosmos')) {
+        return refusal('issuer_app_name_reserved_kosmos', 'hosting.issuerApps.kosmos.name', "kosmos.enabled reserves the issuerApps name 'kosmos'");
     }
     return null;
 }
@@ -899,6 +915,7 @@ function validateEntryAuth(entry, hosting, domain) {
     if (entry.key === 'agora' ||
         entry.key === 'boule' ||
         entry.key === 'cms' ||
+        entry.key === 'kosmos' ||
         hosting.issuerApps.some((app) => app.name === entry.key)) {
         return refusal('client_name_taken', `hosting.entries.${entry.key}.key`, `${at} client name '${entry.key}' is already held by another ZITADEL client`);
     }
@@ -1881,6 +1898,8 @@ function orgServiceSchema(service, schema, legacyKey, split = true) {
 export const ORG_SERVICE_SCHEMAS = [
     orgServiceSchema('Boule', 'boule', () => 'coolify_boule_database'),
     orgServiceSchema('CMS', 'cms', () => 'coolify_cms_database'),
+    // kosmos, like CMS, sits behind its own feature switch (`KosmosApp.enabled`); see `orgServiceSchemaEnabled`.
+    orgServiceSchema('kosmos', 'kosmos', () => 'coolify_kosmos_database'),
     orgServiceSchema("chat's Synapse homeserver", 'chat_synapse', () => 'coolify_chat_synapse_database', false),
     orgServiceSchema("chat's matrix-authentication-service", 'chat_mas', () => 'coolify_chat_mas_database', false),
     orgServiceSchema("chat's own service", 'chat_service', () => 'coolify_chat_service_database'),
@@ -1914,6 +1933,10 @@ export function orgServiceDatabase(org, home) {
             database = underscored(`${org.slug}-cms-db`);
             runtimeRole = 'cms_rt';
             break;
+        case 'kosmos':
+            database = underscored(`${org.slug}-kosmos-db`);
+            runtimeRole = 'kosmos_rt';
+            break;
         case 'chat_service':
             database = 'chat';
             break;

package/dist/plan/agora.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, OrgId } from '../org.js';
+import { type DeclaredOrg, type OrgId } from '../org.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

package/dist/plan/agora.js

@@ -1,5 +1,7 @@
+import { kosmosOn } from '../org.js';
 import { chatUpstreams } from './chat-matrix.js';
 import { FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY } from './core-files.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { SIGN_IN_UPSTREAM_ENV, inAppHostApplied, signInUpstream, staleSignInUpstream, } from './sign-in.js';
 /**
  * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
@@ -307,6 +309,8 @@ export function desiredAgoraEnv(org, recorded, rawHost) {
             chat: { enabled: org.chat.enabled },
             // Agora draws call buttons only when this is true.
             calls: { enabled: org.calls.enabled },
+            // foundry#949: kosmos is opt-in, so Agora is told both whether it is on and where it lives.
+            kosmos: { enabled: kosmosOn(org), url: `https://${kosmosHostnameFor(org)}` },
             // In-app sign-in: Agora reads this at runtime (one image serves every company). Set with `SIGNIN_UPSTREAM`
             // only, so Agora never shows the in-app screen before the login can serve it.
             ...(inAppHostApplied(org, recorded, agoraHostnameFor(org)) ? { signInInApp: true } : {}),

package/dist/plan/archon-blue-green.d.ts

@@ -2,6 +2,7 @@ import { type BlueGreenApplyDeps } from './blue-green-apply.js';
 import { type BlueGreenSubject } from './blue-green.js';
 import type { DeployHealthRuntime } from './deploy-health.js';
 import type { PlatformTunnelPort } from './platform-providers.js';
+import type { StageGuardDeps } from './stage-guards.js';
 export interface ArchonBlueGreenRun {
     subject: BlueGreenSubject;
     /** The owner company's id: the health token's held ref is `sharedSecretRef(ownerOrgId, ...)` like an entry's. */
@@ -42,6 +43,10 @@ export interface ArchonBlueGreenRun {
     sleep: (ms: number) => Promise<void>;
     logDir: string;
     isRunning: (status: string | undefined) => boolean;
+    /** Stage's probe port and Access gate, the same guards an entry's stage gets. Absent: the guards read "not run". */
+    stageGuards?: StageGuardDeps;
+    /** The guard names the plan counted (`desired.guards`); they go into the applied hash. */
+    guardInputs?: readonly string[];
 }
 /**
  * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is

package/dist/plan/archon-blue-green.js

@@ -70,6 +70,8 @@ export async function applyArchonBlueGreen(run) {
             generate: () => randomBytes(32).toString('hex'),
             secret: run.secret,
         }),
+        ...(run.stageGuards ? { stageGuards: run.stageGuards } : {}),
+        ...(run.guardInputs ? { guardInputs: run.guardInputs } : {}),
         actionsKey: async () => {
             const key = await mintActionsKey({
                 id,

package/dist/plan/blue-green-apply.d.ts

@@ -54,6 +54,11 @@ export interface BlueGreenApplyDeps {
      * guard unrecorded ("not run", never passed), so `stageGuardsReady` stays false and the copy does not start.
      */
     stageGuards?: StageGuardDeps;
+    /**
+     * The guard names the plan counted ({@link stageGuardInputs}, from `desired.guards`). They go into the
+     * applied structure hash, so the next plan sees the same hash until a guard becomes possible.
+     */
+    guardInputs?: readonly string[];
     /**
      * The company the stage mail sink belongs to (its name is `<slug>-stage-sink`). Absent: no sink is made and
      * stage holds no mail env at all, so the copy stays refused.