@wtfalch/foundry 0.60.0 → 0.62.0

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

@@ -7,10 +7,11 @@ import { waitForNewDeployment } from './deploy-health.js';
 import { commandHealthCheckSettings, wgetProbe } from './health-check-settings.js';
 import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
 import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
-import { buildStageEnv } from './stage-env.js';
+import { STAGE_SIGN_IN_NAMES, buildStageEnv } from './stage-env.js';
 import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
 import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
 import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_APP_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_IMAGE_TAG, STAGE_SINK_REPOSITORY, stageMailEnv, stageSinkAppName, } from './stage-sink.js';
+import { readWorkspaceCommit, wsKey } from './workspace.js';
 /** How long one Coolify call of the sink may take. */
 const SINK_CALL_TIMEOUT_MS = 30_000;
 /** Env names whose value is a credential: registered before they are copied. */
@@ -97,6 +98,30 @@ export async function applyBlueGreenServer(deps, subject, server) {
     deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
     await deps.persist();
 }
+/**
+ * Applies a server workspace on the primary: the stage mail sink, then the stage app with its own empty
+ * database, the stage guards and the gate, exactly as a blue/green stage, and no colors. The commit the stage
+ * deployed is recorded as `ws.<id>.commit` for the live app to pin to. A failure halfway leaves the sink, app
+ * and database already made, recorded by id; the next run finds them and does the rest. Stage fails closed for
+ * itself: a refused guard records `bg.<id>.stagestate` and writes nothing to the stage app.
+ */
+export async function applyWorkspaceServer(deps, subject, serverUuid) {
+    const sinkReady = await ensureStageSink(deps, subject, serverUuid);
+    await ensureStage(deps, subject, serverUuid);
+    if (!sinkReady) {
+        deps.record(bgKey.stageState(subject.id), 'blocked:sink');
+        await deps.persist();
+    }
+    const stageId = deps.recorded()[bgKey.app(subject.id, serverUuid, 'stage')];
+    if (stageId && deps.recorded()[bgKey.stageState(subject.id)] === 'ok') {
+        const commit = (await readWorkspaceCommit(deps.coolify, stageId)) ??
+            deps.recorded()[bgKey.stage(subject.id)];
+        if (commit) {
+            deps.record(wsKey.commit(subject.id), commit);
+            await deps.persist();
+        }
+    }
+}
 /** Writes the balancer's config with the recorded weights and records them for this server. */
 export async function applyBlueGreenWeights(deps, subject, server) {
     const weights = parseWeights(deps.recorded()[bgKey.weights(subject.id)]);
@@ -109,15 +134,14 @@ export async function applyBlueGreenWeights(deps, subject, server) {
 }
 async function writeLbConfig(deps, subject, server, lbId, weights) {
     const onPrimary = server.isPrimary;
-    let pinKey = deps.recorded()[bgKey.pinKey(subject.id)];
-    if (!pinKey) {
-        pinKey = randomBytes(32).toString('hex');
-        deps.record(bgKey.pinKey(subject.id), pinKey);
-        await deps.persist();
-    }
+    const pinKey = await deps.pinKey();
+    // The idle slot is the one `bg.<id>.live` does not name; the preview router follows it on every weight write.
+    const idle = deps.recorded()[bgKey.live(subject.id)] === 'green' ? 'blue' : 'green';
     const content = renderLbConfig({
         weights,
         pinKey,
+        idle,
+        reporting: subject.reporting,
         backends: {
             blue: [colorBackend(subject, 'blue', onPrimary)],
             green: [colorBackend(subject, 'green', onPrimary)],
@@ -211,14 +235,16 @@ async function ensureGitApp(deps, subject, input) {
         await deps.persist();
         return found.uuid;
     }
-    const githubApp = await coolify.requireGithubApp();
+    const githubAppUuid = deps.githubAppUuid
+        ? await deps.githubAppUuid(subject.repo)
+        : (await coolify.requireGithubApp()).uuid;
     const created = await coolify.createGithubAppApplication({
         is_preview_deployments_enabled: false,
         project_uuid: deps.projectUuid,
         server_uuid: input.server,
         environment_name: deps.environment.name,
         environment_uuid: deps.environment.uuid,
-        github_app_uuid: githubApp.uuid,
+        github_app_uuid: githubAppUuid,
         git_repository: subject.repo,
         git_branch: input.branch,
         build_pack: subject.buildPack,
@@ -319,7 +345,7 @@ async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
  * the sink deploys; a failure clears it, logs fixed text and the error name, and returns false. Production's
  * structure goes on (stage then holds no mail env and the copy stays refused).
  */
-async function ensureStageSink(deps, subject, serverUuid) {
+export async function ensureStageSink(deps, subject, serverUuid) {
     const org = deps.stageSink;
     if (!org)
         return true;
@@ -377,7 +403,7 @@ async function ensureStageSink(deps, subject, serverUuid) {
     return true;
 }
 /** The stage app and its own empty database, on the primary. Its env comes from the allowlist, never from a copy of the live app's. */
-async function ensureStage(deps, subject, serverUuid) {
+export async function ensureStage(deps, subject, serverUuid) {
     const { coolify } = deps;
     const name = stageAppName(subject.base);
     const appId = await stageAppId(deps, subject, name, serverUuid);
@@ -419,12 +445,12 @@ async function ensureStage(deps, subject, serverUuid) {
         }
     }
     const kind = stageKindOf(subject);
-    const prodEnv = await coolify.listEnvs(deps.primaryBlueAppId);
+    const prodEnv = deps.primaryBlueAppId ? await coolify.listEnvs(deps.primaryBlueAppId) : [];
     const greenId = deps.recorded()[bgKey.app(subject.id, serverUuid, 'green')];
     const greenEnv = greenId ? await coolify.listEnvs(greenId) : [];
     const { env } = buildStageEnv({
         kind,
-        appUrl: stageAppUrl(subject),
+        appUrl: deps.stageAppUrl ?? stageAppUrl(subject),
         logDir: deps.logDir,
         database,
         prod: prodEnv,
@@ -434,8 +460,14 @@ async function ensureStage(deps, subject, serverUuid) {
             deps.secret(value);
             return value;
         },
+        ...(deps.signIn ? { signIn: deps.signIn } : {}),
     });
     const stageEnv = [...env];
+    const signInEnv = deps.signIn ? env.filter((e) => STAGE_SIGN_IN_NAMES.includes(e.key)) : [];
+    // A secret kept from an earlier apply was not minted by this run, so it is registered here.
+    for (const e of signInEnv)
+        if (envClass(e.key) === 'secret')
+            deps.secret(e.value);
     if (subject.reporting && deps.actionsKey) {
         // Stage never shares a production secret: its key is its own, minted once and kept.
         const have = (await coolify.listEnvs(appId)).find((e) => e.key === ACTIONS_KEY_ENV && !e.is_preview);
@@ -447,7 +479,7 @@ async function ensureStage(deps, subject, serverUuid) {
     const sinkApplied = deps.stageSink && deps.recorded()[STAGE_SINK_APPLIED_SCOPE_KEY];
     const mail = deps.stageSink && sinkApplied ? stageMailEnv(deps.stageSink) : [];
     const stageHas = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
-    const mailChanged = mail.some((e) => stageHas.get(e.key) !== e.value);
+    const mailChanged = [...mail, ...signInEnv].some((e) => stageHas.get(e.key) !== e.value);
     stageEnv.push(...mail);
     const stageSurface = {
         env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
@@ -464,6 +496,9 @@ async function ensureStage(deps, subject, serverUuid) {
         },
         stage: stageSurface,
         sinkMail: Object.fromEntries(mail.map((e) => [e.key, e.value])),
+        ...(deps.signIn
+            ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
+            : {}),
     });
     if (violations.length > 0) {
         // Stage fails closed for itself: nothing is written to it, production's structure goes on.
@@ -483,7 +518,12 @@ async function ensureStage(deps, subject, serverUuid) {
         probeResult = await runStageProbes(buildStageProbes({
             port: deps.stageGuards?.probes,
             stage: stageValues,
-            database: subject.database,
+            // With no live app there is no production database to try the stage role against.
+            database: subject.database && deps.primaryBlueAppId !== null,
+            ...(deps.signIn?.live.customersOrgId
+                ? { liveCustomersOrgId: deps.signIn.live.customersOrgId }
+                : {}),
+            ...(deps.signIn ? { signInRedirectUri: deps.signIn.redirectUri } : {}),
             prod: new Map(prodEnv
                 .filter((e) => !e.is_preview && e.value !== undefined)
                 .map((e) => [e.key, e.value])),

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
@@ -46,7 +46,10 @@ export declare const bgKey: {
     stageState: (id: string) => string;
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id: string) => string;
-    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    /**
+     * The held ref of the balancer's pin key (a credential: it lets a caller pick a color). A value that is 64 hex
+     * characters is the older recorded key, moved to the held ref on the next read and then overwritten by the ref.
+     */
     pinKey: (id: string) => string;
     /** The hash of the stage env name set and resource set that passed the isolation check. */
     stageIsolation: (id: string) => string;
@@ -91,6 +94,34 @@ export declare function mintActionsKey(input: {
     /** Registers the value for redaction before it is written anywhere. */
     secret: (value: string) => void;
 }): Promise<string>;
+/** The held-key name of a subject's balancer pin key: one mint per subject. */
+export declare const pinKeyName: (id: string) => string;
+/** The held store the pin key lives in; `put` is absent on a host that cannot mint. */
+export interface PinHeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+interface PinKeyInput {
+    id: string;
+    ref: string;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    heldKeys: PinHeldKeys;
+    /** Registers the value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+}
+/**
+ * The balancer's pin key, held (CLAUDE.md, Platform steps, rules 1 and 6). Order: the held key; else the older
+ * recorded key (64 hex), put in the held store and replaced by the ref; else one mint, put first, then the ref is
+ * recorded and persisted. A crash between the put and the record reuses the held key. A recorded ref whose key is
+ * no longer held stops: it never mints again. Errors name the ref only.
+ */
+export declare function mintPinKey(input: PinKeyInput & {
+    generate: () => string;
+}): Promise<string>;
+/** Reads the pin key without minting: the held key, else the older recorded key, else null. */
+export declare function readPinKey(input: Omit<PinKeyInput, 'record' | 'persist'>): Promise<string | null>;
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export declare const healthTokenName: (id: string) => string;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -133,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: {
@@ -157,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.
@@ -164,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;
@@ -200,6 +243,10 @@ export declare const LB_COOKIE_NAME = "bg_color";
 export declare const LB_COLOR_HEADER = "X-Foundry-Color";
 /** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
 export declare const LB_PIN_HEADER = "X-Foundry-Pin";
+/** The cookie that sends a signed-in person with `releases:preview` to the idle slot. */
+export declare const LB_PREVIEW_COOKIE = "bg_preview";
+/** The path the balancer asks the live slot whether a request may see the idle slot. */
+export declare const LB_PREVIEW_CHECK_PATH = "/api/foundry/preview-check";
 export declare const LB_CONFIG_PATH = "/etc/traefik/dynamic/lb.yml";
 /**
  * The balancer's inline Dockerfile: a pinned Traefik with a file provider watching one directory.
@@ -218,6 +265,10 @@ export declare function renderLbConfig(input: {
     weights: Weights;
     backends: Record<Color, string[]>;
     pinKey: string;
+    /** The slot that is not live: the `preview` router sends a cookie holder here. */
+    idle: Color;
+    /** True when the subject has a server that can answer the permission check; a static subject gets no router. */
+    reporting: boolean;
 }): string;
 /**
  * The URL of one color's container on its own server's network. On the primary, blue is the app that was
@@ -324,3 +375,4 @@ export declare function planArchonBlueGreen(input: {
     step: BlueGreenPlanStep | null;
     unmanaged: UnmanagedLine[];
 };
+export {};

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';
@@ -55,7 +57,10 @@ export const bgKey = {
     stageState: (id) => `bg.${id}.stagestate`,
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id) => `bg.${id}.bluename`,
-    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    /**
+     * The held ref of the balancer's pin key (a credential: it lets a caller pick a color). A value that is 64 hex
+     * characters is the older recorded key, moved to the held ref on the next read and then overwritten by the ref.
+     */
     pinKey: (id) => `bg.${id}.pinkey`,
     /** The hash of the stage env name set and resource set that passed the isolation check. */
     stageIsolation: (id) => `bg.${id}.stageisolation`,
@@ -102,6 +107,56 @@ export async function mintActionsKey(input) {
     await input.persist();
     return key;
 }
+/** The held-key name of a subject's balancer pin key: one mint per subject. */
+export const pinKeyName = (id) => `bg-pin-${id}`;
+/**
+ * The balancer's pin key, held (CLAUDE.md, Platform steps, rules 1 and 6). Order: the held key; else the older
+ * recorded key (64 hex), put in the held store and replaced by the ref; else one mint, put first, then the ref is
+ * recorded and persisted. A crash between the put and the record reuses the held key. A recorded ref whose key is
+ * no longer held stops: it never mints again. Errors name the ref only.
+ */
+export async function mintPinKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    const recordedValue = input.recorded()[bgKey.pinKey(input.id)];
+    if (held) {
+        input.secret(held);
+        if (recordedValue !== input.ref) {
+            input.record(bgKey.pinKey(input.id), input.ref);
+            await input.persist();
+        }
+        return held;
+    }
+    const put = input.heldKeys.put?.bind(input.heldKeys);
+    if (!put)
+        throw new Error(`pin key ${input.ref} cannot be held: the host has no held store to write`);
+    if (recordedValue && PIN_KEY.test(recordedValue)) {
+        input.secret(recordedValue);
+        await put(input.ref, recordedValue);
+        input.record(bgKey.pinKey(input.id), input.ref);
+        await input.persist();
+        return recordedValue;
+    }
+    if (recordedValue) {
+        throw new Error(`pin key ${input.ref} was minted but is no longer held; restore the held value`);
+    }
+    const key = input.generate();
+    input.secret(key);
+    await put(input.ref, key);
+    input.record(bgKey.pinKey(input.id), input.ref);
+    await input.persist();
+    return key;
+}
+/** Reads the pin key without minting: the held key, else the older recorded key, else null. */
+export async function readPinKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    const value = held ||
+        (PIN_KEY.test(input.recorded()[bgKey.pinKey(input.id)] ?? '')
+            ? input.recorded()[bgKey.pinKey(input.id)]
+            : null);
+    if (value)
+        input.secret(value);
+    return value ?? null;
+}
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export const healthTokenName = (id) => `reporting-health-${id}`;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -112,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: {
@@ -132,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}).
@@ -160,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 {
@@ -180,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,
@@ -188,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) {
@@ -205,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
@@ -246,6 +326,11 @@ export const LB_COLOR_HEADER = 'X-Foundry-Color';
 /** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
 export const LB_PIN_HEADER = 'X-Foundry-Pin';
 const PIN_KEY = /^[0-9a-f]{64}$/;
+/** The cookie that sends a signed-in person with `releases:preview` to the idle slot. */
+export const LB_PREVIEW_COOKIE = 'bg_preview';
+/** The path the balancer asks the live slot whether a request may see the idle slot. */
+export const LB_PREVIEW_CHECK_PATH = '/api/foundry/preview-check';
+const LB_PREVIEW_PRIORITY = 9000;
 /** Above the default priority of `app` (its rule length), so a pinned request never reaches the weighted service. */
 const LB_PIN_PRIORITY = 10000;
 export const LB_CONFIG_PATH = '/etc/traefik/dynamic/lb.yml';
@@ -272,7 +357,8 @@ export const LB_IMAGE_REF = `traefik:${VERSIONS.traefik}`;
  * line, so a reader sees both numbers. `backends` are the URLs of each color's containers, one per server.
  */
 export function renderLbConfig(input) {
-    const { weights, backends, pinKey } = input;
+    const { weights, backends, pinKey, idle } = input;
+    const live = COLORS.find((color) => color !== idle);
     if (!PIN_KEY.test(pinKey))
         throw new Error('the load balancer pin key is not 64 hex characters');
     const listed = COLORS.filter((color) => weights[color] > 0);
@@ -287,10 +373,29 @@ export function renderLbConfig(input) {
             `      entryPoints: [${LB_ENTRYPOINT}]`,
             `      service: ${color}`,
         ]),
+        ...(input.reporting
+            ? [
+                '    preview:',
+                `      rule: HeaderRegexp(\`Cookie\`, \`(^|;\\s*)${LB_PREVIEW_COOKIE}=1\`)`,
+                `      priority: ${LB_PREVIEW_PRIORITY}`,
+                `      entryPoints: [${LB_ENTRYPOINT}]`,
+                `      service: ${idle}`,
+                '      middlewares: [preview-check]',
+            ]
+            : []),
         '    app:',
         '      rule: PathPrefix(`/`)',
         `      entryPoints: [${LB_ENTRYPOINT}]`,
         '      service: weighted',
+        ...(input.reporting
+            ? [
+                '  middlewares:',
+                '    preview-check:',
+                '      forwardAuth:',
+                `        address: ${backends[live][0]}${LB_PREVIEW_CHECK_PATH}`,
+                '        trustForwardHeader: false',
+            ]
+            : []),
         '  services:',
         '    weighted:',
         '      weighted:',

package/dist/plan/boule.d.ts

@@ -91,6 +91,12 @@ export declare const BOULE_ARCHON_CREDENTIAL_ENV = "ARCHON_CREDENTIAL";
 /** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
 export declare const BOULE_CUSTOMERS_ORG_ENV = "CUSTOMERS_ORGANISATION_ID";
 export declare const BOULE_CUSTOMERS_CREDENTIAL_ENV = "CUSTOMERS_DIRECTORY_CREDENTIAL";
+/**
+ * F5 (Q44): the company's test customers organisation, beside {@link BOULE_CUSTOMERS_ORG_ENV}, so a workspace copy
+ * of an app registers its sign-in against it. Written once the organisation is recorded (a server workspace with
+ * customers makes it); the plan plans Boule again then, as it does for the customers organisation.
+ */
+export declare const BOULE_TEST_CUSTOMERS_ORG_ENV = "TEST_CUSTOMERS_ORGANISATION_ID";
 /**
  * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
  * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
@@ -130,9 +136,25 @@ export interface BouleCredentialWants {
     customersDirectory?: boolean;
     /** The recorded Archon credential is missing or 335 days old: the step mints it again. */
     archonRenewDue?: boolean;
+    /** F13: Boule is given `CUSTOMER_GRANTS` (an entry declares `uses.customerGrants`; needs `customersDirectory`). */
+    customerGrants?: boolean;
+    /** T3: Boule is given its company's registrar key at the sign-in broker (`plan/broker-registrar.ts`). */
+    registrar?: boolean;
+    /** T3b: customers are off but the broker still holds the record, so Boule keeps its registrar env (plan only). */
+    registrarKept?: boolean;
 }
+/** T3: the broker's base and the company's registrar key, in Boule's env (`plan/broker-registrar.ts`). */
+export declare const AUTH_REGISTRAR_URL_ENV = "AUTH_REGISTRAR_URL";
+export declare const AUTH_REGISTRAR_KEY_ENV = "AUTH_REGISTRAR_KEY";
+/**
+ * A company gets a registrar while it has customers (the people its own apps sign in) or its Boule runs apps
+ * (F5: any company that installs an app with sign-in, `org.boule.apps`).
+ */
+export declare const registrarWanted: (org: Pick<DeclaredOrg, "customers" | "boule">) => boolean;
+/** The broker's base as Boule calls it: `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`. */
+export declare const registrarUrl: (issuer: string) => string;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "SIGNIN_UPSTREAM"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "TEST_CUSTOMERS_ORGANISATION_ID", "CUSTOMER_GRANTS", "SIGNIN_UPSTREAM", "AUTH_REGISTRAR_URL", "AUTH_REGISTRAR_KEY"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a

package/dist/plan/boule.js

@@ -1,6 +1,7 @@
-import { DEFAULT_NO_REPLY_LOCAL_PART, ownerMailboxes, } from '../org.js';
+import { DEFAULT_NO_REPLY_LOCAL_PART, appsOn, ownerMailboxes, } from '../org.js';
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
 import { SIGN_IN_UPSTREAM_ENV, inAppHostApplied, signInUpstream, staleSignInUpstream, } from './sign-in.js';
+import { testCustomersOrgKey } from './workspace-client.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
  * (`executor.ts`) need to agree on for an org's Boule -- the hostname, the
@@ -102,6 +103,12 @@ export const BOULE_ARCHON_CREDENTIAL_ENV = 'ARCHON_CREDENTIAL';
 /** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
 export const BOULE_CUSTOMERS_ORG_ENV = 'CUSTOMERS_ORGANISATION_ID';
 export const BOULE_CUSTOMERS_CREDENTIAL_ENV = 'CUSTOMERS_DIRECTORY_CREDENTIAL';
+/**
+ * F5 (Q44): the company's test customers organisation, beside {@link BOULE_CUSTOMERS_ORG_ENV}, so a workspace copy
+ * of an app registers its sign-in against it. Written once the organisation is recorded (a server workspace with
+ * customers makes it); the plan plans Boule again then, as it does for the customers organisation.
+ */
+export const BOULE_TEST_CUSTOMERS_ORG_ENV = 'TEST_CUSTOMERS_ORGANISATION_ID';
 /**
  * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
  * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
@@ -144,6 +151,16 @@ export const bouleArchonCredentialRef = (orgId) => `foundry:boule-archon:${orgId
 export const customersDirectoryRef = (orgId) => `foundry:customers-directory:${orgId}`;
 /** The customers organisation id `zitadel:customers` recorded. */
 export const customersOrgIdOf = (org, recorded) => recorded[`zitadel:customers:${org.id}`] || undefined;
+/** T3: the broker's base and the company's registrar key, in Boule's env (`plan/broker-registrar.ts`). */
+export const AUTH_REGISTRAR_URL_ENV = 'AUTH_REGISTRAR_URL';
+export const AUTH_REGISTRAR_KEY_ENV = 'AUTH_REGISTRAR_KEY';
+/**
+ * A company gets a registrar while it has customers (the people its own apps sign in) or its Boule runs apps
+ * (F5: any company that installs an app with sign-in, `org.boule.apps`).
+ */
+export const registrarWanted = (org) => org.customers?.enabled === true || appsOn(org);
+/** The broker's base as Boule calls it: `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`. */
+export const registrarUrl = (issuer) => `${issuer.replace(/\/+$/, '')}/api`;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -163,7 +180,11 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_ARCHON_CREDENTIAL_ENV,
     BOULE_CUSTOMERS_ORG_ENV,
     BOULE_CUSTOMERS_CREDENTIAL_ENV,
+    BOULE_TEST_CUSTOMERS_ORG_ENV,
+    'CUSTOMER_GRANTS',
     SIGN_IN_UPSTREAM_ENV,
+    AUTH_REGISTRAR_URL_ENV,
+    AUTH_REGISTRAR_KEY_ENV,
 ];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
@@ -218,6 +239,14 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = f
     const customersOrgId = wants.customersDirectory ? customersOrgIdOf(org, recorded) : undefined;
     if (customersOrgId)
         env[BOULE_CUSTOMERS_ORG_ENV] = customersOrgId;
+    const testCustomersOrgId = wants.customersDirectory
+        ? recorded[testCustomersOrgKey(org.id)]
+        : undefined;
+    if (testCustomersOrgId)
+        env[BOULE_TEST_CUSTOMERS_ORG_ENV] = testCustomersOrgId;
+    // The key itself is a secret the executor writes; the plan compares it by presence (`bouleRegistrarDrift`).
+    if (wants.registrar && issuer)
+        env[AUTH_REGISTRAR_URL_ENV] = registrarUrl(issuer);
     const owner = org.owners[0];
     const ownerUserId = owner
         ? recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`]
@@ -355,5 +384,9 @@ export function planBouleOwners(org, recorded, liveBouleEnv) {
 export function staleCustomersEnv(org, live) {
     if (org.customers?.enabled)
         return [];
-    return [BOULE_CUSTOMERS_ORG_ENV, BOULE_CUSTOMERS_CREDENTIAL_ENV].filter((key) => live[key] !== undefined);
+    return [
+        BOULE_CUSTOMERS_ORG_ENV,
+        BOULE_TEST_CUSTOMERS_ORG_ENV,
+        BOULE_CUSTOMERS_CREDENTIAL_ENV,
+    ].filter((key) => live[key] !== undefined);
 }