@wtfalch/foundry 0.46.0 → 0.48.0

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

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { sharedSecretRef } from '../org.js';
 import { applyBlueGreenServer } from './blue-green-apply.js';
-import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, bgKey, healthTokenName, lbOrigin, splitServers, } from './blue-green.js';
+import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, actionsKeyName, bgKey, healthTokenName, lbOrigin, mintActionsKey, splitServers, } from './blue-green.js';
 /**
  * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is
  * blue; green, the balancer and stage are new apps beside it on the primary server. The tunnel moves to the
@@ -58,6 +58,20 @@ export async function applyArchonBlueGreen(run) {
         primaryBlueAppId: run.blueAppId,
         logDir: run.logDir,
         isRunning: run.isRunning,
+        adoptRunningBlue: true,
+        actionsKey: async () => {
+            const key = await mintActionsKey({
+                id,
+                ref: sharedSecretRef(run.ownerOrgId, actionsKeyName(id)),
+                recorded: run.recorded,
+                record: run.record,
+                persist: run.persist,
+                heldKeys: run.heldKeys,
+                generate: () => randomBytes(32).toString('base64'),
+                secret: run.secret,
+            });
+            return key;
+        },
     };
     await applyBlueGreenServer(deps, subject, { uuid: primary, primaryUuid: primary });
     // The structure is applied and every part ran: now, and only now, the tunnel moves.

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

@@ -3,6 +3,7 @@ import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
 import type { TunnelPort } from './edge-tunnels.js';
 import type { CoolifyPort } from './executor.js';
+import { type StageGuardDeps } from './stage-guards.js';
 /** The Coolify calls this module makes. */
 type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
     listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
@@ -31,6 +32,21 @@ export interface BlueGreenApplyDeps {
     primaryBlueAppId: string;
     logDir: string;
     isRunning: (status: string | undefined) => boolean;
+    /**
+     * The primary blue is the process running this apply (platform-archon). Its first apply writes the reporting
+     * env but does not redeploy it: a restart would cut the apply, and the env is read at its next start.
+     */
+    adoptRunningBlue?: boolean;
+    /**
+     * The subject's server actions key (held, minted once). Blue and green are built with it; stage gets a key of
+     * its own. Absent: no key is set.
+     */
+    actionsKey?: () => Promise<string>;
+    /**
+     * What stage's guards need from the host: the probe port and the Access gate. A missing part leaves that
+     * guard unrecorded ("not run", never passed), so `stageGuardsReady` stays false and the copy does not start.
+     */
+    stageGuards?: StageGuardDeps;
 }
 /** What writing a balancer's config needs; {@link BlueGreenApplyDeps} and the release runner both have it. */
 export interface LbConfigDeps {
@@ -60,6 +76,25 @@ export declare function applyBlueGreenWeights(deps: LbConfigDeps, subject: BlueG
     uuid: string;
     primaryUuid: string;
 }): Promise<void>;
+/**
+ * The primary blue's env for another color: the database host swapped when the server is not the primary, and
+ * never the reporting names or the actions key, which differ by design. The structure apply and a deploy both
+ * copy through this, so a color is never deployed with an older copy than the structure apply wrote.
+ */
+export declare function copiedEnv(deps: {
+    label: string;
+    secret: (value: string) => void;
+}, subject: Pick<BlueGreenSubject, 'base'>, source: Array<{
+    key: string;
+    value?: string;
+    is_preview?: boolean;
+}>, server: {
+    uuid: string;
+    primaryUuid: string;
+}): Array<{
+    key: string;
+    value: string;
+}>;
 /** A connector for the org's tunnel on each given server; the primary's is the existing one. */
 export declare function applyBlueGreenConnectors(input: {
     coolify: Parameters<typeof ensureConnectorsOnServers>[0]['coolify'];

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

@@ -1,10 +1,13 @@
 import { randomBytes } from 'node:crypto';
-import { COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, renderLbConfig, reportingEnv, stageAppName, structureHash, } from './blue-green.js';
+import { ACTIONS_KEY_ENV, COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, prodResources, renderLbConfig, reportingEnv, stageAppName, stageAppUrl, stageKindOf, stageResources, structureHash, } from './blue-green.js';
 import { recordBuiltCommit } from './build-record.js';
 import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { waitForNewDeployment } from './deploy-health.js';
 import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
 import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
+import { buildStageEnv } from './stage-env.js';
+import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
+import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
 /** Env names whose value is a credential: registered before they are copied. */
 const SECRETISH = /(KEY|SECRET|TOKEN|PASSWORD|DATABASE_URL)/;
 /** The env names that name the database. */
@@ -35,10 +38,16 @@ export async function applyBlueGreenServer(deps, subject, server) {
     if (!weights)
         throw new Error(`${deps.label}: the recorded weights are not valid`);
     const ids = {};
-    if (isPrimary)
+    if (isPrimary) {
         ids.blue = deps.primaryBlueAppId;
+        // A merge must not redeploy blue past the release runner.
+        await coolify.updateApplication(deps.primaryBlueAppId, { is_auto_deploy_enabled: false });
+    }
     const sourceEnv = await coolify.listEnvs(deps.primaryBlueAppId);
-    const token = await deps.healthToken();
+    const token = subject.reporting ? await deps.healthToken() : null;
+    const actionsKey = subject.reporting && deps.actionsKey ? await deps.actionsKey() : null;
+    if (actionsKey)
+        deps.secret(actionsKey);
     for (const color of COLORS) {
         const name = isPrimary && color === 'blue' ? subject.primaryBlueName : colorAppName(subject.base, color);
         if (!ids[color]) {
@@ -53,12 +62,20 @@ export async function applyBlueGreenServer(deps, subject, server) {
         const appId = ids[color];
         const copied = isPrimary && color === 'blue' ? [] : copiedEnv(deps, subject, sourceEnv, server);
         const release = deps.recorded()[bgKey.digest(id, color)];
-        const reporting = reportingEnv({ color, release, healthToken: token });
+        const reporting = token === null ? [] : reportingEnv({ color, release, healthToken: token });
         // A running color reads its reporting env at start: when it changed, the color restarts before the
         // tunnel can move to it.
         const reportingChanged = await reportingEnvDiffers(deps, appId, reporting);
-        await upsertEnv(deps, appId, [...copied, ...reporting]);
-        await ensureDeployed(deps, appId, name, reportingChanged);
+        await upsertEnv(deps, appId, [
+            ...copied,
+            ...reporting,
+            ...(actionsKey ? [{ key: ACTIONS_KEY_ENV, value: actionsKey, buildTime: true }] : []),
+        ]);
+        const adoptingBlue = deps.adoptRunningBlue === true &&
+            isPrimary &&
+            color === 'blue' &&
+            !deps.recorded()[bgKey.applied(id, server.uuid)];
+        await ensureDeployed(deps, appId, name, reportingChanged && !adoptingBlue);
     }
     const lbName = lbAppName(subject.base);
     const lbId = await ensureLoadBalancer(deps, subject, server.uuid, lbName, isPrimary);
@@ -103,16 +120,24 @@ async function writeLbConfig(deps, subject, server, lbId, weights) {
     deps.record(bgKey.lb(subject.id, server.uuid), formatWeights(weights));
     await deps.persist();
 }
-/** The primary blue's env for another color: the database host swapped when the server is not the primary. */
-function copiedEnv(deps, subject, source, server) {
+/**
+ * The primary blue's env for another color: the database host swapped when the server is not the primary, and
+ * never the reporting names or the actions key, which differ by design. The structure apply and a deploy both
+ * copy through this, so a color is never deployed with an older copy than the structure apply wrote.
+ */
+export function copiedEnv(deps, subject, source, server) {
     const sidecar = server.uuid === server.primaryUuid
         ? null
         : remoteDatabaseHost(subject.base, server.uuid, server.primaryUuid);
     const dbHost = sidecar ? remoteDatabaseAddress(sidecar) : null;
     const out = [];
     for (const env of source) {
-        if (env.is_preview || env.value === undefined || env.key.startsWith('REPORTING_'))
+        if (env.is_preview ||
+            env.value === undefined ||
+            env.key.startsWith('REPORTING_') ||
+            env.key === ACTIONS_KEY_ENV) {
             continue;
+        }
         let value = env.value;
         if (dbHost && DATABASE_ENV.has(env.key)) {
             const swapped = withDatabaseHost(value, dbHost);
@@ -149,6 +174,8 @@ async function ensureGitApp(deps, subject, input) {
         ports_exposes: String(subject.port),
         git_branch: input.branch,
         is_preview_deployments_enabled: false,
+        is_auto_deploy_enabled: input.autoDeploy,
+        ...(subject.dockerfileLocation ? { dockerfile_location: subject.dockerfileLocation } : {}),
         ...(subject.folder === null ? {} : { base_directory: `/${subject.folder}` }),
     };
     const recorded = deps.recorded()[input.key];
@@ -188,6 +215,7 @@ async function ensureGitApp(deps, subject, input) {
         ports_exposes: isStatic ? '80' : String(subject.port),
         is_auto_deploy_enabled: input.autoDeploy,
         base_directory: subject.folder === null ? undefined : `/${subject.folder}`,
+        ...(subject.dockerfileLocation ? { dockerfile_location: subject.dockerfileLocation } : {}),
     });
     // Recorded before anything else is written, so a later failure never leaves an app nothing points at.
     deps.record(input.key, created.uuid);
@@ -273,12 +301,12 @@ async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
     }
     return lbId;
 }
-/** The stage app and its own empty database, on the primary. Holds no env from the live app. */
+/** 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) {
     const { coolify } = deps;
     const name = stageAppName(subject.base);
     const appId = await stageAppId(deps, subject, name, serverUuid);
-    const envs = [{ key: 'LOG_DIR', value: deps.logDir }];
+    const database = [];
     if (subject.database) {
         const dbName = `${subject.base}-stage-db`;
         const pgName = dbName.replace(/-/g, '_');
@@ -302,7 +330,7 @@ async function ensureStage(deps, subject, serverUuid) {
         const db = await coolify.getDatabase(dbId);
         if (db.internal_db_url) {
             deps.secret(db.internal_db_url);
-            envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
+            database.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
             const have = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview);
             if (!have) {
                 const password = randomBytes(24).toString('base64url');
@@ -310,21 +338,144 @@ async function ensureStage(deps, subject, serverUuid) {
                 const runtime = runtimeDatabaseUrl(db.internal_db_url, `${pgName}_rt`, password);
                 if (runtime) {
                     deps.secret(runtime);
-                    envs.push({ key: 'DATABASE_URL', value: runtime });
+                    database.push({ key: 'DATABASE_URL', value: runtime });
                 }
             }
         }
     }
-    // Stage never holds the live app's keys or secrets: its env is the log directory and its own database.
-    await upsertEnv(deps, appId, envs);
+    const kind = stageKindOf(subject);
+    const prodEnv = 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),
+        logDir: deps.logDir,
+        database,
+        prod: prodEnv,
+        existing: await coolify.listEnvs(appId),
+        mint: () => {
+            const value = randomBytes(32).toString('base64url');
+            deps.secret(value);
+            return value;
+        },
+    });
+    const stageEnv = [...env];
+    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);
+        const key = have?.value || randomBytes(32).toString('base64');
+        deps.secret(key);
+        stageEnv.push({ key: ACTIONS_KEY_ENV, value: key, buildTime: true });
+    }
+    const stageSurface = {
+        env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+        resources: stageResources(subject),
+    };
+    const violations = assertStageIsolated({
+        kind,
+        prod: {
+            env: [...prodEnv, ...greenEnv]
+                .filter((e) => !e.is_preview && e.value !== undefined)
+                .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+            resources: prodResources(subject),
+            internalHosts: Object.values(prodResources(subject)),
+        },
+        stage: stageSurface,
+    });
+    if (violations.length > 0) {
+        // Stage fails closed for itself: nothing is written to it, production's structure goes on.
+        await stageFailed(deps, subject, `blocked:${violations.join(',')}`);
+        return;
+    }
+    // Stage's credentials are tried against production before they are written; one that production accepts
+    // blocks stage (nothing is written to it), and what was tried is recorded by name so the copy slice sees it.
+    const stageValues = new Map((await coolify.listEnvs(appId))
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    for (const e of stageEnv)
+        stageValues.set(e.key, e.value);
+    const isolationHash = stageIsolationHash(stageSurface);
+    let probeResult;
+    try {
+        probeResult = await runStageProbes(buildStageProbes({
+            port: deps.stageGuards?.probes,
+            stage: stageValues,
+            database: subject.database,
+            prod: new Map(prodEnv
+                .filter((e) => !e.is_preview && e.value !== undefined)
+                .map((e) => [e.key, e.value])),
+        }));
+    }
+    catch (error) {
+        // A connection URL that cannot be read: stage is blocked, production goes on.
+        await stageFailed(deps, subject, 'blocked:database', error);
+        return;
+    }
+    const probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    if (probeResult.failed.length > 0) {
+        deps.record(bgKey.stageProbes(subject.id), probes.value);
+        await stageFailed(deps, subject, `blocked:${probeResult.failed.join(',')}`);
+        return;
+    }
+    if (!(await ensureStageGate(deps, subject))) {
+        await stageFailed(deps, subject, 'blocked:gate');
+        return;
+    }
+    await upsertEnv(deps, appId, stageEnv);
+    deps.record(bgKey.stageIsolation(subject.id), isolationHash);
+    deps.record(bgKey.stageProbes(subject.id), probes.value);
+    await deps.persist();
     const live = await coolify.getApplication(appId);
     if (live.status === undefined || !deps.isRunning(live.status)) {
-        const built = await waitForNewDeployment(coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+        // Stage is a test copy: a failed build or health check must not fail production's structure apply.
+        // The next apply retries it (the plan keeps the step while the state is `unhealthy`).
+        let built;
+        try {
+            built = await waitForNewDeployment(coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+        }
+        catch (error) {
+            await stageFailed(deps, subject, 'unhealthy', error);
+            return;
+        }
         await recordBuiltCommit(coolify, { appId, deploymentUuid: built.deploymentUuid, name: subject.id }, (key, value) => {
             if (key.startsWith('built_commit_'))
                 deps.record(bgKey.stage(subject.id), value);
         });
     }
+    deps.record(bgKey.stageState(subject.id), 'ok');
+    await deps.persist();
+}
+/**
+ * Stage fails closed for itself only: its state is recorded and the apply of production goes on. The log line is
+ * fixed text and the error name; the cause can echo a credential, so it is never logged.
+ */
+async function stageFailed(deps, subject, state, error) {
+    const name = error === undefined ? 'refused' : error instanceof Error ? error.name : 'unknown';
+    console.error(`${deps.label}: stage is ${state.split(':')[0]} (${name}); production goes on`);
+    deps.record(bgKey.stageState(subject.id), state);
+    await deps.persist();
+}
+/**
+ * The Access gate over the stage host, made once. `false` when making it failed: stage is then blocked and not
+ * written to. No gate dependency: nothing is recorded (not run) and stage goes on.
+ */
+async function ensureStageGate(deps, subject) {
+    const gate = deps.stageGuards?.gate;
+    if (!gate || deps.recorded()[bgKey.stageGate(subject.id)])
+        return true;
+    let id;
+    try {
+        id = (await gate.create()).id;
+    }
+    catch (error) {
+        // An Access error can echo the request, which names the people allowed in: only its name is logged.
+        console.error(`${deps.label}: making the Access gate failed (${error instanceof Error ? error.name : 'unknown'})`);
+        return false;
+    }
+    deps.record(bgKey.stageGate(subject.id), id);
+    await deps.persist();
+    return true;
 }
 async function stageAppId(deps, subject, name, serverUuid) {
     return ensureGitApp(deps, subject, {

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

@@ -1,4 +1,5 @@
 import type { BlueGreenConfig, DeclaredOrg, 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
  * ({@link Colored}), not something only a hosting entry has: platform-archon uses the same code path
@@ -38,11 +39,21 @@ export declare const bgKey: {
     app: (id: string, server: string, part: string) => string;
     /** The cloudflared connector app of the tunnel on a non-primary `server`. */
     connector: (id: string, server: string) => string;
+    /** The held ref of the server actions key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    actionsKey: (id: string) => string;
     stageDatabase: (id: string) => string;
+    /** `ok`, `unhealthy` (build or health check failed) or `blocked:<reason names>` (a guard refused; stage was not written to). */
+    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. */
     pinKey: (id: string) => string;
+    /** The hash of the stage env name set and resource set that passed the isolation check. */
+    stageIsolation: (id: string) => string;
+    /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
+    stageGate: (id: string) => string;
+    /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
+    stageProbes: (id: string) => string;
 };
 /** The three env names the reporting health read uses (contract C1). */
 export declare const REPORTING_ENV: {
@@ -50,6 +61,30 @@ export declare const REPORTING_ENV: {
     readonly release: "REPORTING_RELEASE";
     readonly healthToken: "REPORTING_HEALTH_TOKEN";
 };
+/** Next.js server action ids differ between builds unless every color is built with the same key. */
+export declare const ACTIONS_KEY_ENV = "NEXT_SERVER_ACTIONS_ENCRYPTION_KEY";
+/** The held-key name of a subject's server actions key: one mint per subject, shared by blue and green only. */
+export declare const actionsKeyName: (id: string) => string;
+/**
+ * One mint of the server actions key (CLAUDE.md, Platform steps, rule 1). The key goes to the held store, then its
+ * ref is recorded under {@link bgKey.actionsKey} and persisted, and only then is it returned for any env. A later
+ * apply reuses the held key; when the ref is recorded but the key is no longer held it stops, never mints again.
+ * The error names the ref only.
+ */
+export declare function mintActionsKey(input: {
+    id: string;
+    ref: string;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    heldKeys: {
+        resolve(ref: string): Promise<string | null>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    generate: () => string;
+    /** Registers the value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+}): Promise<string>;
 /** 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. */
@@ -83,12 +118,54 @@ export interface BlueGreenSubject {
     /** The hostnames the tunnel routes to the balancer. */
     hostnames: string[];
     config: BlueGreenConfig;
+    /** The scope key that records the Coolify app of the blue copy (the app the subject runs as today). */
+    blueAppKey: string;
+    /** The Dockerfile in the repo, when it is not the root one. */
+    dockerfileLocation?: string;
+    /**
+     * Whether the app serves the reporting health read. A static app does not: its release uses hard fails only
+     * (address check, crash loop) and moves up by time.
+     */
+    reporting: boolean;
+    /** Set for Boule and Agora, 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';
+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: {
+    readonly boule: {
+        readonly repo: "wtfalch/boule";
+        readonly dockerfile: "/Dockerfile";
+        readonly port: 3000;
+        readonly healthPath: "/api/health";
+        readonly database: true;
+        readonly reporting: true;
+    };
+    readonly agora: {
+        readonly repo: "wtfalch/agora";
+        readonly dockerfile: "/apps/agora/Dockerfile";
+        readonly port: 8080;
+        readonly healthPath: "/";
+        readonly database: false;
+        readonly reporting: false;
+    };
+};
 /**
  * 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}).
  */
 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.
+ */
+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. */
+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;
 /**
  * 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
@@ -147,8 +224,11 @@ export interface UnmanagedLine {
 }
 export interface BlueGreenPlanStep {
     kind: 'bluegreen' | 'bluegreen-lb' | 'bluegreen-connector';
-    /** `before`: ahead of the tunnel step, so its route finds a running balancer. `after`: needs the tunnel. */
-    phase: 'before' | 'after';
+    /**
+     * `before`: ahead of the tunnel step, so its route finds a running balancer. `after`: needs the tunnel.
+     * `last`: after Boule's and Agora's own steps, which make the blue app a built-in subject copies.
+     */
+    phase: 'before' | 'after' | 'last';
     key: string;
     description: string;
     desired: Record<string, unknown>;
@@ -157,6 +237,19 @@ export interface BlueGreenPlanStep {
 export declare function structureHash(subject: BlueGreenSubject, input: {
     primary: boolean;
 }): string;
+/** The kind of stage app a subject has: platform-archon, else a customer app. */
+export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id">) => StageKind;
+/** The names stage can collide on. */
+export declare function stageResources(subject: BlueGreenSubject): Record<string, string>;
+/** The names of the subject's live parts: stage must equal none of them. */
+export declare function prodResources(subject: BlueGreenSubject): Record<string, string>;
+/** The address of a stage app inside its network: it has no hostname. */
+export declare const stageAppUrl: (subject: Pick<BlueGreenSubject, "base" | "port">) => string;
+/**
+ * The violations of stage isolation that need no live values: the stage env names the builder gives, and the
+ * names stage and the org's other apps hold. Names only.
+ */
+export declare function stagePlanViolations(subject: BlueGreenSubject, otherApps: readonly string[]): string[];
 /** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
 export declare function namesNotBlueGreen(org: DeclaredOrg): string[];
 export interface PlanBlueGreenInput {
@@ -168,6 +261,8 @@ export interface PlanBlueGreenInput {
     canHoldSecrets: boolean;
     /** The entry's app step is planned in this run (it makes the blue copy this step copies from). */
     appPlanned: (entryKey: string) => boolean;
+    /** The platform's recorded Access provider, which the stage gate requires. Absent: no gate is made. */
+    accessProviderId?: string | null;
 }
 /**
  * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the