@wtfalch/foundry 0.62.0 → 0.63.0

package/dist/plan/blue-green.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
 import { kosmosOn } from '../org.js';
-import { agoraHostnameFor } from './agora.js';
+import { ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { serverConnectorScopeKey } from './cloudflared-connector.js';
 import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
@@ -9,6 +9,7 @@ import { kosmosHostnameFor } from './kosmos.js';
 import { appNameFor, appStepKey } from './platform-diff.js';
 import { remoteDatabaseAppliedFor } from './remote-database.js';
 import { buildStageEnv } from './stage-env.js';
+import { stageHostname } from './stage-guards.js';
 import { assertStageIsolated, envClass } from './stage-isolation.js';
 import { STAGE_SINK_VERSION } from './stage-sink.js';
 export const COLORS = ['blue', 'green'];
@@ -40,6 +41,8 @@ export const bgKey = {
     digest: (id, color) => `bg.${id}.digest.${color}`,
     weights: (id) => `bg.${id}.weights`,
     stage: (id) => `bg.${id}.stage`,
+    /** The last `deploy_stage`: `<ISO time>|ok|<commit>` or `<ISO time>|failed|<step>`. */
+    stageDeploy: (id) => `bg.${id}.stagedeploy`,
     window: (id) => `bg.${id}.window`,
     held: (id, digest) => `bg.${id}.held.${digest}`,
     /** The weights the load balancer on `server` was last written with. */
@@ -66,8 +69,29 @@ export const bgKey = {
     stageIsolation: (id) => `bg.${id}.stageisolation`,
     /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
     stageGate: (id) => `bg.${id}.stagegate`,
+    /** The hash of the sorted email list last written to the stage gate (owners plus the people holding `releases:preview`). */
+    stageGateMembers: (id) => `bg.${id}.stagegatemembers`,
     /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
     stageProbes: (id) => `bg.${id}.stageprobes`,
+    /** Stage's own sign-in client: its ZITADEL app id, and its client id (public, not a secret). */
+    stageClient: (id) => `bg.${id}.stageclient`,
+    stageClientId: (id) => `bg.${id}.stageclientid`,
+    /** The held ref of stage's app key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    stageSignInKey: (id) => `bg.${id}.stagesigninkey`,
+    /** `{name, organizationId}` of stage's broker entry, so org destroy can remove it. No key. */
+    stageBroker: (id) => `bg.${id}.stagebroker`,
+    /** `ok:<hash of the client, app and broker entry ids>` or `none`; the copy waits for it. */
+    stageSignIn: (id) => `bg.${id}.stagesignin`,
+    /** `none` (production's app uses no files, ai or jobs) or `ok:<hash>` once every service it uses is held by stage or listed absent. */
+    stageServices: (id) => `bg.${id}.stageservices`,
+    /** `ok:<hash of the ids>` or `absent:<service>:<reason>` for one service (`files`, `ai` or `jobs`). */
+    stageService: (id, service) => `bg.${id}.stage${service}`,
+    /** The id of stage's own organisation (files, ai) or project (jobs). An id, not a secret. */
+    stageServiceOrg: (id, service) => `bg.${id}.stage${service}org`,
+    /** The name stage's project or organisation was made under, when the service is deleted by name (jobs). */
+    stageServiceName: (id, service) => `bg.${id}.stage${service}name`,
+    /** `{ids, refs}` of stage's keys in that service: key ids and held refs, never a value. */
+    stageServiceKeys: (id, service) => `bg.${id}.stage${service}keys`,
     /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
     stageSink: (id) => `bg.${id}.stagesink`,
     /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
@@ -437,12 +461,42 @@ export function structureHash(subject, input) {
         primary: input.primary,
         lb: VERSIONS.traefik,
         ...(input.primary ? { stageSink: STAGE_SINK_VERSION } : {}),
+        // Only a primary has a stage, and only a present guard counts: no guard hashes as before.
+        ...(input.primary && input.guards?.length ? { stageGuards: [...input.guards].sort() } : {}),
     }))
         .digest('hex')
         .slice(0, 16);
 }
-/** The kind of stage app a subject has: platform-archon, else a customer app. */
-export const stageKindOf = (subject) => subject.id === ARCHON_SUBJECT_ID ? 'archon' : 'customer';
+/**
+ * The kind of stage app a subject has: Boule and Agora by `builtin` (a hosting entry that happens to be keyed
+ * `boule` is still a customer app), platform-archon by its id, else a customer app (kosmos included: it has no lists of its own).
+ */
+export const stageKindOf = (subject) => subject.builtin === 'boule' || subject.builtin === 'agora'
+    ? subject.builtin
+    : subject.id === ARCHON_SUBJECT_ID
+        ? 'archon'
+        : 'customer';
+/**
+ * The stage guards that can be made now, by name. The names go into the applied structure hash, so a guard
+ * that becomes possible after the first apply changes the hash and plans the structure step once more.
+ */
+export function stageGuardInputs(facts) {
+    const out = [];
+    if (facts.probesPort)
+        out.push('probes');
+    if (facts.accessPort &&
+        facts.providerId &&
+        facts.domain &&
+        facts.claimValue &&
+        facts.emails > 0 &&
+        !facts.hostRuled) {
+        out.push('gate');
+    }
+    return out;
+}
+/** The guard names as the plan's `desired.guards` carries them, and back. */
+export const formatGuards = (guards) => [...guards].sort().join(',');
+export const parseGuards = (value) => typeof value === 'string' && value ? value.split(',') : [];
 /** The names stage can collide on. */
 export function stageResources(subject) {
     const database = `${subject.base}-stage-db`;
@@ -623,10 +677,22 @@ export function planBlueGreen(input) {
                 key: `bg:${id}:stage`,
             });
         }
+        // The guards that can be made now go into the applied hash: one that becomes possible after the first
+        // apply (a provider, a probe port, an owner) changes the hash and plans the structure step once more.
+        const stageHost = org.domain ? stageHostname(org.domain, id) : null;
+        const guards = stageGuardInputs({
+            probesPort: input.stageGuardPorts?.probes === true,
+            accessPort: input.stageGuardPorts?.access === true,
+            providerId: input.accessProviderId,
+            domain: org.domain,
+            claimValue: recordedIds[ZITADEL_ORG_SCOPE_KEY],
+            emails: org.owners.length,
+            hostRuled: (org.hosting.access ?? []).some((rule) => rule.hostname === stageHost),
+        });
         for (const server of targets) {
             const isPrimary = server === primary;
             const key = `${org.id}:${id}:${server}`;
-            const hash = structureHash(subject, { primary: isPrimary });
+            const hash = structureHash(subject, { primary: isPrimary, guards });
             if (!isPrimary && subject.database && !remoteDatabaseAppliedFor(recordedIds, id, server)) {
                 unmanaged.push({
                     description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${server} yet: its database route to that server is not applied`,
@@ -651,6 +717,7 @@ export function planBlueGreen(input) {
                         primary,
                         weights: formatWeights(weights),
                         ...(input.accessProviderId ? { accessProviderId: input.accessProviderId } : {}),
+                        ...(isPrimary && guards.length > 0 ? { guards: formatGuards(guards) } : {}),
                     },
                 });
             }
@@ -749,7 +816,9 @@ export function planArchonBlueGreen(input) {
     if (!primary || !up.includes(primary)) {
         return blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
     }
-    const done = recorded[bgKey.applied(subject.id, primary)] === structureHash(subject, { primary: true }) &&
+    const guards = input.guards ?? [];
+    const done = recorded[bgKey.applied(subject.id, primary)] ===
+        structureHash(subject, { primary: true, guards }) &&
         recorded[bgKey.lb(subject.id, primary)] === formatWeights(weights) &&
         recorded[ARCHON_BG_ORIGIN_SCOPE_KEY] === lbOrigin(subject);
     if (done)
@@ -761,7 +830,12 @@ export function planArchonBlueGreen(input) {
             phase: 'after',
             key: subject.id,
             description: `run platform-archon as blue and green behind a load balancer on Coolify server ${primary}, then send its tunnel to the balancer`,
-            desired: { subject: subject.id, primary, weights: formatWeights(weights) },
+            desired: {
+                subject: subject.id,
+                primary,
+                weights: formatWeights(weights),
+                ...(guards.length > 0 ? { guards: formatGuards(guards) } : {}),
+            },
         },
     };
 }

package/dist/plan/boule.d.ts

@@ -154,7 +154,7 @@ export declare const registrarWanted: (org: Pick<DeclaredOrg, "customers" | "bou
 /** 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", "TEST_CUSTOMERS_ORGANISATION_ID", "CUSTOMER_GRANTS", "SIGNIN_UPSTREAM", "AUTH_REGISTRAR_URL", "AUTH_REGISTRAR_KEY"];
+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", "NATIVE_BUILD_KEY", "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,3 +1,4 @@
+import { NATIVE_BUILD_KEY_ENV } from '../native-build.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';
@@ -176,6 +177,7 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_PEER_PASSWORD_ENV,
     BOULE_BRIDGE_SECRET_ENV,
     BOULE_OWNER_SEED_SECRET_ENV,
+    NATIVE_BUILD_KEY_ENV,
     BOULE_ARCHON_ORG_ID_ENV,
     BOULE_ARCHON_CREDENTIAL_ENV,
     BOULE_CUSTOMERS_ORG_ENV,

package/dist/plan/broker-entries.d.ts

@@ -178,3 +178,12 @@ export declare function writeBrokerEntry(broker: BrokerPort, input: {
     invalidForeign: string[];
     replaced: string | null;
 }>;
+/**
+ * Takes one entry (and so its key) out of the broker's `AUTH_APPS`, matched by name and organisation, and
+ * deploys the broker when the list changed. Every other entry is copied back as it was. An entry that is
+ * already gone writes nothing. Errors name the entry, never a key.
+ */
+export declare function removeBrokerEntry(broker: BrokerPort, input: {
+    name: string;
+    organizationId: string;
+}): Promise<boolean>;

package/dist/plan/broker-entries.js

@@ -373,3 +373,32 @@ export async function writeBrokerEntry(broker, input) {
         replaced: replaced.length > 0 ? JSON.stringify(replaced) : null,
     };
 }
+/**
+ * Takes one entry (and so its key) out of the broker's `AUTH_APPS`, matched by name and organisation, and
+ * deploys the broker when the list changed. Every other entry is copied back as it was. An entry that is
+ * already gone writes nothing. Errors name the entry, never a key.
+ */
+export async function removeBrokerEntry(broker, input) {
+    const label = `broker entry '${input.name}'`;
+    const env = (await broker.listEnvs()).find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
+    if (!env?.value)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(env.value);
+    }
+    catch {
+        throw new Error(`${label}: the broker's AUTH_APPS is not JSON, so nothing was removed`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${label}: the broker's AUTH_APPS is not a JSON array, so nothing was removed`);
+    }
+    const next = parsed.filter((entry) => !(isObject(entry) &&
+        entry.name === input.name &&
+        entry.organizationId === input.organizationId));
+    if (next.length === parsed.length)
+        return false;
+    await broker.setAuthApps(JSON.stringify(next));
+    await broker.deploy();
+    return true;
+}

package/dist/plan/diff.d.ts

@@ -150,6 +150,11 @@ export interface PlanOrgOptions {
     blueGreenServers?: readonly BlueGreenServer[];
     /** The company's stage mail sink is recorded and its live app is stopped or gone. */
     stageSinkDown?: boolean;
+    /** Which stage-guard ports the host has ({@link PlanBlueGreenInput.stageGuardPorts}). */
+    stageGuardPorts?: {
+        probes: boolean;
+        access: boolean;
+    };
 }
 export interface PlanDetail {
     orgId: OrgId;

package/dist/plan/diff.js

@@ -1,4 +1,5 @@
 import { VERSIONS } from '../bootstrap/versions.js';
+import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
 import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, heldEnvRef, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, entryClientIdScopeKey, withRecordedMessagingProject, } from './agora.js';
@@ -568,6 +569,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
         accessProviderId: platformReadiness.accessProviderId ?? null,
         ...(options.stageSinkDown ? { stageSinkDown: true } : {}),
+        ...(options.stageGuardPorts ? { stageGuardPorts: options.stageGuardPorts } : {}),
         appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
             p.action.kind === 'app' &&
             p.action.key === appStepKey(org, entryKey)),
@@ -3386,6 +3388,8 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
         drift.push(BOULE_BRIDGE_SECRET_ENV);
     if (!liveEnv[BOULE_OWNER_SEED_SECRET_ENV])
         drift.push(BOULE_OWNER_SEED_SECRET_ENV);
+    if (!liveEnv[NATIVE_BUILD_KEY_ENV])
+        drift.push(NATIVE_BUILD_KEY_ENV);
     // Secrets written but Boule not restarted since: plan the step so it restarts, minting nothing.
     if (platformOwner && !recordedIds[BOULE_SECRETS_RESTARTED_SCOPE_KEY]) {
         drift.push('restart after the peer password and bridge secret');

package/dist/plan/edge-access.d.ts

@@ -87,9 +87,8 @@ export interface AccessPort {
     }>;
     replaceGateHostnames(gateId: string, hostnames: string[]): Promise<void>;
     /**
-     * Replaces the whole list of people who pass a gate; nothing else about the gate changes. Edge's platform
-     * client has no such call yet, so {@link createEdgeAccess} does not implement it: a host that wants a
-     * workspace's testers to change supplies a port that does (edge's company `gates.setPeople`).
+     * Replaces the whole list of people who pass a gate; nothing else about the gate changes. The edge adapter
+     * implements it with edge's platform `setGatePeople`; a host may supply its own port instead.
      */
     setGatePeople?(gateId: string, emails: string[]): Promise<void>;
     /** Deletes the gate with its application, policy and list; a gate already gone is done. */

package/dist/plan/edge-access.js

@@ -167,6 +167,13 @@ export function createEdgeAccess(client, options = {}) {
         async replaceGateHostnames(gateId, hostnames) {
             await writeSlot(() => access.replaceGateHostnames(gateId, { hostnames }));
         },
+        ...(typeof client.setGatePeople === 'function'
+            ? {
+                async setGatePeople(gateId, emails) {
+                    await writeSlot(() => access.setGatePeople(gateId, { emails }));
+                },
+            }
+            : {}),
         async readiness() {
             const { authDomain } = await access.readiness();
             return { authDomain };

package/dist/plan/executor.d.ts

@@ -21,7 +21,8 @@ import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor }
 import type { EdgePortName } from './platform-org.js';
 import type { RequestHeaderPort } from './platform-providers.js';
 import { type ReleaseContext, type ReleaseHost } from './release-host.js';
-import { type StageProbePort } from './stage-guards.js';
+import { type StageCopyHostConfig } from './stage-copy-host.js';
+import { type ReleasePreviewMembers, type StageProbePort } from './stage-guards.js';
 import type { WorkerAppDatabasePort } from './worker-app-database.js';
 import { type KeysCustodyPort, type WorkerAppPort } from './worker-app.js';
 export declare function coolifyProjectMark(org: Pick<DeclaredOrg, 'id'>): string;
@@ -1411,6 +1412,11 @@ export interface FilesOrganisationPort {
      * the list is a no-op.
      */
     ensureAllowedOrigin(organisationId: string, origin: string): Promise<void>;
+    /**
+     * Deletes an organisation with its keys. Optional: used only by org destroy for stage's own organisation
+     * (`<org>-stage`); a port without it leaves that organisation, which destroy then reports as blocked.
+     */
+    deleteOrganisation?(organisationId: string): Promise<void>;
 }
 /**
  * Provisions one org's organisation on AI and switches its AI use on (#80),
@@ -1519,6 +1525,11 @@ export interface AiOrganisationPort {
         keyId: string | null;
         limitMicros: string;
     }): Promise<unknown>;
+    /**
+     * Deletes an organisation with its keys and budget. Optional: used only by org destroy for stage's own
+     * organisation (`<org>-stage`); a port without it leaves that organisation, which destroy then reports as blocked.
+     */
+    deleteOrganisation?(organisationId: string): Promise<void>;
 }
 /**
  * #317 (F7): the edge service's own management API
@@ -1634,6 +1645,11 @@ export interface JobsSchedulerPort {
         secret?: string;
         syncKey?: string;
     }>;
+    /**
+     * Removes a project and its keys (`DELETE /admin/projects/<name>`). Optional: used only by org destroy for
+     * stage's own project (`<org>-stage`); a port without it leaves that project, which destroy then reports as blocked.
+     */
+    deleteProject?(name: string): Promise<void>;
 }
 /**
  * #177: where the org steps' files, AI and jobs ports come from when the host
@@ -1746,6 +1762,18 @@ export interface FoundryStepExecutorPorts {
      * one the probes are reported as not run, and the stage copy stays blocked.
      */
     stageProbes?: StageProbePort;
+    /**
+     * The stage copy (`copy_prod_to_stage`, run by the release tick). The host supplies the dump download and the
+     * backup storage; foundry builds the restore port itself and reads production's address live from Coolify.
+     * Without it a copy request is refused with `no-copy-port`. The host needs `pg_restore` (Postgres 16) on PATH.
+     */
+    stageCopy?: StageCopyHostConfig;
+    /**
+     * Who may open an org's stage gate besides its owners: the people holding `releases:preview` in `orgId`. Read on
+     * each release tick (10 s limit) and when the gate is made; a failed read leaves the gate as it is. Without it
+     * the gate keeps the owners it was made with.
+     */
+    releasePreviewMembers?: ReleasePreviewMembers;
     /**
      * F4.ratelimits: overrides the rate limiting rule calls, which otherwise go through
      * `edge.ratelimits` (see {@link EdgePort.ratelimits}). Kept for a host or a test that supplies its own.
@@ -2436,8 +2464,18 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * blue copy is not recorded. The health token is only read here, never minted.
      */
     releaseHost(org: DeclaredOrg, subject: BlueGreenSubject, context: ReleaseContext, renew: () => Promise<void>): ReleaseHost | null;
+    /**
+     * The copy's ports for one subject. Production's database is the org's (`coolify:database:<org id>`) for an
+     * entry and Boule's own for Boule; Agora has none, so its copy is refused with `no-production-database`.
+     */
+    private stageCopyFor;
     /** Whether the stage mail sink app is stopped or gone, read live. A failed read throws; the caller reads that as up. */
     stageSinkDown(appId: string): Promise<boolean>;
+    /** Which stage-guard ports this executor has, for the planner (they decide the guard names in the applied hash). */
+    stageGuardPorts(): {
+        probes: boolean;
+        access: boolean;
+    };
     /** Every server Coolify lists with whether it is usable and reachable, for the planner. */
     blueGreenServers(): Promise<BlueGreenServer[]>;
     /**
@@ -2505,6 +2543,25 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * bypass or service-token rule there would open stage, so no gate is made and the guard stays unrecorded.
      */
     private stageGuards;
+    /**
+     * One release tick for one subject: its recorded stage gate's list follows the people holding
+     * `releases:preview`, owners always staying (`syncStageGateMembers`). Never throws.
+     */
+    syncStageGateMembers(org: DeclaredOrg, subject: BlueGreenSubject, context: ReleaseContext): Promise<void>;
+    /**
+     * Stage's own files organisation, ai organisation and jobs project (`plan/stage-services.ts`), each named
+     * for its subject (`<org id>-stage-<subject id>`, `<slug>-stage-<subject id>`: one per subject, as the recorded keys are) and built from the same ports production's steps use. A service whose port is
+     * missing or not ready answers `available() === false`, and stage then records it absent and mints nothing.
+     */
+    private stageServicesPort;
+    /**
+     * Stage's own sign-in (`plan/stage-signin.ts`): a client named `<production client>-stage` on production's
+     * sign-in organisation and project with redirect URIs on the stage host only, a broker entry
+     * `<production entry>-stage` with a key of its own, and that key's held ref. `{ required: false }` for an entry
+     * that does not sign in. `undefined`, with one fixed log line saying why, when something it needs is missing:
+     * the guard then stays unrecorded and the copy waits. Platform-archon is not covered yet.
+     */
+    private stageSignInPort;
     private coolifyApp;
     /**
      * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
@@ -2711,7 +2768,20 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensurePeerPassword;
     /** Same rule for the secret Archon's invite form sends to Boule. */
     private ensureBridgeSecret;
+    /**
+     * `minLength`, when given, also counts a present-but-empty value as not set -- the same guard
+     * {@link ensureAuthAppKey} already applies for `AUTH_APP_KEY`, now reusable here instead of a
+     * third, bare copy of this check (foundry#970, thermo note 1 in #957). Omitted, the three existing
+     * callers below keep their original behaviour.
+     */
     private mintIfAbsent;
+    /**
+     * Every company's Boule, F3/#970: `NATIVE_BUILD_KEY` is what Boule presents to Archon's
+     * native-build route (estate#262) to ask it to dispatch `build-app.yml`. Minted once, like
+     * {@link ensureAuthAppKey}, and never rotated; a present-but-empty value (the bug
+     * `mintNativeBuildKey`'s own read-then-generate had, see #957) is treated as not set.
+     */
+    private ensureNativeBuildKey;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a