@wtfalch/foundry 0.72.3 → 0.74.0

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export { StaleLeaseError } from './store.js';
 export type { PlanApply, DestroyProgress } from './apply.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
-export type { Color, ReleaseAction, ReleaseEvent, ReleaseEventKind, ReleaseSeries, ReleaseSeriesColor, ReleaseSignal, ReleaseState, WindowState, } from './release/types.js';
+export type { Color, ReleaseAction, ReleaseEvent, ReleaseEventKind, ReleaseSeries, ReleaseSeriesColor, ReleaseRequirement, ReleaseSignal, ReleaseState, ReleasedVersion, WindowState, } from './release/types.js';
 export type { ReleaseStore } from './release/state.js';
-export { readReleaseHistory, readReleaseState, requestReleaseAction } from './release/state.js';
+export { readReleaseHistory, readReleasedVersions, readReleaseState, requestReleaseAction, rescheduleRelease, } from './release/state.js';
 export type { BuiltinFanOut, FanOutApp, FanOutOrgState } from './release/fanout.js';
 export { readBuiltinFanOut } from './release/fanout.js';
 export type { ReleaseSeriesHost, ReleaseSeriesQuery } from './release/series.js';

package/dist/index.js

@@ -14,7 +14,7 @@ export { NATIVE_BUILD_REPO, NATIVE_BUILD_WORKFLOW_FILE, NATIVE_BUILD_WORKFLOW_RE
 export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
-export { readReleaseHistory, readReleaseState, requestReleaseAction } from './release/state.js';
+export { readReleaseHistory, readReleasedVersions, readReleaseState, requestReleaseAction, rescheduleRelease, } from './release/state.js';
 export { readBuiltinFanOut } from './release/fanout.js';
 export { readReleaseSeries } from './release/series.js';
 export { readEntryReleaseSeries } from './plan/release-series-reader.js';

package/dist/migrations/0071_release_request_schedule.sql

@@ -0,0 +1,12 @@
+-- @wtfalch/foundry: a release request can wait for a time. `not_before` is null for every request made
+-- until now, so each of them stays due at once. The release runner reads only the open rows whose time has come.
+-- `claimed_at` is set when the runner starts a due go-live: from then on it can no longer be cancelled or moved.
+-- Additive: two nullable columns and one partial index; no existing row is touched.
+-- Mirrors src/store/schema.ts's `foundryReleaseRequests`.
+
+alter table foundry_release_requests add column if not exists not_before timestamptz;
+alter table foundry_release_requests add column if not exists claimed_at timestamptz;
+
+create index if not exists foundry_release_requests_scheduled_idx
+  on foundry_release_requests (org_id, entry_key, not_before)
+  where consumed_at is null and not_before is not null;

package/dist/plan/plan-apply.js

@@ -1207,6 +1207,8 @@ export class FoundryPlanApply {
                 host,
                 context,
                 now: this.now(),
+                nowFn: () => this.now(),
+                ...(ownerOrgId !== null ? { ownerOrgId } : {}),
                 primaryUuid,
                 ...(copies === 'defer' ? { deferCopies: true } : {}),
             });
@@ -1248,6 +1250,7 @@ export class FoundryPlanApply {
             host,
             context,
             now: this.now(),
+            nowFn: () => this.now(),
             primaryUuid,
             ...(copies === 'defer' ? { deferCopies: true } : {}),
         });

package/dist/plan/platform-diff.d.ts

@@ -70,13 +70,14 @@ export declare const AUTH_TUNNEL_ROUTES_VERSION = "2";
 export declare const PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY = "auth_tunnel_routes_applied";
 /**
  * The version of the env `provisionAuthStack` writes to the login apps (`LOGIN_MAIL_FROM`,
- * `LETTERMINT_API_TOKEN`, `LOGIN_PASSKEY_RP_ID`). Raise it when a key is added or its meaning changes, so an applied
+ * `LETTERMINT_API_TOKEN`, `LOGIN_PASSKEY_RP_ID`, `ZITADEL_DOMAIN`, `LOGIN_COMPANY_NAME`). Raise it when a key is added or its meaning changes, so an applied
  * sign-in plans its step once more and the apps get the env. Never holds a value.
  * 1: the login apps send their own invite and verification mail (auth 0.35.0, foundry 0.68.0).
  * 2: a company's login apps get `LOGIN_PASSKEY_RP_ID` (foundry 0.70.2).
  * 3: the login apps get `ZITADEL_DOMAIN` (foundry 0.72.2; written from 0.72.3).
+ * 4: the login apps get `LOGIN_COMPANY_NAME`, the sign-in page's wordmark (foundry 0.73.0).
  */
-export declare const AUTH_LOGIN_ENV_VERSION = "3";
+export declare const AUTH_LOGIN_ENV_VERSION = "4";
 /**
  * What the login apps' env is written for: the version, the sender address (`LOGIN_MAIL_FROM`) and the
  * passkey RP ID (`LOGIN_PASSKEY_RP_ID`, none for the platform and a company without its own domain).

package/dist/plan/platform-diff.js

@@ -77,13 +77,14 @@ export const AUTH_TUNNEL_ROUTES_VERSION = '2';
 export const PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY = 'auth_tunnel_routes_applied';
 /**
  * The version of the env `provisionAuthStack` writes to the login apps (`LOGIN_MAIL_FROM`,
- * `LETTERMINT_API_TOKEN`, `LOGIN_PASSKEY_RP_ID`). Raise it when a key is added or its meaning changes, so an applied
+ * `LETTERMINT_API_TOKEN`, `LOGIN_PASSKEY_RP_ID`, `ZITADEL_DOMAIN`, `LOGIN_COMPANY_NAME`). Raise it when a key is added or its meaning changes, so an applied
  * sign-in plans its step once more and the apps get the env. Never holds a value.
  * 1: the login apps send their own invite and verification mail (auth 0.35.0, foundry 0.68.0).
  * 2: a company's login apps get `LOGIN_PASSKEY_RP_ID` (foundry 0.70.2).
  * 3: the login apps get `ZITADEL_DOMAIN` (foundry 0.72.2; written from 0.72.3).
+ * 4: the login apps get `LOGIN_COMPANY_NAME`, the sign-in page's wordmark (foundry 0.73.0).
  */
-export const AUTH_LOGIN_ENV_VERSION = '3';
+export const AUTH_LOGIN_ENV_VERSION = '4';
 /**
  * What the login apps' env is written for: the version, the sender address (`LOGIN_MAIL_FROM`) and the
  * passkey RP ID (`LOGIN_PASSKEY_RP_ID`, none for the platform and a company without its own domain).

package/dist/plan/platform-providers.js

@@ -1575,11 +1575,12 @@ const PLATFORM_AUTH_RESERVED_USERNAME = 'admin';
 /** #216 (building on #209/#215): the narrower `IAM_LOGIN_CLIENT` machine user for the login app and the broker. */
 const PLATFORM_AUTH_LOGIN_CLIENT_USER_NAME = 'foundry-login-client';
 export const PLATFORM_AUTH_ORG_NAME = 'foundry';
+const LOGIN_COMPANY_NAME_ENV = 'LOGIN_COMPANY_NAME';
 /**
  * The instance's first organisation (the default one, whose name the login shows as its wordmark).
  * A company's own instance passes the recorded id (the platform passes none and keeps the name `foundry`);
- * found by that id when there is one, because a company's own instance has it renamed to the
- * company's name (`applySigninMail`), and a lookup by name would then make a second `foundry` org. The
+ * found by that id when there is one, because a company's own instance may have it renamed (foundry
+ * before 0.73.0 did), and a lookup by name would then make a second `foundry` org. The
  * name is the way in only before the id is recorded. A recorded id ZITADEL no longer has is a failure,
  * never a reason to make another org.
  */
@@ -2228,6 +2229,11 @@ export async function provisionAuthStack(scope, deps, target, input) {
         },
         // #1086: the login builds redirects for an unbound host from this, never from a header.
         { key: 'ZITADEL_DOMAIN', value: hostname },
+        // The wordmark on the sign-in page: a company's own name, `Archon` for the platform's login.
+        {
+            key: LOGIN_COMPANY_NAME_ENV,
+            value: input.mailBranding ? signinMailName(input.mailBranding.companyName) : 'Archon',
+        },
         { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
         { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
         // #405: the login app's own requestId-free fallback (`resolveRedirectUri`
@@ -2856,17 +2862,12 @@ export async function provisionAuthStack(scope, deps, target, input) {
             (deps.signinMailWritable !== true ||
                 typeof mailZitadel.ensureEmailOtpMessageText !== 'function' ||
                 typeof mailZitadel.ensureLabelPolicy !== 'function' ||
-                typeof mailZitadel.ensureOrgName !== 'function' ||
                 typeof mailZitadel.ensureEmailOtpGenerator !== 'function')) {
             console.info(`${label}: the host cannot write message texts, so the sign-in mail keeps ZITADEL's default text`);
         }
         else if (input.mailBranding) {
-            const firstOrgId = scope.recordedIds()[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
-            if (!firstOrgId) {
-                throw new Error(`${label}: the instance's first organisation is not recorded`);
-            }
             try {
-                await applySigninMail(mailZitadel, input.mailBranding.companyName, firstOrgId);
+                await applySigninMail(mailZitadel, input.mailBranding.companyName);
             }
             catch (error) {
                 const cause = redactSecrets(error instanceof Error ? error.message : String(error), [

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

@@ -84,7 +84,11 @@ export declare function createReleaseHost(input: ReleaseHostInput): ReleaseHost;
  * (like the next apply, through its `bluegreen-lb` step) writes it again.
  */
 export declare function runSubjectRelease(input: {
-    store: Pick<ReleaseStore, 'openRequests' | 'consumeRequests'> & Partial<Pick<ReleaseStore, 'appendEvents'>>;
+    store: Pick<ReleaseStore, 'openRequests' | 'consumeRequests' | 'claimRequests'> & Partial<Pick<ReleaseStore, 'appendEvents'>>;
+    /** `DeclaredPlatform.ownerOrgId`: without it no go_live or set_required request runs. */
+    ownerOrgId?: string;
+    /** The clock for the repeated passes of a go-live; absent: `now` for every pass. */
+    nowFn?: () => Date;
     scopeOwnerId: string;
     subject: BlueGreenSubject;
     host: ReleaseHost;

package/dist/plan/release-host.js

@@ -9,6 +9,9 @@ import { waitForDeploymentFinished, waitForNewDeployment, } from './deploy-healt
 import { isNotFoundError } from './executor.js';
 import { runStageCopyRequest } from './stage-copy-host.js';
 const COMMIT = /^[0-9a-f]{40}$/;
+const APP_RELEASE_ENV = ['APP_TAG', 'APP_RELEASE', 'APP_MINIMUM_RELEASE'];
+/** One tick runs a pending go-live at most this many times (stage, idle, staff, open). */
+const GO_LIVE_RUNS = 4;
 /** A stage deploy waits at most this many polls of this long (10 minutes) for Coolify's deployment to finish. */
 export const STAGE_DEPLOY_ATTEMPTS = 60;
 export const STAGE_DEPLOY_INTERVAL_MS = 10_000;
@@ -109,7 +112,7 @@ export function createReleaseHost(input) {
     const pinInput = () => pinInputOf(input, recorded);
     const addressOf = (color) => colorAddress(input, recorded, color);
     const healthColor = () => healthColorOf(recorded(), id);
-    const deployTo = async (color, digest) => {
+    const deployTo = async (color, digest, appEnv) => {
         if (!COMMIT.test(digest))
             throw new Error(`${input.label}: the release is not a built commit`);
         const token = subject.reporting ? await input.healthToken() : null;
@@ -135,22 +138,40 @@ export function createReleaseHost(input) {
                     throw new Error(`${input.label}: reading the env of the blue app failed`);
                 }
             }
+            // A go-live's own values replace blue's: the color boots with the tag's tag, release and minimum.
             const refreshed = copiedEnv({ label: input.label, secret: input.secret }, subject, source, {
                 uuid: server,
                 primaryUuid: input.primaryUuid,
-            });
+            }).filter((e) => !appEnv || !APP_RELEASE_ENV.includes(e.key));
+            const release = appEnv
+                ? [
+                    { key: 'APP_TAG', value: appEnv.tag },
+                    { key: 'APP_RELEASE', value: String(appEnv.release) },
+                    ...(appEnv.minimum === null
+                        ? []
+                        : [{ key: 'APP_MINIMUM_RELEASE', value: String(appEnv.minimum) }]),
+                ]
+                : [];
             const reporting = token ? reportingEnv({ color, release: digest, healthToken: token }) : [];
             try {
-                const envs = [...refreshed, ...reporting];
+                const envs = [...refreshed, ...reporting, ...release];
                 if (envs.length > 0) {
                     await coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
                 }
                 // A key removed from blue (a rotated-out credential) must not stay on the slot.
-                if (appId !== input.primaryBlueAppId) {
-                    const keep = new Set([...source.map((e) => e.key), ...envs.map((e) => e.key)]);
+                if (appId !== input.primaryBlueAppId || (appEnv && appEnv.minimum === null)) {
+                    const keep = new Set([
+                        ...(appId === input.primaryBlueAppId
+                            ? []
+                            : source
+                                .map((e) => e.key)
+                                .filter((key) => !appEnv || !APP_RELEASE_ENV.includes(key))),
+                        ...envs.map((e) => e.key),
+                    ]);
                     for (const env of await coolify.listEnvs(appId)) {
                         if (env.uuid &&
                             !keep.has(env.key) &&
+                            (appId !== input.primaryBlueAppId || env.key === 'APP_MINIMUM_RELEASE') &&
                             !env.key.startsWith('REPORTING_') &&
                             env.key !== ACTIONS_KEY_ENV) {
                             await coolify.deleteEnv(appId, env.uuid);
@@ -272,7 +293,7 @@ export function createReleaseHost(input) {
         stageCopy: (request) => runStageCopyRequest({ subject, context, ports: input.stageCopy, renew: input.renew }, request),
         async effect(effect) {
             if (effect.kind === 'deploy')
-                await deployTo(effect.color, effect.digest);
+                await deployTo(effect.color, effect.digest, effect.appEnv);
             else if (effect.kind === 'stop')
                 await stop(effect.color);
             else if (effect.kind === 'deploy_stage')
@@ -355,53 +376,81 @@ export async function runSubjectRelease(input) {
             context.recordScopeId(bgKey.weights(id), DEFAULT_WEIGHTS);
         await context.persist();
     }
-    await input.host.refreshStage();
-    const before = ids()[bgKey.weights(id)];
-    const result = await runRelease({
-        store: {
-            getScopeIds: async () => ({ ...ids() }),
-            openRequests: (query) => input.store.openRequests(query),
-        },
-        orgId: input.scopeOwnerId,
-        entryKey: id,
-        entry: subject.config,
-        now: input.now,
-        deps: input.host.deps,
-        ...(subject.reporting ? {} : { hardOnly: true }),
-        ...(input.deferCopies ? { deferCopies: true } : {}),
-    });
-    for (const [key, value] of Object.entries(result.writes)) {
-        if (value === null)
-            context.forgetId(key);
-        else
-            context.recordScopeId(key, value);
-    }
-    await context.persist();
-    if (input.store.appendEvents && result.events.length > 0) {
-        try {
-            await input.store.appendEvents({
-                orgId: input.scopeOwnerId,
-                entryKey: id,
-                events: result.events,
-            });
+    /** Where a go-live stands: it moves when stage, a color's digest or the window changes. */
+    const stand = () => [
+        ids()[bgKey.stage(id)] ?? '',
+        ids()[bgKey.digest(id, 'blue')] ?? '',
+        ids()[bgKey.digest(id, 'green')] ?? '',
+        // A window never written reads as idle, so the first run's own write is not a change.
+        ids()[bgKey.window(id)] ?? '{"kind":"idle"}',
+    ].join('|');
+    const pass = async (now) => {
+        await input.host.refreshStage();
+        const before = ids()[bgKey.weights(id)];
+        const result = await runRelease({
+            store: {
+                getScopeIds: async () => ({ ...ids() }),
+                openRequests: (query) => input.store.openRequests(query),
+                claimRequests: (claim) => input.store.claimRequests(claim),
+            },
+            orgId: input.scopeOwnerId,
+            ...(input.ownerOrgId !== undefined ? { ownerOrgId: input.ownerOrgId } : {}),
+            entryKey: id,
+            entry: subject.config,
+            now,
+            deps: input.host.deps,
+            ...(subject.reporting ? {} : { hardOnly: true }),
+            ...(input.deferCopies ? { deferCopies: true } : {}),
+        });
+        for (const [key, value] of Object.entries(result.writes)) {
+            if (value === null)
+                context.forgetId(key);
+            else
+                context.recordScopeId(key, value);
         }
-        catch {
-            // The history is a record, not a gate: losing a line must not leave the run's requests open to replay.
-            console.error(`release ${id}: recording ${result.events.length} history lines failed`);
+        await context.persist();
+        if (input.store.appendEvents && result.events.length > 0) {
+            try {
+                await input.store.appendEvents({
+                    orgId: input.scopeOwnerId,
+                    entryKey: id,
+                    events: result.events,
+                });
+            }
+            catch {
+                // The history is a record, not a gate: losing a line must not leave the run's requests open to replay.
+                console.error(`release ${id}: recording ${result.events.length} history lines failed`);
+            }
         }
-    }
-    await input.store.consumeRequests(result.requestIds);
-    const after = parseWeights(ids()[bgKey.weights(id)]);
-    // Also when a balancer lags the weights (an earlier write failed), so the next tick retries it.
-    if (after && (formatWeights(after) !== before || balancerLags(ids(), id, formatWeights(after)))) {
-        await input.host.writeWeights();
-    }
-    return {
-        blocked: result.blocked,
-        refused: result.refused,
-        deferredCopy: result.deferredCopy,
-        copy: result.copy,
+        await input.store.consumeRequests(result.requestIds);
+        const after = parseWeights(ids()[bgKey.weights(id)]);
+        // Also when a balancer lags the weights (an earlier write failed), so the next tick retries it.
+        if (after &&
+            (formatWeights(after) !== before || balancerLags(ids(), id, formatWeights(after)))) {
+            await input.host.writeWeights();
+        }
+        return result;
     };
+    let was = stand();
+    let result = await pass(input.now);
+    const seen = { blocked: new Set(result.blocked), refused: new Set(result.refused) };
+    let copy = result.copy;
+    let deferredCopy = result.deferredCopy;
+    // A go-live is stage, then idle, then staff, then open: each step is one run, and a step that worked makes the
+    // next one possible, so the tag goes live in one tick when nothing fails. A run that changed nothing stops it.
+    for (let more = 1; more < GO_LIVE_RUNS && result.goLiveOpen; more += 1) {
+        if (stand() === was)
+            break;
+        was = stand();
+        result = await pass(input.nowFn?.() ?? input.now);
+        for (const line of result.blocked)
+            seen.blocked.add(line);
+        for (const line of result.refused)
+            seen.refused.add(line);
+        copy ??= result.copy;
+        deferredCopy ||= result.deferredCopy;
+    }
+    return { blocked: [...seen.blocked], refused: [...seen.refused], deferredCopy, copy };
 }
 /**
  * Runs the stage copy a release run decided on and records what came of it. Call it after

package/dist/plan/signin-mail.d.ts

@@ -18,16 +18,8 @@ export declare const SIGNIN_MAIL_CODE: {
     readonly length: 6;
     readonly expirySeconds: 300;
 };
-/** The four ZITADEL calls the sign-in mail needs. */
+/** The three ZITADEL calls the sign-in mail needs. */
 export interface PlatformZitadelMailBranding {
-    /**
-     * Renames an organisation, only when its name differs (`PUT /management/v1/orgs/me` as that
-     * organisation). The login shows the instance's default organisation's name as its wordmark when the
-     * host is bound to no company, so a company's own instance names it after the company.
-     */
-    ensureOrgName(orgId: string, name: string): Promise<{
-        changed: boolean;
-    }>;
     ensureEmailOtpMessageText(language: string, text: {
         title: string;
         preHeader: string;
@@ -104,7 +96,7 @@ export declare const SIGNIN_MAIL_LABEL_POLICY: {
     readonly warnColorDark: "#FF9C8C";
     readonly disableWatermark: true;
 };
-/** Names the default organisation after the company, then writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
-export declare function applySigninMail(zitadel: PlatformZitadelMailBranding, companyName: string, defaultOrgId: string): Promise<{
+/** Writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. The wordmark is the login's `LOGIN_COMPANY_NAME`, not an organisation name. */
+export declare function applySigninMail(zitadel: PlatformZitadelMailBranding, companyName: string): Promise<{
     changed: boolean;
 }>;

package/dist/plan/signin-mail.js

@@ -71,13 +71,12 @@ export const SIGNIN_MAIL_LABEL_POLICY = {
     warnColorDark: '#FF9C8C',
     disableWatermark: true,
 };
-/** Names the default organisation after the company, then writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
-export async function applySigninMail(zitadel, companyName, defaultOrgId) {
-    const name = await zitadel.ensureOrgName(defaultOrgId, signinMailName(companyName));
+/** Writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. The wordmark is the login's `LOGIN_COMPANY_NAME`, not an organisation name. */
+export async function applySigninMail(zitadel, companyName) {
     const text = await zitadel.ensureEmailOtpMessageText(SIGNIN_MAIL_LANGUAGE, signinMailText(companyName));
     const look = await zitadel.ensureLabelPolicy({ ...SIGNIN_MAIL_LABEL_POLICY });
     const code = await zitadel.ensureEmailOtpGenerator({ ...SIGNIN_MAIL_CODE });
     return {
-        changed: name.changed || text.changed || look.changed || code.changed,
+        changed: text.changed || look.changed || code.changed,
     };
 }

package/dist/release/decide.d.ts

@@ -79,6 +79,15 @@ export type ReleaseEffect = {
     kind: 'deploy';
     color: Color;
     digest: string;
+    /**
+     * A go-live's `APP_TAG`, `APP_RELEASE` and `APP_MINIMUM_RELEASE` (removed when `minimum` is null). The host
+     * writes them to this color with the deploy, so the color boots with them; the serving color is never touched.
+     */
+    appEnv?: {
+        tag: string;
+        release: number;
+        minimum: number | null;
+    };
 } | {
     kind: 'stop';
     color: Color;

package/dist/release/decide.js

@@ -161,7 +161,7 @@ function applyActions(r, actions, now, out, kind) {
                 out.refused.push('promote refused: stage has no digest');
             else if (cur.held.includes(digest))
                 out.refused.push('promote refused: digest is held');
-            else if (digest === cur.digests[cur.live])
+            else if (digest === cur.digests[cur.live] && !a.redeploy)
                 out.refused.push('promote refused: digest is already live');
             else {
                 const to = otherColor(cur.live);

package/dist/release/golive.d.ts

@@ -0,0 +1,77 @@
+import type { Recorded } from './decide.js';
+import type { ReleaseAction, ReleaseEvent, ReleasedVersion } from './types.js';
+export type GoLiveAction = Extract<ReleaseAction, {
+    kind: 'go_live';
+}>;
+export type SetRequiredAction = Extract<ReleaseAction, {
+    kind: 'set_required';
+}>;
+export type App = 'boule' | 'agora';
+/** A go-live tries each deploy step this many ticks before it is refused. */
+export declare const GO_LIVE_TRIES = 3;
+/** `bg.<entry>.golive`: `<request id>|<stage deploys tried>|<release reserved by the idle deploy>|<idle deploys failed>`. */
+export interface GoLiveState {
+    requestId: number;
+    tries: number;
+    release: number | null;
+    idle: number;
+}
+export declare function parseGoLive(value: string | undefined): GoLiveState | null;
+export declare function formatGoLive(s: GoLiveState): string;
+/** What one due `go_live` request comes to in this run. */
+export interface GoLivePlan {
+    /** For `decide`: `deploy_stage`, `promote` or `open` (never more than one). */
+    actions: ReleaseAction[];
+    /** The `promote` among `actions`, when there is one: its deploy carries the tag's env. */
+    promote?: ReleaseAction;
+    /** The tag completed in this run: record it. */
+    record: boolean;
+    /** The request is consumed. False: it stays open and the next run judges it again. */
+    consume: boolean;
+    /** The runner starts this go-live: the request is claimed before any effect, so it can no longer be cancelled or moved. */
+    claim: boolean;
+    /** The env the idle color is deployed with (only with `promote`). */
+    appEnv?: {
+        tag: string;
+        release: number;
+        minimum: number | null;
+    };
+    /** The tries to carry into `bg.<entry>.golive` when the idle deploy worked or failed (only with `promote`). */
+    carry?: {
+        tries: number;
+        idle: number;
+    };
+    /** `bg.<entry>.golive` after this run (null removes it); not used with `promote`. */
+    state?: GoLiveState | null;
+    refused?: string;
+    blocked?: string;
+    events: Array<Pick<ReleaseEvent, 'kind' | 'reason'>>;
+}
+/**
+ * Decides one `go_live`. Stage is deployed at the tag's commit when it differs, then the idle color is deployed
+ * with the tag's env (`promote`, also for a commit the live color already runs), then it is opened (the staff hold
+ * is passed here: stage was the review) only when the idle color runs and answers, and the request waits until
+ * the release completes, one color at 100 % with the window closed. Only then is the version recorded, and only
+ * when `bg.<entry>.golive` holds the release number this request's own idle deploy reserved: a tag no color
+ * carries is never recorded. Each deploy step is tried `GO_LIVE_TRIES` ticks, a history line for each retry.
+ */
+export declare function planGoLive(input: {
+    app: App;
+    action: GoLiveAction;
+    requestId: number;
+    recorded: Recorded;
+    ids: Readonly<Record<string, string>>;
+    released: readonly ReleasedVersion[];
+    now: Date;
+    /** The new color's observation (only meaningful while a release runs). */
+    observation: {
+        status: 'running' | 'crash_loop' | 'other';
+        address: 'ok' | 'failed' | 'unchecked';
+    };
+}): GoLivePlan;
+/** The highest release at or below `release` that is required; null when none. */
+export declare function minimumFor(versions: readonly ReleasedVersion[], release: number): number | null;
+/** A free release number: the unix second of `now`, or the next free one when a version already took it. */
+export declare function releaseNumber(now: Date, versions: readonly ReleasedVersion[]): number;
+/** The scope writes that record `v`. */
+export declare function recordWrites(v: ReleasedVersion): Record<string, string>;