@wtfalch/foundry 0.46.0 → 0.48.0

package/dist/build-json.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { type WorkerAppConfig } from './worker-app-config.js';
+/**
+ * The `build.json` a company's release carries: what Archon needs to deploy one build of a Worker
+ * app. Same shapes as `WorkerAppConfig`; `repo` and `commit` say where the build came from.
+ * Whether `artifactUrl` is an asset of that release is checked by the reader that fetched it.
+ */
+export interface BuildJson {
+    repo: string;
+    commit: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    compatibilityDate?: string;
+    compatibilityFlags?: 'nodejs_compat'[];
+    durableObjects: WorkerAppConfig['durableObjects'];
+    containers?: WorkerAppConfig['containers'];
+    migrationsSha256?: string;
+}
+export type BuildJsonErrorCode = 'unknown_field' | 'missing_field' | 'wrong_type' | 'not_https' | 'bad_sha256';
+/** Thrown by {@link parseBuildJson}. `path` is dotted into the build.json; the message never carries a value. */
+export declare class BuildJsonError extends Error {
+    readonly code: BuildJsonErrorCode;
+    readonly path: string;
+    constructor(code: BuildJsonErrorCode, path: string);
+}
+export declare const buildJsonSchema: z.ZodType<BuildJson>;
+/** Parses a build.json. Throws {@link BuildJsonError} for the first problem. */
+export declare function parseBuildJson(input: unknown): BuildJson;

package/dist/build-json.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { WORKER_APP_COMPATIBILITY_FLAGS, WORKER_APP_INSTANCE_TYPES, WORKER_APP_MAX_INSTANCES, } from './worker-app-config.js';
+/** Thrown by {@link parseBuildJson}. `path` is dotted into the build.json; the message never carries a value. */
+export class BuildJsonError extends Error {
+    code;
+    path;
+    constructor(code, path) {
+        super(`build.json refused (${code}) at ${path || '(root)'}`);
+        this.code = code;
+        this.path = path;
+        this.name = 'BuildJsonError';
+    }
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const sha256 = z.string().regex(SHA256_HEX, { message: 'bad_sha256' });
+const text = z.string().min(1);
+const httpsUrl = z.string().superRefine((value, ctx) => {
+    let url = null;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        // not a URL: refused below
+    }
+    if (url === null || url.protocol !== 'https:') {
+        ctx.addIssue({ code: 'custom', message: 'not_https' });
+    }
+});
+const durableObjects = z.strictObject({
+    classes: z.record(z.string(), z.string()),
+    migrations: z.array(z.strictObject({
+        tag: z.string(),
+        newSqliteClasses: z.array(z.string()).optional(),
+        deletedClasses: z.array(z.string()).optional(),
+        renamedClasses: z.array(z.strictObject({ from: z.string(), to: z.string() })).optional(),
+    })),
+});
+const container = z.strictObject({
+    className: z.string(),
+    image: z.strictObject({
+        repository: z.string(),
+        digest: z.string().regex(DIGEST, { message: 'wrong_type' }),
+    }),
+    instanceType: z.string().refine((v) => WORKER_APP_INSTANCE_TYPES.has(v), {
+        message: 'wrong_type',
+    }),
+    maxInstances: z.number().int().min(1).max(WORKER_APP_MAX_INSTANCES),
+});
+export const buildJsonSchema = z.strictObject({
+    repo: text,
+    commit: text,
+    artifactUrl: httpsUrl,
+    artifactSha256: sha256,
+    compatibilityDate: z.string().optional(),
+    compatibilityFlags: z
+        .array(z.string().refine((v) => WORKER_APP_COMPATIBILITY_FLAGS.has(v), { message: 'wrong_type' }))
+        .optional(),
+    durableObjects,
+    containers: z.array(container).optional(),
+    migrationsSha256: sha256.optional(),
+});
+function valueAt(input, path) {
+    let current = input;
+    for (const key of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function dotted(path) {
+    return path.map(String).join('.');
+}
+/** Parses a build.json. Throws {@link BuildJsonError} for the first problem. */
+export function parseBuildJson(input) {
+    const result = buildJsonSchema.safeParse(input);
+    if (result.success)
+        return result.data;
+    const issue = result.error.issues[0];
+    if (!issue)
+        throw new BuildJsonError('wrong_type', '');
+    if (issue.code === 'unrecognized_keys') {
+        const base = dotted(issue.path);
+        const key = issue.keys[0] ?? '';
+        throw new BuildJsonError('unknown_field', base ? `${base}.${key}` : key);
+    }
+    const path = dotted(issue.path);
+    if (issue.message === 'not_https' || issue.message === 'bad_sha256') {
+        throw new BuildJsonError(issue.message, path);
+    }
+    if (valueAt(input, issue.path) === undefined)
+        throw new BuildJsonError('missing_field', path);
+    throw new BuildJsonError('wrong_type', path);
+}

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, BlueGreenConfig, OrgBuiltinApp, OrgRefusal, OrgRefusalCode, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, isMainEntry, mainEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export { refuseOrg } from './refuse-org.js';
+export { workerAppHasBuild } from './worker-app-config.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>;
-export type { RequestableField, CallsChange, CustomersChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
+export type { RequestableField, CallsChange, CustomersChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, AppChange, BuildChange, FailureCode, RequestedBy, } from './requested-changes.js';
+export type { BuildJson, BuildJsonErrorCode } from './build-json.js';
+export { buildJsonSchema, parseBuildJson, BuildJsonError } from './build-json.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
@@ -25,13 +29,15 @@ export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAudit
 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 { DumpError, dumpNow } from './plan/index.js';
+export type { DatabaseDump } 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';
 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';
+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, stepEntryKey, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';

package/dist/index.js

@@ -1,10 +1,13 @@
-export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, appEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, isMainEntry, mainEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
+export { refuseOrg } from './refuse-org.js';
+export { workerAppHasBuild } from './worker-app-config.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.
 import { VERSIONS } from './bootstrap/versions.js';
 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 { StaleLeaseError } from './store.js';
@@ -15,10 +18,11 @@ 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';
 export { AdoptRefusedError } from './plan/index.js';
+export { DumpError, dumpNow } 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';
-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 { 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, stepEntryKey, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgTarget, } from './plan/index.js';

package/dist/migrations/0058_app_requests.sql

@@ -0,0 +1,32 @@
+-- @wtfalch/foundry: a company's app requests (826 items 4 and 5). A Save in Boule or a release
+-- build puts one hosting entry (`app`) or deploys one build (`build`); Archon applies it within the
+-- plan's limits. Mirrors src/store/schema.ts's `foundryRequestedChanges`.
+--
+-- Additive only, like 0057_org_customers.sql (which also widens this table's field check): new
+-- nullable columns, `updated_at` with a default, a partial unique index, and wider checks. Every
+-- existing row satisfies the wider checks and reads back with null in the new columns, so the
+-- migration is safe on live rows when the container starts.
+
+alter table foundry_requested_changes
+  add column if not exists requester jsonb,
+  add column if not exists idempotency_key text,
+  add column if not exists reason jsonb,
+  add column if not exists updated_at timestamptz not null default now();
+
+-- One request per (org, key): a repeated Save or webhook delivery returns the first row.
+create unique index if not exists foundry_requested_changes_idempotency_idx
+  on foundry_requested_changes (org_id, idempotency_key)
+  where idempotency_key is not null;
+
+-- `applying`: Archon is applying it. `failed`: it ended without applying; `reason` says why.
+alter table foundry_requested_changes
+  drop constraint if exists foundry_requested_changes_state_check;
+alter table foundry_requested_changes
+  add constraint foundry_requested_changes_state_check
+    check (state in ('auto', 'needs_approval', 'approved', 'rejected', 'applied', 'applying', 'failed'));
+
+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'));

package/dist/migrations/0059_org_builtin_blue_green.sql

@@ -0,0 +1,9 @@
+-- @wtfalch/foundry: `boule_blue_green` and `agora_blue_green` are `org.boule.blueGreen` and
+-- `org.agora.blueGreen` as JSON ({ steps?, stepHoldMinutes? }); null (the default) keeps the company's
+-- Boule or Agora on one app. Copies 0056_platform_archon_blue_green.sql: nullable columns added with
+-- `if not exists`, so it is 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 boule_blue_green jsonb,
+  add column if not exists agora_blue_green jsonb;

package/dist/org.d.ts

@@ -282,6 +282,17 @@ 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' | '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' | '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' | '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' | 'client_name_taken' | '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_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' | '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.
+ */
+export interface OrgRefusal {
+    code: OrgRefusalCode;
+    path: string;
+    message: string;
+}
 /**
  * One app the org runs. `database` and `gates` are meaningless without
  * `HostingConfig.enabled`, so `validateHosting` requires it before either is
@@ -305,6 +316,11 @@ export interface HostingEntry {
     buildPack: HostingBuildPack;
     /** The port the app listens on. `null` is Coolify's default. */
     port: number | null;
+    /**
+     * The org's main app: served at the org's main address (`<slug>.oikos.host`, or the domain's
+     * apex), whatever its key. An entry keyed {@link APP_ENTRY_KEY} with `main` unset is main.
+     */
+    main?: boolean;
     /** The path that answers 200 when the app is healthy. `null` is none. */
     healthPath: string | null;
     /**
@@ -369,6 +385,14 @@ export interface HostingEntry {
      */
     blueGreen?: BlueGreenConfig;
 }
+/**
+ * `boule` and `agora` on a company: the built-in apps foundry runs for every company (`<slug>-boule`,
+ * `<slug>-agora`). Only blue/green is declared here; absent means off. Optional so every existing literal and
+ * fixture compiles unchanged.
+ */
+export interface OrgBuiltinApp {
+    blueGreen?: BlueGreenConfig;
+}
 /** 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. */
@@ -551,8 +575,10 @@ export interface EnvHeldSecret {
     from: 'heldSecret';
     name: string;
 }
-/** The org's `app` entry: today's one app. */
-export declare function appEntry(hosting: HostingConfig): HostingEntry | undefined;
+/** True for the entry marked `main`, and for an entry keyed {@link APP_ENTRY_KEY} that leaves `main` unset. */
+export declare function isMainEntry(entry: Pick<HostingEntry, 'key' | 'main'>): boolean;
+/** The org's main app: the entry marked `main`, else the entry keyed {@link APP_ENTRY_KEY}. */
+export declare function mainEntry(hosting: Pick<HostingConfig, 'entries'>): HostingEntry | undefined;
 /**
  * The closed set of values the plan already mints that `HostingEntry.env`
  * may map an app's env var name to (#243): the org's own Files organisation
@@ -585,19 +611,27 @@ export declare const heldEnvRef: (orgId: string, entryKey: string, name: string)
  * - `tunnel` requires `enabled` -- it means nothing without the apps running.
  * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
- * - `enabled` requires an entry keyed {@link APP_ENTRY_KEY}.
+ * - `enabled` requires at least one entry, and at most one entry is the main app ({@link isMainEntry}).
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
  */
-export declare function validateHosting(hosting: HostingConfig, names?: {
+export declare function validateHosting(hosting: HostingConfig, names?: HostingNames): string | null;
+/** What {@link refuseHosting} knows of the org's names (see `plan/locked-hostnames.ts`'s `hostingNames`). */
+export interface HostingNames {
     domain: string | null;
     locked: ReadonlySet<string>;
     slug?: string;
     siteOwnsApex?: boolean;
-}): string | null;
+    /** Boule or Agora declares `blueGreen`: the blue/green key names are reserved for the entries too. */
+    builtinBlueGreen?: boolean;
+}
+/** {@link validateHosting} with the code and path of the first refusal. */
+export declare function refuseHosting(hosting: HostingConfig, names?: HostingNames): OrgRefusal | null;
 /** `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;
 export declare function validateDomain(domain: string): string | null;
 /**
  * A broker entry name foundry writes itself: Archon's, and any company's Boule.
@@ -715,6 +749,10 @@ export interface CustomersConfig {
 export declare function validateCustomers(org: Pick<DeclaredOrg, 'customers'> & {
     hosting: Pick<HostingConfig, 'entries'>;
 }): string | null;
+/** {@link validateCustomers} with the code and path of the refusal. */
+export declare function refuseCustomers(org: Pick<DeclaredOrg, 'customers'> & {
+    hosting: Pick<HostingConfig, 'entries'>;
+}): OrgRefusal | null;
 /** 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. */
@@ -1009,6 +1047,10 @@ export interface DeclaredOrg {
     services?: ServicesConfig;
     /** Absent means `{ inApp: false }`. Optional so every existing literal and fixture compiles unchanged. */
     signIn?: SignInConfig;
+    /** The company's Boule. Absent means no blue/green. */
+    boule?: OrgBuiltinApp;
+    /** The company's Agora, a static app: its release moves on hard fails and time only. Absent means no blue/green. */
+    agora?: OrgBuiltinApp;
     /** 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. */