@wtfalch/foundry 0.46.0 → 0.48.0

package/dist/plan/providers-readers.js

@@ -280,12 +280,23 @@ async function withBouleEnvConfig(client, resource, recorded, liveKeys) {
     // Boule must hold too. In memory only, compared by `planBoule` and never
     // written to a step, description or log.
     const orgId = recorded[resource.key]?.slice('boule:'.length);
-    const appUuid = Object.entries(recorded).find(([, value]) => value === `app:${orgId}:${APP_ENTRY_KEY}`)?.[0];
+    // The token sits on the org's main app, whatever its key; the reader does not know the
+    // declaration, so it tries the `app` entry first and then each other recorded app.
+    const appPrefix = `app:${orgId}:`;
+    const appUuids = Object.entries(recorded)
+        .filter(([, value]) => value.startsWith(appPrefix))
+        .sort(([, a], [, b]) => Number(b === `${appPrefix}${APP_ENTRY_KEY}`) - Number(a === `${appPrefix}${APP_ENTRY_KEY}`))
+        .map(([uuid]) => uuid);
     // A recorded app that is not in the live listing is gone: no app token, and
     // no read of its envs. A listed app whose read fails fails like any read.
-    const appToken = appUuid && liveKeys.has(appUuid)
-        ? (await client.listEnvs(appUuid)).find((e) => !e.is_preview && e.key === BOULE_MAIL_TOKEN_ENV)?.value
-        : undefined;
+    let appToken;
+    for (const appUuid of appUuids) {
+        if (!liveKeys.has(appUuid))
+            continue;
+        appToken = (await client.listEnvs(appUuid)).find((e) => !e.is_preview && e.key === BOULE_MAIL_TOKEN_ENV)?.value;
+        if (appToken)
+            break;
+    }
     return {
         ...resource,
         config: { ...resource.config, env, ...(appToken ? { appMailToken: appToken } : {}) },

package/dist/plan/proxy-labels.d.ts

@@ -51,7 +51,19 @@ export declare function entryRoutes(org: DeclaredOrg, recorded?: Readonly<Record
     hostname: string;
     service: string;
 }>;
-/** The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}. */
+/**
+ * The tunnel routes of the company's Boule and Agora that run behind a balancer: their names go to it once the
+ * structure on the primary is applied. Until then (and for an app that does not declare blue/green) a name keeps
+ * the Coolify proxy origin it had, so none appears here.
+ */
+export declare function builtinRoutes(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): Array<{
+    hostname: string;
+    service: string;
+}>;
+/**
+ * The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}.
+ * A built-in app's balancer route is added only when there is one, so a company without it keeps its marker.
+ */
 export declare function entryRoutesMarker(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): string;
 /**
  * A short digest of the spec; the same spec always gives the same hash. The token is left out: the

package/dist/plan/proxy-labels.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { PRIMARY_SERVER_SCOPE_KEY, balancerApplied, lbAppName, liveAppNameFor, } from './blue-green.js';
+import { BUILTIN_APPS, PRIMARY_SERVER_SCOPE_KEY, balancerApplied, builtinSubject, lbAppName, lbOrigin, liveAppNameFor, } from './blue-green.js';
 import { entryHostnames, wildcardHostname } from './hostnames.js';
 import { NO_DOMAIN_ZONE } from './own-hostnames.js';
 import { appNameFor } from './platform-diff.js';
@@ -85,9 +85,32 @@ export function entryRoutes(org, recorded = {}) {
         routes.push(wildcard);
     return routes;
 }
-/** The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}. */
+/**
+ * The tunnel routes of the company's Boule and Agora that run behind a balancer: their names go to it once the
+ * structure on the primary is applied. Until then (and for an app that does not declare blue/green) a name keeps
+ * the Coolify proxy origin it had, so none appears here.
+ */
+export function builtinRoutes(org, recorded = {}) {
+    const routes = [];
+    for (const app of BUILTIN_APPS) {
+        const subject = builtinSubject(org, app, recorded);
+        if (!subject || !balancerApplied(subject.id, recorded, recorded[PRIMARY_SERVER_SCOPE_KEY])) {
+            continue;
+        }
+        for (const hostname of subject.hostnames) {
+            routes.push({ hostname, service: lbOrigin(subject) });
+        }
+    }
+    return routes;
+}
+/**
+ * The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}.
+ * A built-in app's balancer route is added only when there is one, so a company without it keeps its marker.
+ */
 export function entryRoutesMarker(org, recorded = {}) {
-    return JSON.stringify(entryRoutes(org, recorded));
+    const builtin = builtinRoutes(org, recorded);
+    const routes = entryRoutes(org, recorded);
+    return JSON.stringify(builtin.length > 0 ? [...routes, ...builtin] : routes);
 }
 /**
  * A short digest of the spec; the same spec always gives the same hash. The token is left out: the

package/dist/plan/release-host.d.ts

@@ -21,7 +21,7 @@ export interface ReleaseHost {
 export interface ReleaseHostInput {
     subject: BlueGreenSubject;
     context: ReleaseContext;
-    coolify: Pick<CoolifyPort, 'getApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'deployAndWait' | 'raw' | 'listStorages' | 'createFileStorage' | 'updateFileStorage'> & {
+    coolify: Pick<CoolifyPort, 'getApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deployAndWait' | 'raw' | 'listStorages' | 'createFileStorage' | 'updateFileStorage'> & {
         listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
     };
     /** Reads the entry's health token (`sharedSecretRef(org.id, healthTokenName(id))`). Never mints. */

package/dist/plan/release-host.js

@@ -1,6 +1,6 @@
 import { checkColorAddress, readReleaseHealth } from '../release/health.js';
 import { runRelease } from '../release/run.js';
-import { applyBlueGreenWeights } from './blue-green-apply.js';
+import { applyBlueGreenWeights, copiedEnv } from './blue-green-apply.js';
 import { DEFAULT_WEIGHTS, LB_COLOR_HEADER, LB_PIN_HEADER, bgKey, formatWeights, parseWeights, reportingEnv, } from './blue-green.js';
 import { waitForNewDeployment } from './deploy-health.js';
 import { isNotFoundError } from './executor.js';
@@ -19,21 +19,23 @@ export function createReleaseHost(input) {
     const id = subject.id;
     const recorded = () => context.recordedIds();
     /** Every Coolify app of `color`, one per server that has the structure applied. */
-    const colorApps = (color) => {
+    const colorAppsOnServers = (color) => {
         const ids = recorded();
         const apps = [];
         if (color === 'blue')
-            apps.push(input.primaryBlueAppId);
+            apps.push({ appId: input.primaryBlueAppId, server: input.primaryUuid });
         const prefix = `bg.${id}.app.`;
         for (const key of Object.keys(ids).sort()) {
             if (!key.startsWith(prefix) || !key.endsWith(`.${color}`))
                 continue;
             const value = ids[key];
+            const server = key.slice(prefix.length, key.length - color.length - 1);
             if (value)
-                apps.push(value);
+                apps.push({ appId: value, server });
         }
         return apps;
     };
+    const colorApps = (color) => colorAppsOnServers(color).map((a) => a.appId);
     const primaryColorApp = (color) => color === 'blue' ? input.primaryBlueAppId : recorded()[bgKey.app(id, input.primaryUuid, color)];
     /**
      * Where the runner reaches a color: the entry's first public hostname, pinned to the color by the balancer's
@@ -66,21 +68,39 @@ export function createReleaseHost(input) {
     const deployTo = async (color, digest) => {
         if (!COMMIT.test(digest))
             throw new Error(`${input.label}: the release is not a built commit`);
-        const token = await input.healthToken();
-        if (!token)
-            throw new Error(`${input.label}: the health token is not held`);
-        input.secret(token);
-        const apps = colorApps(color);
+        const token = subject.reporting ? await input.healthToken() : null;
+        if (subject.reporting) {
+            if (!token)
+                throw new Error(`${input.label}: the health token is not held`);
+            input.secret(token);
+        }
+        const apps = colorAppsOnServers(color);
         if (apps.length === 0)
             throw new Error(`${input.label}: ${color} has no app recorded`);
-        for (const appId of apps) {
+        for (const { appId, server } of apps) {
             await input.renew();
             await coolify.updateApplication(appId, { git_commit_sha: digest });
+            // The color takes blue's env as it is now, so a change made after the structure apply (sign-in, mail,
+            // credentials) reaches it before it serves. Blue on the primary is the source itself.
+            let source = [];
+            if (appId !== input.primaryBlueAppId) {
+                try {
+                    source = await coolify.listEnvs(input.primaryBlueAppId);
+                }
+                catch {
+                    throw new Error(`${input.label}: reading the env of the blue app failed`);
+                }
+            }
+            const refreshed = copiedEnv({ label: input.label, secret: input.secret }, subject, source, {
+                uuid: server,
+                primaryUuid: input.primaryUuid,
+            });
+            const reporting = token ? reportingEnv({ color, release: digest, healthToken: token }) : [];
             try {
-                await coolify.bulkUpsertEnvs(appId, reportingEnv({ color, release: digest, healthToken: token }).map((e) => ({
-                    ...e,
-                    literal: true,
-                })));
+                const envs = [...refreshed, ...reporting];
+                if (envs.length > 0) {
+                    await coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
+                }
             }
             catch {
                 // A Coolify error can echo the request body, which holds the token.
@@ -128,6 +148,7 @@ export function createReleaseHost(input) {
                 address: await checkColorAddress({
                     ...addressOf(color),
                     healthPath: subject.healthPath,
+                    expectJson: subject.reporting && subject.healthPath === '/api/health',
                     ...(input.fetch ? { fetchImpl: input.fetch } : {}),
                 }),
             };
@@ -221,6 +242,7 @@ export async function runSubjectRelease(input) {
         entry: subject.config,
         now: input.now,
         deps: input.host.deps,
+        ...(subject.reporting ? {} : { hardOnly: true }),
     });
     for (const [key, value] of Object.entries(result.writes)) {
         if (value === null)

package/dist/plan/stage-env.d.ts

@@ -0,0 +1,38 @@
+import { type StageKind } from './stage-isolation.js';
+export interface StageEnvInput {
+    kind: StageKind;
+    /** Where the stage app is reached: its own container address, since stage has no hostname. */
+    appUrl: string;
+    logDir: string;
+    /** The stage database's URLs, already minted for stage. */
+    database: ReadonlyArray<{
+        key: string;
+        value: string;
+    }>;
+    /** The env of the live app. Read for the names it uses, and for the values on `SHARED_WITH_PROD`; nothing else is copied. */
+    prod: ReadonlyArray<{
+        key: string;
+        value?: string;
+        is_preview?: boolean;
+    }>;
+    /** The env stage holds now: a minted secret is kept, so a second apply does not rotate it. */
+    existing: ReadonlyArray<{
+        key: string;
+        value?: string;
+        is_preview?: boolean;
+    }>;
+    mint: () => string;
+}
+export interface StageEnv {
+    env: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** Names the live app uses that stage does not get yet. A service is either in `env` or here. */
+    absent: string[];
+}
+/**
+ * The env of a stage app, built from the kind's allowlist and never from a copy of the live app's env. Every
+ * name is allowed and none is denied, or this throws a fixed text with the name.
+ */
+export declare function buildStageEnv(input: StageEnvInput): StageEnv;

package/dist/plan/stage-env.js

@@ -0,0 +1,52 @@
+import { STAGE_ALLOWLIST, isAllowed, isDenied, isSharedWithProd, } from './stage-isolation.js';
+/** Prod names whose stage value waits for the stage's own organisation or project: absent until then. */
+const WAITS_FOR_STAGE_SERVICE = new Set([
+    'FILES_URL',
+    'AI_URL',
+    'JOBS_SCHEDULER_URL',
+    'ANALYTICS_URL',
+]);
+/** Secrets stage mints for itself, when the app uses them. A copy of prod's value would be a prod credential. */
+const MINTED = ['AUTH_COOKIE_SECRET', 'KEYSTORE_KEK'];
+/**
+ * The env of a stage app, built from the kind's allowlist and never from a copy of the live app's env. Every
+ * name is allowed and none is denied, or this throws a fixed text with the name.
+ */
+export function buildStageEnv(input) {
+    const { kind } = input;
+    const live = (list) => new Map(list
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    const prod = live(input.prod);
+    const existing = live(input.existing);
+    const env = new Map();
+    const set = (key, value) => {
+        if (isDenied(kind, key) || !isAllowed(kind, key)) {
+            throw new Error(`stage env: ${key} is not allowed for a ${kind} stage`);
+        }
+        env.set(key, value);
+    };
+    set('LOG_DIR', input.logDir);
+    if (isAllowed(kind, 'APP_URL'))
+        set('APP_URL', input.appUrl);
+    if (isAllowed(kind, 'APP_ENVIRONMENT'))
+        set('APP_ENVIRONMENT', 'stage');
+    for (const { key, value } of input.database)
+        set(key, value);
+    for (const [key, value] of prod) {
+        if (!env.has(key) &&
+            isSharedWithProd(key) &&
+            isAllowed(kind, key) &&
+            !WAITS_FOR_STAGE_SERVICE.has(key)) {
+            set(key, value);
+        }
+    }
+    for (const key of MINTED) {
+        if (prod.has(key) && isAllowed(kind, key))
+            set(key, existing.get(key) ?? input.mint());
+    }
+    const absent = STAGE_ALLOWLIST[kind]
+        .filter((name) => !name.endsWith('*') && prod.has(name) && !env.has(name))
+        .sort();
+    return { env: [...env].map(([key, value]) => ({ key, value })), absent };
+}

package/dist/plan/stage-guards.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
+ * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
+ * this file returns, logs or throws a value: errors and results carry fixed text and names.
+ */
+/** Milliseconds one probe may take. A probe that does not answer in time is not a rejection. */
+export declare const STAGE_PROBE_TIMEOUT_MS = 10000;
+/**
+ * The calls the host makes to prove a stage credential does not work against production. Every method answers
+ * `true` when production REFUSED the credential, `false` when it accepted it. A method the host does not
+ * implement leaves that probe "not run". No method ever returns a value.
+ */
+export interface StageProbePort {
+    /** Logs in to the production database host with the stage role and password. */
+    databaseRejects?(input: {
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+    }): Promise<boolean>;
+    /** Uses the stage files key on production's organisation. */
+    filesRejects?(input: {
+        url: string;
+        apiKey: string;
+        organisationId: string;
+    }): Promise<boolean>;
+    /** Uses the stage ai key on production's organisation. */
+    aiRejects?(input: {
+        url: string;
+        apiKey: string;
+        organisationId: string;
+    }): Promise<boolean>;
+    /** Uses the stage jobs key on production's project. */
+    jobsRejects?(input: {
+        url: string;
+        syncKey: string;
+        projectId: string;
+    }): Promise<boolean>;
+}
+/** One probe. `run` is `null` when the host has no port for it: the probe is then reported as not run. */
+export interface StageProbe {
+    what: string;
+    /** `true`: production rejected the stage credential. */
+    run: (() => Promise<boolean>) | null;
+}
+export interface StageProbeInput {
+    port: StageProbePort | undefined;
+    /** The env stage will hold. */
+    stage: ReadonlyMap<string, string>;
+    /** The env of the live app. */
+    prod: ReadonlyMap<string, string>;
+    /** Whether stage has a database: if no database probe can be built, one is kept as not run. */
+    database?: boolean;
+}
+/**
+ * The probes for what stage holds: its database role against production's database host, and its files, ai and
+ * jobs keys against production's organisation or project, each only where stage has the key and production
+ * names the target. A probe whose port method is missing is kept with `run: null`.
+ */
+export declare function buildStageProbes(input: StageProbeInput): StageProbe[];
+export interface StageProbeResult {
+    /** Names of the probes production rejected. */
+    rejected: string[];
+    /** Names of the probes that were accepted, threw or timed out: the apply fails on these. */
+    failed: string[];
+    /** Names of the probes with no port: reported as not run, never as passed. */
+    notRun: string[];
+}
+/** Runs every probe once, each under a timeout. A throw and a timeout count as failed, never as rejected. */
+export declare function runStageProbes(probes: readonly StageProbe[], options?: {
+    timeoutMs?: number;
+}): Promise<StageProbeResult>;
+/**
+ * What `bg.<id>.stageprobes` holds: `ok:<hash>` when every probe ran and was rejected (the hash covers the
+ * stage env names, the sha256 of each stage secret and URL value, and the probe names, so a changed stage
+ * credential invalidates it), `notrun:<names>` when a probe had no port, `failed:<names>` when one was accepted.
+ */
+export declare function stageProbesRecord(result: StageProbeResult, isolationHash: string, stage: ReadonlyMap<string, string>): {
+    value: string;
+    ok: boolean;
+};
+/** The Access gate stage's host sits behind: made once, staff only, recorded as `bg.<id>.stagegate`. */
+export interface StageGate {
+    /** The stage host the gate covers. */
+    hostname: string;
+    /** Makes the gate (no bypass and no service-token rule) and returns its id. */
+    create: () => Promise<{
+        id: string;
+    }>;
+}
+export interface StageGuardDeps {
+    probes?: StageProbePort;
+    gate?: StageGate;
+}
+/** The key of the stage gate in the company (a DNS label, like a declared gate's). */
+export declare const stageGateKey: (id: string) => string;
+/** The hostname stage is served at: under the company's domain, never a name production uses. */
+export declare const stageHostname: (domain: string, id: string) => string;
+/** Why stage guards are not ready, or `[]`. Names only; the copy slice calls this before it reads production. */
+export declare function stageGuardsReady(recorded: Readonly<Record<string, string>>, id: string): {
+    ready: boolean;
+    missing: string[];
+};

package/dist/plan/stage-guards.js

@@ -0,0 +1,149 @@
+import { createHash } from 'node:crypto';
+import { bgKey } from './blue-green.js';
+import { envClass } from './stage-isolation.js';
+/**
+ * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
+ * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
+ * this file returns, logs or throws a value: errors and results carry fixed text and names.
+ */
+/** Milliseconds one probe may take. A probe that does not answer in time is not a rejection. */
+export const STAGE_PROBE_TIMEOUT_MS = 10_000;
+const DB_URL = /^[a-z][a-z0-9+.-]*:\/\/([^:@/]*):([^@/]*)@([^/:?#]+)(?::(\d+))?\/([^?#]*)/i;
+function parseDatabaseUrl(name, value) {
+    const match = DB_URL.exec(value);
+    if (!match)
+        throw new Error(`stage probes: ${name} is not a connection URL`);
+    return {
+        user: decodeURIComponent(match[1]),
+        password: decodeURIComponent(match[2]),
+        host: match[3],
+        port: match[4] ? Number(match[4]) : 5432,
+        database: match[5],
+    };
+}
+/**
+ * The probes for what stage holds: its database role against production's database host, and its files, ai and
+ * jobs keys against production's organisation or project, each only where stage has the key and production
+ * names the target. A probe whose port method is missing is kept with `run: null`.
+ */
+export function buildStageProbes(input) {
+    const { port, stage, prod, database } = input;
+    const probes = [];
+    const stageUrl = stage.get('DATABASE_URL');
+    const prodUrl = prod.get('DATABASE_URL_OWNER') ?? prod.get('DATABASE_URL');
+    if (stageUrl && prodUrl) {
+        const from = parseDatabaseUrl('DATABASE_URL', stageUrl);
+        const to = parseDatabaseUrl('the live database URL', prodUrl);
+        const call = port?.databaseRejects?.bind(port);
+        probes.push({
+            what: 'database:stage-role-on-prod-host',
+            run: call
+                ? () => call({
+                    host: to.host,
+                    port: to.port,
+                    database: to.database,
+                    user: from.user,
+                    password: from.password,
+                })
+                : null,
+        });
+    }
+    if (database && !(stageUrl && prodUrl)) {
+        // Stage has a database but a URL could not be read: the guard is not run, never passed.
+        probes.push({ what: 'database', run: null });
+    }
+    for (const [what, urlName, keyName, orgName, method] of [
+        ['files:stage-key-on-prod-org', 'FILES_URL', 'FILES_API_KEY', 'FILES_ORGANISATION_ID', 'files'],
+        ['ai:stage-key-on-prod-org', 'AI_URL', 'AI_API_KEY', 'AI_ORGANISATION_ID', 'ai'],
+    ]) {
+        const url = stage.get(urlName);
+        const apiKey = stage.get(keyName);
+        const organisationId = prod.get(orgName);
+        if (!url || !apiKey || !organisationId)
+            continue;
+        const call = (method === 'files' ? port?.filesRejects : port?.aiRejects)?.bind(port);
+        probes.push({
+            what,
+            run: call ? () => call({ url, apiKey, organisationId }) : null,
+        });
+    }
+    const jobsUrl = stage.get('JOBS_SCHEDULER_URL');
+    const syncKey = stage.get('JOBS_SYNC_KEY');
+    const projectId = prod.get('JOBS_PROJECT_ID');
+    if (jobsUrl && syncKey && projectId) {
+        const call = port?.jobsRejects?.bind(port);
+        probes.push({
+            what: 'jobs:stage-key-on-prod-project',
+            run: call ? () => call({ url: jobsUrl, syncKey, projectId }) : null,
+        });
+    }
+    return probes;
+}
+/** Runs every probe once, each under a timeout. A throw and a timeout count as failed, never as rejected. */
+export async function runStageProbes(probes, options = {}) {
+    const timeoutMs = options.timeoutMs ?? STAGE_PROBE_TIMEOUT_MS;
+    const out = { rejected: [], failed: [], notRun: [] };
+    for (const probe of probes) {
+        if (!probe.run) {
+            out.notRun.push(probe.what);
+            continue;
+        }
+        let timer;
+        try {
+            const rejected = await Promise.race([
+                probe.run(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+                }),
+            ]);
+            (rejected === true ? out.rejected : out.failed).push(probe.what);
+        }
+        catch {
+            // The cause can echo the credential; the name is all the report needs.
+            out.failed.push(probe.what);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    return out;
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * What `bg.<id>.stageprobes` holds: `ok:<hash>` when every probe ran and was rejected (the hash covers the
+ * stage env names, the sha256 of each stage secret and URL value, and the probe names, so a changed stage
+ * credential invalidates it), `notrun:<names>` when a probe had no port, `failed:<names>` when one was accepted.
+ */
+export function stageProbesRecord(result, isolationHash, stage) {
+    if (result.failed.length > 0)
+        return { value: `failed:${result.failed.join(',')}`, ok: false };
+    if (result.notRun.length > 0)
+        return { value: `notrun:${result.notRun.join(',')}`, ok: false };
+    const credentials = [...stage]
+        .filter(([name]) => envClass(name) === 'secret' || envClass(name) === 'url')
+        .map(([name, value]) => `${name}=${sha256(value)}`)
+        .sort();
+    return {
+        value: `ok:${sha256(`${isolationHash}:${result.rejected.join(',')}:${credentials.join(',')}`)}`,
+        ok: true,
+    };
+}
+/** The key of the stage gate in the company (a DNS label, like a declared gate's). */
+export const stageGateKey = (id) => `stage-${id}`;
+/** The hostname stage is served at: under the company's domain, never a name production uses. */
+export const stageHostname = (domain, id) => `stage-${id}.${domain}`;
+/** Why stage guards are not ready, or `[]`. Names only; the copy slice calls this before it reads production. */
+export function stageGuardsReady(recorded, id) {
+    const missing = [];
+    if (!recorded[bgKey.stageIsolation(id)])
+        missing.push('stageisolation');
+    if (!recorded[bgKey.stageGate(id)])
+        missing.push('stagegate');
+    if (!recorded[bgKey.stageProbes(id)]?.startsWith('ok:'))
+        missing.push('stageprobes');
+    // An older ok: record outlives a later block; the stage state says what the last apply found.
+    if (recorded[bgKey.stageState(id)] !== 'ok')
+        missing.push('stagestate');
+    return { ready: missing.length === 0, missing };
+}

package/dist/plan/stage-isolation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The stage-isolation check (campaign T3 section 4). Stage must hold no credential that reaches production,
+ * so this runs before stage gets any env and again when the plan is made. It returns violation names only:
+ * a violation names an env var or a resource kind, never a value.
+ */
+export type StageKind = 'boule' | 'agora' | 'archon' | 'customer';
+export type EnvClass = 'secret' | 'url' | 'id' | 'literal';
+export interface SurfaceEnv {
+    name: string;
+    class: EnvClass;
+    /** The value, where the caller holds it. */
+    value?: string;
+    /** A reference to the value, where the caller holds only that (plan time). */
+    ref?: string;
+}
+/** What one side (production or stage) holds. */
+export interface Surface {
+    env: SurfaceEnv[];
+    /** Every name the side can collide on: app, database and role names, hostnames, container names. */
+    resources: Record<string, string>;
+    /** Internal hosts a stage URL must not name (prod database container, sidecar, balancer, platform apps). */
+    internalHosts?: readonly string[];
+}
+/** The class of an env name, from its spelling. */
+export declare function envClass(name: string): EnvClass;
+/** Env names (or `PREFIX_*`) each kind of stage app may hold. A name not here is refused. */
+export declare const STAGE_ALLOWLIST: Record<StageKind, readonly string[]>;
+/** Whether `name` is on the deny list of `kind`. */
+export declare function isDenied(kind: StageKind, name: string): boolean;
+/** Whether `name` is on the allowlist of `kind`. Mail names are checked by A5 only. */
+export declare function isAllowed(kind: StageKind, name: string): boolean;
+/**
+ * Env that stage holds with the same value as production, on purpose. Each entry says why that cannot write
+ * to production. A name not here must differ from every production value.
+ */
+export declare const SHARED_WITH_PROD: Readonly<Record<string, string>>;
+/** Whether `name` may equal production's value. */
+export declare const isSharedWithProd: (name: string) => boolean;
+export interface StageIsolationInput {
+    kind: StageKind;
+    prod: Surface;
+    stage: Surface;
+    /** The mail env stage is allowed to hold: the sink's wiring. Empty: stage holds no mail env. */
+    sinkMail?: Readonly<Record<string, string>>;
+}
+/**
+ * The violations of stage isolation, as `<code>:<name>`; empty when stage is isolated. Names only: an env
+ * name or a resource kind, never a value.
+ *  - A1 allowlist: `env_not_allowed`. A2 deny list: `env_denied`.
+ *  - A3 values: `value_shared` (a secret, url or id equals a production value), `shared_differs` (a name on
+ *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
+ *  - A4 names: `resource_shared`, `host_is_prod_internal`.
+ *  - A5 mail: `mail_not_sink`, `mail_token`.
+ */
+export declare function assertStageIsolated(input: StageIsolationInput): string[];
+/** The sha256 of the stage env name set plus the resource set: what `bg.<id>.stageisolation` records. */
+export declare function stageIsolationHash(stage: Surface): string;