@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/workspace-worker.js

@@ -0,0 +1,13 @@
+/**
+ * A Worker-app workspace is planned as a second Worker app: a copy of the entry under the key `<key>-work`.
+ * The copy is never declared; `withWorkspaceWorkers` (`plan/workspace.ts`) makes it and registers it here, so
+ * the name, host and zone helpers can tell it from a declared entry. A leaf module: `hostnames.ts` reads it.
+ */
+const PARENT_OF = new WeakMap();
+export function registerWorkspaceWorker(copy, parentKey) {
+    PARENT_OF.set(copy, parentKey);
+}
+/** The key of the entry a workspace Worker copy belongs to, or `null` for a declared entry. */
+export function workspaceWorkerParent(entry) {
+    return PARENT_OF.get(entry) ?? null;
+}

package/dist/plan/workspace.d.ts

@@ -0,0 +1,101 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import { type BlueGreenServer, type BlueGreenSubject } from './blue-green.js';
+import type { DraftStep } from './diff.js';
+/** The scope keys of a workspace, beside the stage's `bg.<key>.…` ones. `.` separated, no `:`. */
+export declare const wsKey: {
+    /** The hash of the workspace's shape last applied. Also the sign that its route may be written. */
+    applied: (key: string) => string;
+    /** The 40 character commit the workspace runs; the live app is made from it. */
+    commit: (key: string) => string;
+    /** The commit the live app was last made from or moved to by a promote (`HostingEntry.liveCommit`). */
+    liveCommit: (key: string) => string;
+    /** The non-secret sign-in env the workspace was last applied with (JSON); never a key. */
+    signIn: (key: string) => string;
+};
+/** The key of a workspace's Access gate in the company. */
+export declare const workspaceGateKey: (entryKey: string) => string;
+/** The key of the gate over the test inbox. Entry keys cannot start with a hyphen, so it never clashes with `ws-<key>`. */
+export declare const INBOX_GATE_KEY = "ws--inbox";
+/** True when the org has a server workspace, and so a stage mail sink to show. */
+export declare const hasInbox: (org: DeclaredOrg) => boolean;
+/** The people-list hash a gate was last made or changed with. */
+export declare const gatePeopleScopeKey: (gateKey: string) => string;
+/** The entries of an org that declare a workspace. */
+export declare function workspaceEntries(org: DeclaredOrg): HostingEntry[];
+/** True for a workspace that runs as a server (Coolify), false for a Worker app's. */
+export declare const isServerWorkspace: (entry: HostingEntry) => boolean;
+/**
+ * The company's people who may open company apps: the owners, by sign-in address and work address. This is the
+ * list the stage gate used (owners only); the owners are the only company people the gate inputs hold.
+ */
+export declare function companyPeople(org: Pick<DeclaredOrg, 'owners'>): string[];
+/** Who passes a workspace's gate: the company's people and the entry's testers, lowercased, distinct, sorted. */
+export declare function workspacePeople(org: Pick<DeclaredOrg, 'owners'>, entry: HostingEntry): string[];
+/** The hash recorded when a gate's people were set. A change of testers changes it. */
+export declare const peopleHash: (emails: readonly string[]) => string;
+/** The org without the entries that are not live: nothing that makes an app or its address sees them. */
+export declare function withoutDarkEntries(org: DeclaredOrg): DeclaredOrg;
+/**
+ * The org with a second Worker app per Worker-app workspace, keyed `<key>-work`, so the Worker app planner and
+ * executor deploy it like any other. The copy has no database and no sign-in env (the workspace gate is its
+ * sign-in; a database would be the live one) and is served at the workspace host. `declared` names the org the
+ * workspaces are read from when `org` has had dark entries removed.
+ */
+export declare function withWorkspaceWorkers(org: DeclaredOrg, declared?: DeclaredOrg): DeclaredOrg;
+/** A server workspace as the blue/green stage code sees its subject: no colors, no hostnames, no reporting. */
+export declare function workspaceSubject(org: DeclaredOrg, entry: HostingEntry): BlueGreenSubject;
+/** The origin the tunnel sends a server workspace's host to: the stage app on the company network. */
+export declare const workspaceOrigin: (subject: Pick<BlueGreenSubject, "base" | "port">) => string;
+/**
+ * The tunnel routes of the server workspaces: the workspace host to the stage app. A route is written only once
+ * the workspace was applied and its stage guards hold (isolated, probed, gated, healthy), never before.
+ */
+export declare function workspaceRoutes(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): Array<{
+    hostname: string;
+    service: string;
+}>;
+/** Whether `name` is the workspace host of one of the org's server workspaces. */
+export declare function ownsWorkspaceName(org: DeclaredOrg, name: string): boolean;
+/** A short hash of what decides the shape of a server workspace, so a change replans it. */
+export declare function workspaceStructureHash(org: DeclaredOrg, entry: HostingEntry): string;
+export interface PlanWorkspacesInput {
+    /** The org as declared, dark entries included. */
+    org: DeclaredOrg;
+    recordedIds: Readonly<Record<string, string>>;
+    /** Every Coolify server the host reports. `undefined`: the host cannot list them. */
+    servers: readonly BlueGreenServer[] | undefined;
+    /** The workspace's Access gate is recorded or planned in this run. */
+    gateReady: (gateKey: string) => boolean;
+    /** The company's stage mail sink is recorded and its live app is stopped or gone. */
+    stageSinkDown?: boolean;
+    /**
+     * The sign-in env a workspace with `uses.auth` should run with, as `workspaceSignInMarker` writes it, or
+     * `null` while it is not all recorded (the workspace is then blocked). Absent: sign-in is not planned.
+     */
+    signInWanted?: (entry: HostingEntry) => string | null;
+    /** The issuer the workspace's app signs in at; goes to the step for the executor. */
+    authIssuer?: string | null;
+}
+/**
+ * One `coolify:workspace` step per server workspace whose shape is not applied yet or whose stage needs another
+ * try; the Worker-app workspaces are planned by `planWorkerApps` through {@link withWorkspaceWorkers}. Pure.
+ * Blocked, not planned, while the host cannot list servers, the primary is unusable, the stage would not be
+ * isolated from the company's other apps, or the gate is not there: a workspace nobody can sign in to is not made.
+ */
+export declare function planWorkspaces(input: PlanWorkspacesInput): {
+    steps: DraftStep[];
+    unmanaged: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+/**
+ * The commit of the newest finished deployment of the workspace's stage app, or `null` when the port cannot
+ * list deployments, the read fails or there is none. The live app of a workspace entry is made from it.
+ */
+export declare function readWorkspaceCommit(coolify: {
+    listApplicationDeployments?(uuid: string, take?: number): Promise<Array<{
+        commit?: string;
+        status: string;
+    }>>;
+}, stageAppId: string): Promise<string | null>;

package/dist/plan/workspace.js

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { FULL_COMMIT_SHA, isLiveEntry, normalizeTesters, } from '../org.js';
+import { PRIMARY_SERVER_SCOPE_KEY, bgKey, splitServers, stageAppName, stagePlanViolations, } from './blue-green.js';
+import { withTimeout } from './call-timeout.js';
+import { workspaceHost, workspaceInboxHost } from './hostnames.js';
+import { appNameFor, appStepKey } from './platform-diff.js';
+import { stageGuardsReady } from './stage-guards.js';
+import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_VERSION, stageSinkAppName, } from './stage-sink.js';
+import { registerWorkspaceWorker } from './workspace-worker.js';
+/**
+ * Private workspaces (`HostingEntry.workspace`). A workspace is where a company's team and invited testers build
+ * and test an app behind sign-in; `live` is a separate step that puts the app on its public address.
+ *
+ * A server entry's workspace is the blue/green stage (`blue-green-apply.ts`'s `ensureStage`): the stage app, its
+ * own empty database, the stage mail sink and the stage guards. It is served at the workspace host and has no
+ * colors, so it needs no `blueGreen`. A Worker app's workspace is a second Worker app `<slug>-<key>-work`.
+ * The gate over the workspace host is one Access gate per workspace, made by `planGates`.
+ */
+const FULL_SHA = FULL_COMMIT_SHA;
+/** One Coolify read of the workspace's deployments. */
+const COMMIT_READ_TIMEOUT_MS = 15_000;
+/** A Cloudflare Worker script name is at most 63 characters; so is a DNS label. */
+const MAX_NAME = 63;
+/** The scope keys of a workspace, beside the stage's `bg.<key>.…` ones. `.` separated, no `:`. */
+export const wsKey = {
+    /** The hash of the workspace's shape last applied. Also the sign that its route may be written. */
+    applied: (key) => `ws.${key}.applied`,
+    /** The 40 character commit the workspace runs; the live app is made from it. */
+    commit: (key) => `ws.${key}.commit`,
+    /** The commit the live app was last made from or moved to by a promote (`HostingEntry.liveCommit`). */
+    liveCommit: (key) => `ws.${key}.livecommit`,
+    /** The non-secret sign-in env the workspace was last applied with (JSON); never a key. */
+    signIn: (key) => `ws.${key}.signin`,
+};
+/** The key of a workspace's Access gate in the company. */
+export const workspaceGateKey = (entryKey) => `ws-${entryKey}`;
+/** The key of the gate over the test inbox. Entry keys cannot start with a hyphen, so it never clashes with `ws-<key>`. */
+export const INBOX_GATE_KEY = 'ws--inbox';
+/** True when the org has a server workspace, and so a stage mail sink to show. */
+export const hasInbox = (org) => workspaceEntries(org).some(isServerWorkspace);
+/** The people-list hash a gate was last made or changed with. */
+export const gatePeopleScopeKey = (gateKey) => `gate_people_${gateKey}`;
+/** The entries of an org that declare a workspace. */
+export function workspaceEntries(org) {
+    return org.hosting.enabled ? org.hosting.entries.filter((e) => e.workspace !== undefined) : [];
+}
+/** True for a workspace that runs as a server (Coolify), false for a Worker app's. */
+export const isServerWorkspace = (entry) => entry.workspace !== undefined && entry.workerApp === undefined;
+/**
+ * The company's people who may open company apps: the owners, by sign-in address and work address. This is the
+ * list the stage gate used (owners only); the owners are the only company people the gate inputs hold.
+ */
+export function companyPeople(org) {
+    return normalizeTesters(org.owners.flatMap((owner) => owner.mailboxAddress === undefined ? [owner.email] : [owner.email, owner.mailboxAddress])).sort();
+}
+/** Who passes a workspace's gate: the company's people and the entry's testers, lowercased, distinct, sorted. */
+export function workspacePeople(org, entry) {
+    return normalizeTesters([...companyPeople(org), ...(entry.workspace?.testers ?? [])]).sort();
+}
+/** The hash recorded when a gate's people were set. A change of testers changes it. */
+export const peopleHash = (emails) => createHash('sha256').update(JSON.stringify(emails)).digest('hex').slice(0, 16);
+/** The org without the entries that are not live: nothing that makes an app or its address sees them. */
+export function withoutDarkEntries(org) {
+    if (org.hosting.entries.every(isLiveEntry))
+        return org;
+    return { ...org, hosting: { ...org.hosting, entries: org.hosting.entries.filter(isLiveEntry) } };
+}
+/**
+ * The org with a second Worker app per Worker-app workspace, keyed `<key>-work`, so the Worker app planner and
+ * executor deploy it like any other. The copy has no database and no sign-in env (the workspace gate is its
+ * sign-in; a database would be the live one) and is served at the workspace host. `declared` names the org the
+ * workspaces are read from when `org` has had dark entries removed.
+ */
+export function withWorkspaceWorkers(org, declared = org) {
+    if (!org.hosting.enabled)
+        return org;
+    const copies = [];
+    for (const entry of declared.hosting.entries) {
+        if (!entry.workspace || !entry.workerApp)
+            continue;
+        const { workspace: _w, live: _l, hostedName: _h, uses: _u, workerApp, ...rest } = entry;
+        const { database: _d, authEnv: _a, ...app } = workerApp;
+        const copy = {
+            ...rest,
+            key: `${entry.key}-work`,
+            main: false,
+            hostnames: [],
+            gates: [],
+            env: {},
+            database: false,
+            workerApp: app,
+        };
+        registerWorkspaceWorker(copy, entry.key);
+        copies.push(copy);
+    }
+    if (copies.length === 0)
+        return org;
+    return { ...org, hosting: { ...org.hosting, entries: [...org.hosting.entries, ...copies] } };
+}
+/** A server workspace as the blue/green stage code sees its subject: no colors, no hostnames, no reporting. */
+export function workspaceSubject(org, entry) {
+    const base = appNameFor(org, entry);
+    const isStatic = entry.buildPack === 'static';
+    return {
+        id: entry.key,
+        base,
+        primaryBlueName: base,
+        port: isStatic ? 80 : (entry.port ?? 80),
+        repo: entry.repo,
+        folder: entry.folder,
+        branch: entry.branch,
+        buildPack: entry.buildPack,
+        healthPath: entry.healthPath ?? (isStatic ? '/' : '/api/health'),
+        database: entry.database,
+        hostnames: [],
+        config: {},
+        blueAppKey: `coolify:app:${appStepKey(org, entry.key)}`,
+        reporting: false,
+    };
+}
+/** The origin the tunnel sends a server workspace's host to: the stage app on the company network. */
+export const workspaceOrigin = (subject) => `http://${stageAppName(subject.base)}:${subject.port}`;
+/**
+ * The tunnel routes of the server workspaces: the workspace host to the stage app. A route is written only once
+ * the workspace was applied and its stage guards hold (isolated, probed, gated, healthy), never before.
+ */
+export function workspaceRoutes(org, recorded = {}) {
+    const inbox = hasInbox(org) &&
+        recorded[STAGE_SINK_APPLIED_SCOPE_KEY] &&
+        recorded[`cloudflare:gate:${org.id}:${INBOX_GATE_KEY}`]
+        ? [
+            {
+                hostname: workspaceInboxHost(org.slug),
+                service: `http://${stageSinkAppName(org)}:${STAGE_SINK_HTTP_PORT}`,
+            },
+        ]
+        : [];
+    return [
+        ...workspaceEntries(org)
+            .filter((entry) => isServerWorkspace(entry) &&
+            recorded[wsKey.applied(entry.key)] &&
+            stageGuardsReady(recorded, entry.key).ready)
+            .map((entry) => ({
+            hostname: workspaceHost(org.slug, entry.key),
+            service: workspaceOrigin(workspaceSubject(org, entry)),
+        })),
+        ...inbox,
+    ];
+}
+/** Whether `name` is the workspace host of one of the org's server workspaces. */
+export function ownsWorkspaceName(org, name) {
+    const lower = name.toLowerCase();
+    if (hasInbox(org) && lower === workspaceInboxHost(org.slug))
+        return true;
+    return workspaceEntries(org).some((entry) => isServerWorkspace(entry) && workspaceHost(org.slug, entry.key) === lower);
+}
+/** A short hash of what decides the shape of a server workspace, so a change replans it. */
+export function workspaceStructureHash(org, entry) {
+    const subject = workspaceSubject(org, entry);
+    const auth = entry.uses?.auth;
+    return createHash('sha256')
+        .update(JSON.stringify({
+        base: subject.base,
+        port: subject.port,
+        repo: subject.repo,
+        folder: subject.folder,
+        branch: subject.branch,
+        buildPack: subject.buildPack,
+        healthPath: subject.healthPath,
+        database: subject.database,
+        host: workspaceHost(org.slug, entry.key),
+        stageSink: STAGE_SINK_VERSION,
+        ...(auth
+            ? {
+                signIn: {
+                    users: auth.users,
+                    registration: auth.registration,
+                    signIn: auth.signIn ?? null,
+                    workspaces: auth.workspaces ?? null,
+                },
+            }
+            : {}),
+    }))
+        .digest('hex')
+        .slice(0, 16);
+}
+/**
+ * One `coolify:workspace` step per server workspace whose shape is not applied yet or whose stage needs another
+ * try; the Worker-app workspaces are planned by `planWorkerApps` through {@link withWorkspaceWorkers}. Pure.
+ * Blocked, not planned, while the host cannot list servers, the primary is unusable, the stage would not be
+ * isolated from the company's other apps, or the gate is not there: a workspace nobody can sign in to is not made.
+ */
+export function planWorkspaces(input) {
+    const { org, recordedIds } = input;
+    const steps = [];
+    const unmanaged = [];
+    for (const entry of workspaceEntries(org)) {
+        if (!isServerWorkspace(entry))
+            continue;
+        const id = entry.key;
+        const at = `${org.slug}'s ${id} workspace`;
+        const subject = workspaceSubject(org, entry);
+        const blocked = (why, part = 'blocked') => unmanaged.push({
+            description: `${at} is blocked, not planned: ${why}`,
+            key: `workspace:${id}:${part}`,
+        });
+        if (entry.buildPack === 'dockercompose')
+            continue;
+        if (stageAppName(subject.base).length > MAX_NAME ||
+            (workspaceHost(org.slug, id).split('.')[0] ?? '').length > MAX_NAME) {
+            blocked('its app name or address is too long; shorten the slug or the entry key', 'name');
+            continue;
+        }
+        const violations = stagePlanViolations(subject, org.hosting.entries.filter((e) => e.key !== id).map((e) => appNameFor(org, e)));
+        if (violations.length > 0) {
+            blocked(`its stage would not be isolated from the company's other apps (${violations.join(', ')})`, 'stageisolation');
+            continue;
+        }
+        if (!input.servers) {
+            blocked('the host cannot list Coolify servers');
+            continue;
+        }
+        const { up } = splitServers(input.servers);
+        const primary = recordedIds[PRIMARY_SERVER_SCOPE_KEY] ?? up[0];
+        if (!primary || !up.includes(primary)) {
+            blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
+            continue;
+        }
+        if (!input.gateReady(workspaceGateKey(id))) {
+            blocked('its Access gate is not recorded or planned yet', 'gate');
+            continue;
+        }
+        const signInWanted = entry.uses?.auth && input.signInWanted ? input.signInWanted(entry) : undefined;
+        if (signInWanted === null) {
+            blocked('its sign-in organisation, client or issuer is not recorded or planned yet', 'signin');
+            continue;
+        }
+        const stageState = recordedIds[bgKey.stageState(id)];
+        if (stageState === 'unhealthy') {
+            unmanaged.push({
+                description: `${at}: the stage app is not healthy yet`,
+                key: `workspace:${id}:stage`,
+            });
+        }
+        else if (stageState === 'blocked:sink' || input.stageSinkDown === true) {
+            unmanaged.push({
+                description: `${at}: the stage mail sink is not running; the workspace gets no mail env`,
+                key: `workspace:${id}:stage`,
+            });
+        }
+        else if (stageState?.startsWith('blocked:')) {
+            unmanaged.push({
+                description: `${at}: the stage is blocked and was not written to (${stageState.slice('blocked:'.length)})`,
+                key: `workspace:${id}:stage`,
+            });
+        }
+        const retry = stageState === 'unhealthy' ||
+            stageState?.startsWith('blocked:') === true ||
+            input.stageSinkDown === true;
+        const signInStale = signInWanted !== undefined && recordedIds[wsKey.signIn(id)] !== signInWanted;
+        if (recordedIds[wsKey.applied(id)] === workspaceStructureHash(org, entry) &&
+            !retry &&
+            !signInStale) {
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'workspace',
+                key: appStepKey(org, id),
+                desired: {
+                    entry: id,
+                    server: primary,
+                    primary,
+                    ...(signInWanted !== undefined && input.authIssuer
+                        ? { authIssuer: input.authIssuer }
+                        : {}),
+                },
+            },
+            step: {
+                description: `run ${at} at ${workspaceHost(org.slug, id)}: a stage copy of the app with its own empty database, behind sign-in${recordedIds[wsKey.applied(id)] ? '' : ' (first time)'}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, unmanaged };
+}
+/**
+ * The commit of the newest finished deployment of the workspace's stage app, or `null` when the port cannot
+ * list deployments, the read fails or there is none. The live app of a workspace entry is made from it.
+ */
+export async function readWorkspaceCommit(coolify, stageAppId) {
+    const list = coolify.listApplicationDeployments?.bind(coolify);
+    if (!list)
+        return null;
+    try {
+        const rows = await withTimeout('workspace commit: list deployments', COMMIT_READ_TIMEOUT_MS, () => list(stageAppId));
+        const finished = rows.find((row) => row.status === 'finished');
+        return finished?.commit && FULL_SHA.test(finished.commit) ? finished.commit : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/release/decide.d.ts

@@ -1,4 +1,4 @@
-import { type Color, type ReleaseAction, type ReleaseSignal, type WindowState } from './types.js';
+import { type Color, type ReleaseAction, type ReleaseConfig, type ReleaseSignal, type WindowState } from './types.js';
 /** ADR 0001 rule 5: the default steps and the least time on each. */
 export declare const DEFAULT_STEPS: readonly number[];
 export declare const DEFAULT_STEP_HOLD_MINUTES = 60;
@@ -15,8 +15,24 @@ export declare const ERROR_RATE_MARGIN = 0.02;
 /** Rules 12 and 13: the window at 100% closes after this long, and at most this long. */
 export declare const WINDOW_MIN_HOURS = 24;
 export declare const WINDOW_CAP_DAYS = 7;
+/** A `signal` step that waited this long since it began without a passing check accepts `approve_step` and reports a blocked line. */
+export declare const STEP_SIGNAL_CAP_HOURS = 24;
 /** The new color must be running and answer on its own address within this time of the deploy. */
 export declare const DEPLOY_TIMEOUT_MINUTES = 30;
+/** A `deploy_stage` ref: a branch name or a full 40-hex commit sha. */
+export declare const STAGE_REF_PATTERN: RegExp;
+export declare const DEFAULT_ADVANCE: ReleaseConfig['advance'];
+/** The release kind fields of an entry's `blueGreen`. */
+export interface ReleaseEntryConfig {
+    steps?: readonly number[] | undefined;
+    stepHoldMinutes?: number | undefined;
+    advance?: ReleaseConfig['advance'] | undefined;
+    minRequests?: number | undefined;
+    errorMargin?: number | undefined;
+    staffFirst?: boolean | undefined;
+}
+/** The entry's release kind with every default filled in. */
+export declare function resolveReleaseConfig(entry: ReleaseEntryConfig | undefined): ReleaseConfig;
 export interface ActiveRelease {
     from: Color;
     to: Color;
@@ -64,6 +80,11 @@ export type ReleaseEffect = {
 } | {
     kind: 'stop';
     color: Color;
+}
+/** Deploy stage at this ref. Decide only passes it on; the host executes it. */
+ | {
+    kind: 'deploy_stage';
+    ref: string;
 };
 export interface Decision {
     recorded: Recorded;
@@ -90,6 +111,14 @@ export declare function decide(input: {
     actions: readonly ReleaseAction[];
     steps?: readonly number[] | undefined;
     stepHoldMinutes?: number | undefined;
+    /** How a step is left; default `signal`. */
+    advance?: ReleaseConfig['advance'] | undefined;
+    /** Requests the new color needs before its error rate counts; default RELATIVE_MIN_REQUESTS. */
+    minRequests?: number | undefined;
+    /** Error rate allowed above the baseline; default ERROR_RATE_MARGIN. */
+    errorMargin?: number | undefined;
+    /** A promote waits at weight 0 in `staff` until an `open` action. */
+    staffFirst?: boolean | undefined;
     now: Date;
     observation: Observation;
     /**

package/dist/release/decide.js

@@ -15,11 +15,25 @@ export const ERROR_RATE_MARGIN = 0.02;
 /** Rules 12 and 13: the window at 100% closes after this long, and at most this long. */
 export const WINDOW_MIN_HOURS = 24;
 export const WINDOW_CAP_DAYS = 7;
+/** A `signal` step that waited this long since it began without a passing check accepts `approve_step` and reports a blocked line. */
+export const STEP_SIGNAL_CAP_HOURS = 24;
 /** The new color must be running and answer on its own address within this time of the deploy. */
 export const DEPLOY_TIMEOUT_MINUTES = 30;
 const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
+/** A `deploy_stage` ref: a branch name or a full 40-hex commit sha. */
+export const STAGE_REF_PATTERN = /^(?:[A-Za-z0-9._/-]{1,200}|[0-9a-f]{40})$/;
+export const DEFAULT_ADVANCE = 'signal';
+/** The entry's release kind with every default filled in. */
+export function resolveReleaseConfig(entry) {
+    return {
+        advance: entry?.advance ?? DEFAULT_ADVANCE,
+        steps: normalizeSteps(entry?.steps),
+        stepHoldMinutes: entry?.stepHoldMinutes ?? DEFAULT_STEP_HOLD_MINUTES,
+        staffFirst: entry?.staffFirst ?? false,
+    };
+}
 export function normalizeSteps(steps) {
     const wanted = steps && steps.length > 0 ? steps : DEFAULT_STEPS;
     const valid = [...new Set(wanted.filter((n) => Number.isInteger(n) && n >= 1 && n <= 100))].sort((a, b) => a - b);
@@ -61,12 +75,41 @@ export function healthRange(r, now) {
     }
     return null;
 }
-function applyActions(r, actions, now, out) {
+function applyActions(r, actions, now, out, kind) {
     let cur = r;
     let promoted = false;
     let ended = false;
+    let approved = false;
+    let opened = false;
     for (const a of actions) {
-        if (a.kind === 'clear_held') {
+        if (a.kind === 'deploy_stage') {
+            if (typeof a.ref === 'string' && STAGE_REF_PATTERN.test(a.ref))
+                out.effects.push({ kind: 'deploy_stage', ref: a.ref });
+            else
+                out.refused.push('deploy_stage refused: the ref is not a branch name or a commit sha');
+        }
+        else if (a.kind === 'approve_step') {
+            const w = cur.window;
+            const capped = kind.advance === 'signal' &&
+                'since' in w &&
+                now.getTime() - Date.parse(w.since) >= STEP_SIGNAL_CAP_HOURS * HOUR;
+            const waiting = (kind.advance === 'approval' || capped) &&
+                cur.release !== null &&
+                ((w.kind === 'step' && w.percent > 0) || (w.kind === 'inconclusive' && w.percent > 0));
+            if (waiting)
+                approved = true;
+            else
+                out.refused.push('approve_step refused: no step is waiting for approval');
+        }
+        else if (a.kind === 'open') {
+            if (cur.window.kind === 'staff' && cur.release) {
+                cur = stepTo(cur, cur.release, kind.steps[0], now);
+                opened = true;
+            }
+            else
+                out.refused.push('open refused: no release is waiting for staff');
+        }
+        else if (a.kind === 'clear_held') {
             cur = { ...cur, held: cur.held.filter((d) => d !== a.digest) };
         }
         else if (a.kind === 'promote') {
@@ -114,7 +157,7 @@ function applyActions(r, actions, now, out) {
             }
         }
     }
-    return { recorded: cur, promoted, ended };
+    return { recorded: cur, promoted, ended, approved, opened };
 }
 /**
  * The whole release decision for one run: from the recorded state, the
@@ -126,12 +169,15 @@ export function decide(input) {
     const steps = normalizeSteps(input.steps);
     const holdMs = (input.stepHoldMinutes ?? DEFAULT_STEP_HOLD_MINUTES) * MINUTE;
     const out = { effects: [], refused: [] };
-    const applied = applyActions(input.recorded, input.actions, now, out);
+    const advance = input.advance ?? DEFAULT_ADVANCE;
+    const minRequests = input.minRequests ?? RELATIVE_MIN_REQUESTS;
+    const errorMargin = input.errorMargin ?? ERROR_RATE_MARGIN;
+    const applied = applyActions(input.recorded, input.actions, now, out, { advance, steps });
     let r = applied.recorded;
     let signal = null;
     const blocked = [];
     const rel = r.release;
-    if (!applied.promoted && !applied.ended && rel) {
+    if (!applied.promoted && !applied.ended && !applied.opened && rel) {
         const since = Date.parse('since' in r.window ? r.window.since : '');
         const elapsed = now.getTime() - since;
         const hard = observation.status === 'crash_loop'
@@ -143,12 +189,19 @@ export function decide(input) {
             if (hard)
                 r = rollback(r, now, hard);
             else if (observation.status === 'running' && observation.address === 'ok') {
-                const first = steps[0];
-                r = stepTo(r, rel, first, now);
+                if (input.staffFirst)
+                    r = { ...r, window: { kind: 'staff', since: now.toISOString() } };
+                else
+                    r = stepTo(r, rel, steps[0], now);
             }
             else if (elapsed >= DEPLOY_TIMEOUT_MINUTES * MINUTE)
                 r = rollback(r, now, 'deploy timeout');
         }
+        else if (r.window.kind === 'staff') {
+            // Weight 0: only a hard fail (crash loop, failed address) rolls back. `open` leaves it.
+            if (hard)
+                r = rollback(r, now, hard);
+        }
         else {
             const health = input.hardOnly ? null : observation.health;
             const newC = health?.colors[rel.to] ?? { requests: 0, errors: 0 };
@@ -164,10 +217,10 @@ export function decide(input) {
                 verdict = 'hard_fail';
             else if (input.hardOnly)
                 verdict = 'pass';
-            else if (!health || baseline === null || newC.requests < RELATIVE_MIN_REQUESTS)
+            else if (!health || baseline === null || newC.requests < minRequests)
                 verdict = 'inconclusive';
             else
-                verdict = rate(newC) > baseline + ERROR_RATE_MARGIN ? 'fail' : 'pass';
+                verdict = rate(newC) > baseline + errorMargin ? 'fail' : 'pass';
             signal = { requests: newC.requests, errors: newC.errors, baselineRate: baseline, verdict };
             if (verdict === 'hard_fail') {
                 r = rollback(r, now, hard ?? 'hard fail: error rate');
@@ -188,7 +241,14 @@ export function decide(input) {
                     if (!atWindow) {
                         const pct = r.window.percent;
                         const holdDone = elapsed >= holdMs;
-                        if (holdDone && verdict !== 'fail') {
+                        const stepUp = advance === 'time'
+                            ? holdDone && verdict !== 'fail'
+                            : advance === 'signal'
+                                ? (holdDone && verdict === 'pass') || (applied.approved && verdict !== 'fail')
+                                : applied.approved && verdict !== 'fail';
+                        if (applied.approved && advance !== 'time' && verdict === 'fail')
+                            out.refused.push('approve_step refused: the error rate is failing');
+                        if (stepUp) {
                             const next = steps.find((s) => s > pct);
                             r = stepTo(r, rel, next, now);
                         }
@@ -198,6 +258,8 @@ export function decide(input) {
                                 ...r,
                                 window: { kind, percent: pct, since: r.window.since },
                             };
+                            if (advance === 'signal' && elapsed >= STEP_SIGNAL_CAP_HOURS * HOUR)
+                                blocked.push('step waiting for traffic: approve the step or roll back in Archon');
                         }
                     }
                     else {
@@ -208,7 +270,7 @@ export function decide(input) {
                                 baseline !== null &&
                                 elapsed >= WINDOW_MIN_HOURS * HOUR &&
                                 newC.requests >= required &&
-                                rate(newC) <= baseline + ERROR_RATE_MARGIN;
+                                rate(newC) <= baseline + errorMargin;
                         if (closable) {
                             out.effects.push({ kind: 'stop', color: rel.from });
                             r = { ...r, window: { kind: 'passed', at: now.toISOString() }, release: null };