@wtfalch/foundry 0.60.0 → 0.62.0

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

@@ -1,5 +1,6 @@
 import { type WorkerAppConfig } from './worker-app-config.js';
 export type { WorkerAppConfig } from './worker-app-config.js';
+export { AI_ENTRY_PERMISSIONS, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, } from './entry-rules.js';
 /**
  * Opaque, minted by foundry when an org is created. Keys the declared org,
  * the applied state, every estate-wide service's id map, and the chat
@@ -218,6 +219,11 @@ export interface IssuerApp {
  * validates is always one Coolify itself accepts.
  */
 export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercompose';
+/** The company's GitHub App installation: the numeric installation id and the account (user or org login) it is installed on. */
+export interface HostingGithub {
+    installationId: number;
+    account: string;
+}
 /**
  * The org's hosted apps and what runs beside them (#71, part of #14's
  * adopted/standard/bespoke map) -- distinct from the cms site (`SiteConfig`
@@ -233,6 +239,12 @@ export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercom
  * be true.
  */
 export interface HostingConfig {
+    /**
+     * The company's installation of the platform's GitHub App. With it an entry's `repo` may be
+     * `<account>/<name>` as well as `wtfalch/<name>`, and the planner makes the company its own Coolify GitHub
+     * source (`coolify:github-source`) from the installation id. Absent: only `wtfalch/<name>`.
+     */
+    github?: HostingGithub;
     /** The org's apps run on Coolify. */
     enabled: boolean;
     /** Served on `DeclaredOrg.domain` (and its Cloudflare zone managed) instead of `<slug>.oikos.host` (`../slug.ts`). */
@@ -289,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' | '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' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | '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';
+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.
@@ -322,6 +334,11 @@ export interface HostingEntry {
     buildPack: HostingBuildPack;
     /** The port the app listens on. `null` is Coolify's default. */
     port: number | null;
+    /**
+     * The app's live address on the platform's apps domain: `<hostedName>.companyincluded.app`. A
+     * label {@link hostedLabelRefusal} accepts; unique within the org (the host checks it across orgs).
+     */
+    hostedName?: string;
     /**
      * 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.
@@ -374,8 +391,8 @@ export interface HostingEntry {
      * F8: a Cloudflare Worker foundry deploys from this entry's own repo,
      * beside the app, on the org's own zone. Only our own repos may use this
      * (#318: outside customers need Workers for Platforms, not built yet), so
-     * `validateEntryWorker` refuses it unless `repo` is set (every non-null
-     * `repo` already matches `wtfalch/...`, {@link REPO}) and the route's zone
+     * `validateEntryWorker` refuses it unless `repo` is set and under `wtfalch`
+     * ({@link REPO}; a company's own GitHub account is refused) and the route's zone
      * is the org's own domain.
      */
     worker?: WorkerConfig;
@@ -390,7 +407,63 @@ export interface HostingEntry {
      * blue and a green copy behind a load balancer on every server it manages, and the tunnel routes to the balancer.
      */
     blueGreen?: BlueGreenConfig;
+    /**
+     * A private workspace for the app: it runs at `workspaceHost(slug, key)` behind a Cloudflare Access gate that
+     * lets in the company's people and `testers`. A server entry's workspace is the blue/green stage machinery
+     * (its own empty database, the stage mail sink, the stage guards) without colors; a `workerApp` entry's is a
+     * second Worker script `<slug>-<key>-work`. See `plan/workspace.ts`. Not combined with `blueGreen`.
+     */
+    workspace?: EntryWorkspace;
+    /**
+     * Whether the app is live. Absent means true. `false` plans no public hostname, DNS record, live app or live
+     * Worker: only the workspace exists, so it needs `workspace`. Setting it to true makes the live app from the
+     * commit the workspace runs, with its own database; the workspace stays.
+     */
+    live?: boolean;
+    /**
+     * The 40 character commit the live app runs, set by a promote. Needs `workspace` and a server (repo) entry.
+     * When set, the live app is made from it and later moved to it (`git_commit_sha` patched, then deployed),
+     * whatever the workspace runs. Absent: the app is made from the workspace's commit and stays there. It may be
+     * a commit the workspace never ran (a rollback).
+     */
+    liveCommit?: string;
+    /**
+     * Parts of the app only the company's people may open, each gated by a path-scoped Cloudflare Access
+     * application on `<host><path>`, on the live hosts and (with a `workspace`) on the workspace host. See
+     * `plan/private-pages.ts`.
+     */
+    privatePages?: PrivatePage[];
+}
+/** One private page of an entry. */
+export interface PrivatePage {
+    /** Starts with `/`; letters, digits and `. _ ~ - /`; no query, no trailing slash, not `/` itself. */
+    path: string;
+    /** The company's role ids that may open the page. Foundry cannot resolve roles; see `people`. */
+    roles: string[];
+    /**
+     * The company people holding `roles`, as email addresses, resolved by the host that declares the org (as
+     * `workspace.testers` is supplied). The gate admits the owners plus these. Absent: the owners only.
+     */
+    people?: string[];
+}
+export declare const MAX_PRIVATE_PAGES = 20;
+export declare const MAX_PRIVATE_PAGE_ROLES = 50;
+export declare const MAX_PRIVATE_PAGE_PEOPLE = 200;
+export declare const PRIVATE_PAGE_PATH: RegExp;
+/** The keys of the Access gates private pages get: `pp-` (live) or `wp-` (workspace) and 16 hex characters. */
+export declare const PRIVATE_PAGE_GATE_KEY: RegExp;
+/** A full git commit: 40 lowercase hex characters. */
+export declare const FULL_COMMIT_SHA: RegExp;
+/** The people outside the company who may open an entry's workspace. */
+export interface EntryWorkspace {
+    /** Email addresses, at most {@link MAX_WORKSPACE_TESTERS}, distinct when lowercased. */
+    testers: string[];
 }
+export declare const MAX_WORKSPACE_TESTERS = 50;
+/** An entry is live unless it says `live: false`. */
+export declare const isLiveEntry: (entry: Pick<HostingEntry, "live">) => boolean;
+/** Trimmed, lowercased and distinct testers, in the order first seen. The planner and hosts read testers through this. */
+export declare function normalizeTesters(testers: readonly string[]): string[];
 /**
  * `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
@@ -399,11 +472,46 @@ export interface HostingEntry {
 export interface OrgBuiltinApp {
     blueGreen?: BlueGreenConfig;
 }
+/**
+ * The company's Boule. `apps` (F3, F5, F7) turns on the managed-apps platform keys: Boule installs and runs apps
+ * for the company, so foundry gives it an edge key that may deploy the company's own Workers
+ * (`plan/entry-edge-key.ts`), a registrar key at the sign-in broker (`plan/broker-registrar.ts`) and a registrar key
+ * at the signed-records service (`plan/keys-registrar.ts`). Absent is off. Boule's apps are not in `hosting.entries`,
+ * so this switch is how the plan knows the company has any.
+ */
+export interface BouleApp extends OrgBuiltinApp {
+    apps?: boolean;
+}
+/** 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. */
     steps?: number[];
     stepHoldMinutes?: number;
+    /**
+     * How a step is left. `signal` (default): the hold passed and the error rate matches the old color's.
+     * `time`: the hold passed and the error rate is not failing. `approval`: a person approves each step.
+     */
+    advance?: 'time' | 'signal' | 'approval';
+    /** Requests the new color needs before its error rate counts (whole number 1..100000). Default 20. */
+    minRequests?: number;
+    /** The new color matches the old while its error rate is at most the old plus this (0..1). Default 0.02. */
+    errorMargin?: number;
+    /** A promote deploys the idle color and holds it at weight 0 for staff until an `open` action. Default false. */
+    staffFirst?: boolean;
 }
 /** One named volume on a hosting entry's app. */
 export interface EntryVolume {
@@ -498,6 +606,16 @@ export interface EntryAuth {
      * `users: 'customers'`.
      */
     signIn?: 'password' | 'email-code';
+    /**
+     * The entry's own customers get workspaces in the broker: they make one, invite people by email and give
+     * each member one of `roles`. The first role is the owner role. `invitePath` is the page on the entry's
+     * host the invitation mail links to (`<host><invitePath>?token=`). Needs `users: 'customers'` and an
+     * entry that runs as a server. The entry gets `WORKSPACES_URL` and `WORKSPACES_API_KEY`.
+     */
+    workspaces?: {
+        roles: string[];
+        invitePath: string;
+    };
     /**
      * The left-half text of the customers' sign-in window. Written on the
      * customers organisation as metadata `wtfalch.room` (JSON, keys in the
@@ -506,6 +624,8 @@ export interface EntryAuth {
      */
     room?: EntryAuthRoom;
 }
+/** The env names `uses.auth.workspaces` writes; `env` may not name them. */
+export declare const WORKSPACES_ENTRY_ENV_NAMES: readonly ["WORKSPACES_URL", "WORKSPACES_API_KEY"];
 export interface EntryAuthRoom {
     name: string;
     headline: string;
@@ -514,20 +634,6 @@ export interface EntryAuthRoom {
     description?: string;
     steps?: number;
 }
-/** Longest value of each `uses.auth.room` text field. */
-export declare const ROOM_TEXT_MAX: {
-    readonly name: 40;
-    readonly headline: 120;
-    readonly line: 200;
-    readonly title: 60;
-    readonly description: 200;
-};
-export declare const ROOM_STEPS_MIN = 2;
-export declare const ROOM_STEPS_MAX = 9;
-/** `uses.auth.mcp.onboardingPath`: absolute, no query, no fragment, no dot segments. */
-export declare const ONBOARDING_PATH_MAX_LENGTH = 200;
-/** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
-export declare const MCP_PATH: RegExp;
 /**
  * AI for one entry: a key below the org's own ai key, the `AI_*` env and,
  * with `webhookPath`, the ai webhook. `offerings` is what the app may call,
@@ -540,8 +646,6 @@ export interface EntryAi {
     permissions?: string[];
     webhookPath?: string;
 }
-/** What an entry's ai key may hold: the most the org's own key holds. */
-export declare const AI_ENTRY_PERMISSIONS: readonly ["ai.offerings:invoke", "ai.runs:create"];
 /** The env names `uses.ai` writes; `env` may not name them. */
 export declare const AI_ENTRY_ENV_NAMES: readonly ["AI_URL", "AI_ORGANISATION_ID", "AI_API_KEY", "AI_WEBHOOK_SECRET", "AI_OFFERINGS_JSON"];
 /**
@@ -559,8 +663,6 @@ export interface EntryFiles {
     permissions?: string[];
     shareHost?: boolean;
 }
-/** What an entry's files key may hold: read and write on its collections, and the most the org's own key holds besides minting. */
-export declare const FILES_ENTRY_PERMISSIONS: readonly ["files.collections:read", "files.files:read", "files.files:download", "files.files:upload", "files.files:replace", "files.files:delete"];
 /** The env names `uses.files` always writes, besides one `FILES_COLLECTION_<NAME>_ID` per collection. */
 export declare const FILES_ENTRY_ENV_NAMES: readonly ["FILES_URL", "FILES_ORGANISATION_ID", "FILES_API_KEY"];
 export declare const filesCollectionEnvName: (name: string) => string;
@@ -576,9 +678,49 @@ export interface HostingEntryUses {
      * org `domain`.
      */
     edge?: true;
+    /**
+     * The entry sends mail from the company's mail domain: it gets the company's
+     * Lettermint token and `MAIL_FROM`, as the main app does. In a workspace the
+     * stage gets the mail sink's env only (`stageMailEnv`).
+     */
+    mail?: true;
+    /**
+     * The entry is a project of its own in the jobs scheduler and gets
+     * `JOBS_SCHEDULER_URL` (the scheduler's public origin), `JOBS_SIGNING_SECRET`
+     * and `JOBS_SYNC_KEY` (`plan/entry-jobs.ts`). Blocked, not planned, until the
+     * scheduler's public route (`plan/own-jobs-route.ts`) is recorded: the owner
+     * company's for a company on shared services, the company's own otherwise.
+     * A workspace gets none of the three.
+     */
+    jobs?: true;
+    /**
+     * The app keeps a tamper-evident audit log (`@wtfalch/audit`). A Worker app with a database: the append-only
+     * tables and the two chain functions are derived (`audit/ledger-set.ts`), never listed by hand, and the
+     * platform's sealing service signs and anchors the ledger on a schedule with a key the app never holds
+     * (`plan/entry-audit.ts`, `audit/`). The erase functions are not granted.
+     */
+    audit?: true;
+    /**
+     * The app implements Boule's customer-grants routes under `/api/customer-grants`, called by a machine
+     * (Boule), not a person. F11 only lets that path through a gated host (`entryMachinePaths`); F13 builds
+     * the rest (the credential, the app env and Boule's entry).
+     */
+    customerGrants?: true;
+    /**
+     * F12: the entry gets credentials for its own `repo`: a GitHub deploy key made for it (write only with
+     * `access: 'write'`), delivered as `GIT_REPO_URL` (`git@github.com:<owner>/<name>.git`) and `GIT_SSH_KEY`
+     * (`plan/entry-repo-key.ts`). Needs `repo`. Removed with the entry or the flag; a workspace copy gets none.
+     */
+    repo?: {
+        access: 'read' | 'write';
+    };
 }
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export declare const EDGE_ENTRY_ENV_NAMES: readonly ["EDGE_URL", "EDGE_API_KEY"];
+/** The env names `uses.mail` writes; `env` may not name them. */
+export declare const MAIL_ENTRY_ENV_NAMES: readonly ["LETTERMINT_API_TOKEN", "MAIL_FROM"];
+/** The env names `uses.jobs` writes; `env` may not name them. */
+export declare const JOBS_ENTRY_ENV_NAMES: readonly ["JOBS_SCHEDULER_URL", "JOBS_SIGNING_SECRET", "JOBS_SYNC_KEY"];
 /**
  * A plain string is pushed as it is, so `validateHosting` refuses one that
  * looks like a secret. `{ from }` names a value the plan already mints.
@@ -661,10 +803,26 @@ export interface HostingNames {
 export declare function normalizeHostingRepos(repos: readonly string[] | undefined): string[];
 /** {@link validateHosting} with the code and path of the first refusal. */
 export declare function refuseHosting(hosting: HostingConfig, names?: HostingNames): OrgRefusal | null;
+/**
+ * The company's GitHub config when `repo` is under its account, else `undefined`: such an entry is built
+ * through the company's own Coolify source, any other through the platform's. Read it only through this.
+ */
+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. */
+export declare const CUSTOMER_GRANTS_ENTRY_ENV_NAMES: readonly ["CUSTOMER_GRANTS_CREDENTIAL"];
+/** The platform zone new app addresses (`<hostedName>.companyincluded.app`) and every workspace live in. */
+export declare const APPS_DOMAIN = "companyincluded.app";
 export declare function validateDomain(domain: string): string | null;
 /**
  * A broker entry name foundry writes itself: Archon's, and any company's Boule.
@@ -1082,9 +1240,11 @@ export interface DeclaredOrg {
     /** Absent means `{ inApp: true }`. Optional so every existing literal and fixture compiles unchanged. */
     signIn?: SignInConfig;
     /** The company's Boule. Absent means no blue/green. */
-    boule?: OrgBuiltinApp;
+    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. */