@wtfalch/foundry 0.61.0 → 0.62.0

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, NativeBuildKeyEnvPort, } 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, mintNativeBuildKey, } 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';

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, mintNativeBuildKey, } 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';

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/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,70 @@
+/**
+ * `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.
+ *
+ * Neither function here is wired into `plan/diff.ts` or `plan/executor.ts`:
+ * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
+ * route, not foundry's apply loop, and `mintNativeBuildKey` is left for the
+ * host to call from wherever it writes Boule's env (`executor.ts`'s
+ * `coolifyBoule`, the same way it already calls `mintIfAbsent` for
+ * `BOULE_OWNER_SEED_SECRET_ENV`) once that wiring has its own review --
+ * adding it here would touch every one of this package's Boule-convergence
+ * fixtures for one new env var, which is a larger change than this issue
+ * asks for.
+ */
+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;
+/** The one thing {@link mintNativeBuildKey} needs from Coolify: a live app's env, to check whether it already has a key. */
+export interface NativeBuildKeyEnvPort {
+    listEnvs(appId: string): Promise<ReadonlyArray<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }>>;
+}
+/**
+ * Mints the per-company key Boule presents to Archon's native-build route
+ * (estate#262), the same way every other per-company key in this codebase is
+ * minted (estate#207): a random value, written to Boule's env once and never
+ * rotated, kept unchanged on every later apply once it is there. Returns
+ * `null` when Boule's env already holds one -- the caller then writes
+ * nothing, so the live value stands. `onSecret`, when given, is told the
+ * minted value so the caller can keep it out of its own logs and error
+ * messages.
+ */
+export declare function mintNativeBuildKey(coolify: NativeBuildKeyEnvPort, appId: string, onSecret?: (value: string) => void): Promise<string | null>;

package/dist/native-build.js

@@ -0,0 +1,92 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * `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.
+ *
+ * Neither function here is wired into `plan/diff.ts` or `plan/executor.ts`:
+ * `dispatchNativeBuild` runs inside Archon's own `/api/native/builds`
+ * route, not foundry's apply loop, and `mintNativeBuildKey` is left for the
+ * host to call from wherever it writes Boule's env (`executor.ts`'s
+ * `coolifyBoule`, the same way it already calls `mintIfAbsent` for
+ * `BOULE_OWNER_SEED_SECRET_ENV`) once that wiring has its own review --
+ * adding it here would touch every one of this package's Boule-convergence
+ * fixtures for one new env var, which is a larger change than this issue
+ * asks for.
+ */
+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;
+/**
+ * Mints the per-company key Boule presents to Archon's native-build route
+ * (estate#262), the same way every other per-company key in this codebase is
+ * minted (estate#207): a random value, written to Boule's env once and never
+ * rotated, kept unchanged on every later apply once it is there. Returns
+ * `null` when Boule's env already holds one -- the caller then writes
+ * nothing, so the live value stands. `onSecret`, when given, is told the
+ * minted value so the caller can keep it out of its own logs and error
+ * messages.
+ */
+export async function mintNativeBuildKey(coolify, appId, onSecret) {
+    const envs = await coolify.listEnvs(appId);
+    if (envs.some((e) => e.key === NATIVE_BUILD_KEY_ENV && !e.is_preview))
+        return null;
+    const value = randomBytes(NATIVE_BUILD_KEY_BYTES).toString('base64url');
+    onSecret?.(value);
+    return value;
+}

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/blue-green.d.ts

@@ -1,4 +1,4 @@
-import type { BlueGreenConfig, DeclaredOrg, HostingEntry } from '../org.js';
+import { type BlueGreenConfig, type DeclaredOrg, type HostingEntry } from '../org.js';
 import { type StageKind } from './stage-isolation.js';
 /**
  * Blue/green releases (docs/adr/0001-blue-green-releases.md). A color is a property any app can have
@@ -164,11 +164,14 @@ export interface BlueGreenSubject {
      * (address check, crash loop) and moves up by time.
      */
     reporting: boolean;
-    /** Set for Boule and Agora, which are not hosting entries. */
+    /** Set for Boule, Agora and kosmos, which are not hosting entries. */
     builtin?: BuiltinApp;
 }
-/** The apps foundry runs for every company, which can declare blue/green (`org.boule`, `org.agora`). */
-export type BuiltinApp = 'boule' | 'agora';
+/**
+ * The apps foundry runs for a company that can declare blue/green: Boule and Agora, every company's own, plus
+ * kosmos once the company turns it on (`org.boule`, `org.agora`, `org.kosmos`; docs/adr/0001, rule 1).
+ */
+export type BuiltinApp = 'boule' | 'agora' | 'kosmos';
 export declare const BUILTIN_APPS: readonly BuiltinApp[];
 /** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
 export declare const BUILTIN_APP: {
@@ -188,6 +191,14 @@ export declare const BUILTIN_APP: {
         readonly database: false;
         readonly reporting: false;
     };
+    readonly kosmos: {
+        readonly repo: "wtfalch/kosmos";
+        readonly dockerfile: "/Dockerfile";
+        readonly port: 3000;
+        readonly healthPath: "/api/health";
+        readonly database: true;
+        readonly reporting: true;
+    };
 };
 /**
  * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
@@ -195,11 +206,12 @@ export declare const BUILTIN_APP: {
  */
 export declare function entrySubject(org: DeclaredOrg, entry: HostingEntry, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
 /**
- * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
- * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ * The company's Boule, Agora or kosmos as a subject; `null` when it does not declare blue/green (see
+ * {@link builtinDeclaresBlueGreen}). The running app keeps its name `<slug>-<app>` and is blue, like
+ * platform-archon. All three run on the primary server only.
  */
 export declare function builtinSubject(org: DeclaredOrg, app: BuiltinApp, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
-/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule, Agora and kosmos. */
 export declare function blueGreenSubjects(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): BlueGreenSubject[];
 /** Whether the org declares blue/green for any of its apps. */
 export declare const declaresBlueGreen: (org: DeclaredOrg) => boolean;

package/dist/plan/blue-green.js

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
+import { kosmosOn } from '../org.js';
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { serverConnectorScopeKey } from './cloudflared-connector.js';
 import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { appNameFor, appStepKey } from './platform-diff.js';
 import { remoteDatabaseAppliedFor } from './remote-database.js';
 import { buildStageEnv } from './stage-env.js';
@@ -165,7 +167,7 @@ export function reportingEnv(input) {
         { key: REPORTING_ENV.healthToken, value: input.healthToken },
     ];
 }
-export const BUILTIN_APPS = ['boule', 'agora'];
+export const BUILTIN_APPS = ['boule', 'agora', 'kosmos'];
 /** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
 export const BUILTIN_APP = {
     boule: {
@@ -185,7 +187,31 @@ export const BUILTIN_APP = {
         database: false,
         reporting: false,
     },
+    kosmos: {
+        repo: 'wtfalch/kosmos',
+        dockerfile: '/Dockerfile',
+        port: 3000,
+        healthPath: '/api/health',
+        database: true,
+        reporting: true,
+    },
 };
+/** `builtinSubject`'s hostname for each built-in app, kept beside {@link BUILTIN_APP} rather than a third switch. */
+function builtinHostnameFor(org, app) {
+    if (app === 'boule')
+        return bouleHostnameFor(org);
+    if (app === 'agora')
+        return agoraHostnameFor(org);
+    return kosmosHostnameFor(org);
+}
+/**
+ * Whether `org` declares blue/green for a built-in app: Boule and Agora opt into it through their own
+ * `blueGreen` field (they already run as a single copy otherwise); kosmos has no single-copy mode -- turning
+ * it on (`org.kosmos.enabled`) always runs it blue/green, docs/adr/0001 rule 1.
+ */
+function builtinDeclaresBlueGreen(org, app) {
+    return app === 'kosmos' ? kosmosOn(org) : org[app]?.blueGreen !== undefined;
+}
 /**
  * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
  * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
@@ -213,13 +239,14 @@ export function entrySubject(org, entry, recorded) {
     };
 }
 /**
- * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
- * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ * The company's Boule, Agora or kosmos as a subject; `null` when it does not declare blue/green (see
+ * {@link builtinDeclaresBlueGreen}). The running app keeps its name `<slug>-<app>` and is blue, like
+ * platform-archon. All three run on the primary server only.
  */
 export function builtinSubject(org, app, recorded = {}) {
-    const config = org[app]?.blueGreen;
-    if (!config)
+    if (!builtinDeclaresBlueGreen(org, app))
         return null;
+    const config = org[app]?.blueGreen ?? {};
     const spec = BUILTIN_APP[app];
     const base = `${org.slug}-${app}`;
     return {
@@ -233,7 +260,7 @@ export function builtinSubject(org, app, recorded = {}) {
         buildPack: 'dockerfile',
         healthPath: spec.healthPath,
         database: spec.database,
-        hostnames: [app === 'boule' ? bouleHostnameFor(org) : agoraHostnameFor(org)],
+        hostnames: [builtinHostnameFor(org, app)],
         config,
         blueAppKey: `coolify:${app}:${org.id}`,
         dockerfileLocation: spec.dockerfile,
@@ -241,7 +268,7 @@ export function builtinSubject(org, app, recorded = {}) {
         builtin: app,
     };
 }
-/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule, Agora and kosmos. */
 export function blueGreenSubjects(org, recorded) {
     const subjects = [];
     for (const entry of org.hosting.entries) {
@@ -258,7 +285,7 @@ export function blueGreenSubjects(org, recorded) {
 }
 /** Whether the org declares blue/green for any of its apps. */
 export const declaresBlueGreen = (org) => org.hosting.entries.some((entry) => entry.blueGreen) ||
-    BUILTIN_APPS.some((app) => org[app]?.blueGreen);
+    BUILTIN_APPS.some((app) => builtinDeclaresBlueGreen(org, app));
 /**
  * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
  * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as

package/dist/plan/deploy-health.js

@@ -142,10 +142,17 @@ async function matchesHealth(fetchImpl, health) {
         const response = await fetchImpl(health.url, {
             signal: AbortSignal.timeout(HEALTH_REQUEST_TIMEOUT_MS),
         });
-        if (!response.ok)
+        if (!response.ok) {
+            // #760: an unread body left undici's parser paused when the socket
+            // ended, throwing an uncaught assertion in the host. Every answer this
+            // function does not go on to consume gets cancelled here.
+            await response.body?.cancel();
             return false;
-        if (health.kind === 'ready')
+        }
+        if (health.kind === 'ready') {
+            await response.body?.cancel();
             return true;
+        }
         const body = await response.json().catch(() => undefined);
         const value = body && typeof body === 'object'
             ? body[health.field ?? 'version']

package/dist/plan/desktop-callback.js

@@ -1,6 +1,7 @@
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { appHostname, cmsStudioHostnameFor, entryHostnames } from './hostnames.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { workspaceAuthEntryOf, workspaceClientHosts } from './workspace-client.js';
 /**
  * #339: the desktop app signs in through the company's web app, so every
@@ -36,7 +37,9 @@ export function signInRedirectUris(org, appKey) {
                     ? cmsStudioHostnameFor(org)
                     : appKey === 'boule'
                         ? bouleHostnameFor(org)
-                        : appHostname(org),
+                        : appKey === 'kosmos'
+                            ? kosmosHostnameFor(org)
+                            : appHostname(org),
             ];
     return [
         ...hosts.map((host) => `https://${host}/auth/callback`),