@wtfalch/foundry 0.61.0 → 0.63.0

package/dist/release/migration-compatibility.js

@@ -0,0 +1,340 @@
+import { foldMigrationClasses } from '../worker-app-config.js';
+import { parseMigrations, unappliedDatabaseMigrations, } from '../worker-app-migrations.js';
+const REMOVAL_MARKER = /^--\s*removal-since:\s*(\S.*)$/i;
+const STATEMENT_MAX_CHARS = 160;
+/** Collapses whitespace and cuts a statement down to a readable, one-line length for a message. */
+function oneLine(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length > STATEMENT_MAX_CHARS
+        ? `${collapsed.slice(0, STATEMENT_MAX_CHARS - 1)}…`
+        : collapsed;
+}
+/**
+ * Splits `sql` into standalone statements at a semicolon that sits outside a line comment, a
+ * block comment, a single- or double-quoted literal, and a dollar-quoted body (a function's
+ * `$$ ... $$`, which may itself hold semicolons). Each statement keeps any comment lines directly
+ * above it, so a `-- removal-since:` marker travels with the statement it excuses.
+ */
+function splitStatements(sql) {
+    const statements = [];
+    let current = '';
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const ch = sql[i];
+        if (ch === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i);
+            const end2 = end === -1 ? n : end + 1;
+            current += sql.slice(i, end2);
+            i = end2;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            const end2 = end === -1 ? n : end + 2;
+            current += sql.slice(i, end2);
+            i = end2;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            let j = i + 1;
+            while (j < n) {
+                if (sql[j] === ch) {
+                    if (sql[j + 1] === ch) {
+                        j += 2;
+                        continue;
+                    }
+                    j += 1;
+                    break;
+                }
+                j += 1;
+            }
+            current += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (ch === '$') {
+            const tagMatch = /^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/.exec(sql.slice(i));
+            if (tagMatch) {
+                const tag = tagMatch[0];
+                const end = sql.indexOf(tag, i + tag.length);
+                const end2 = end === -1 ? n : end + tag.length;
+                current += sql.slice(i, end2);
+                i = end2;
+                continue;
+            }
+        }
+        if (ch === ';') {
+            statements.push(current);
+            current = '';
+            i += 1;
+            continue;
+        }
+        current += ch;
+        i += 1;
+    }
+    if (current.trim() !== '')
+        statements.push(current);
+    return statements;
+}
+/**
+ * Splits `code` at a top-level comma (outside a quoted literal or parentheses), so each element
+ * of an `ALTER TABLE`'s comma-separated action list -- `ADD COLUMN a text DEFAULT 'x', ADD COLUMN
+ * b integer NOT NULL` -- can be judged on its own. Without this, a `DEFAULT` on one added column
+ * hid a `NOT NULL` with no default on a different one, because the two regexes ran against the
+ * whole statement (foundry#941 review).
+ */
+function splitTopLevelCommas(code) {
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const ch = code[i];
+        if (ch === "'" || ch === '"') {
+            let j = i + 1;
+            while (j < n) {
+                if (code[j] === ch) {
+                    if (code[j + 1] === ch) {
+                        j += 2;
+                        continue;
+                    }
+                    j += 1;
+                    break;
+                }
+                j += 1;
+            }
+            current += code.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (ch === '(') {
+            depth += 1;
+            current += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === ')') {
+            depth = Math.max(0, depth - 1);
+            current += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+            i += 1;
+            continue;
+        }
+        current += ch;
+        i += 1;
+    }
+    parts.push(current);
+    return parts;
+}
+/** The statement with its leading blank and comment lines removed, so classification reads code, not a marker. */
+function withoutLeadingComments(statement) {
+    const lines = statement.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const trimmed = lines[i].trim();
+        if (trimmed === '' || trimmed.startsWith('--')) {
+            i += 1;
+            continue;
+        }
+        break;
+    }
+    return lines.slice(i).join('\n').trim();
+}
+/** The release named in a `-- removal-since: <release>` line directly above the statement, or `null`. */
+function declaredSince(statement) {
+    for (const line of statement.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const match = REMOVAL_MARKER.exec(trimmed);
+        if (match)
+            return match[1].trim();
+        if (!trimmed.startsWith('--'))
+            break;
+    }
+    return null;
+}
+/**
+ * Classifies one statement's code (comments already stripped) as additive or destructive, or
+ * `null` when it cannot tell: an unrecognised statement is never assumed to be additive.
+ */
+function classifyStatement(code) {
+    if (code === '')
+        return null;
+    if (/^CREATE\s+(OR\s+REPLACE\s+)?(TABLE|SCHEMA|EXTENSION|SEQUENCE|VIEW)\b/i.test(code)) {
+        return { destructive: false, reason: 'creates something new' };
+    }
+    if (/^CREATE\s+(UNIQUE\s+)?INDEX(\s+CONCURRENTLY)?\b/i.test(code)) {
+        return { destructive: false, reason: 'adds an index' };
+    }
+    if (/^CREATE\s+(OR\s+REPLACE\s+)?(FUNCTION|PROCEDURE)\b/i.test(code)) {
+        return { destructive: false, reason: 'adds or replaces a function' };
+    }
+    if (/^CREATE\s+(OR\s+REPLACE\s+)?TRIGGER\b/i.test(code)) {
+        return { destructive: false, reason: 'adds a trigger' };
+    }
+    if (/^(COMMENT\s+ON|GRANT)\b/i.test(code)) {
+        return {
+            destructive: false,
+            reason: 'changes neither data nor structure a running release reads',
+        };
+    }
+    if (/^ALTER\s+TABLE\b/i.test(code)) {
+        if (/\bDROP\s+COLUMN\b/i.test(code))
+            return { destructive: true, reason: 'drops a column' };
+        if (/\bDROP\s+CONSTRAINT\b/i.test(code))
+            return { destructive: true, reason: 'drops a constraint' };
+        if (/\bRENAME\b/i.test(code))
+            return { destructive: true, reason: 'renames a table or column' };
+        if (/\bALTER\s+COLUMN\b[\s\S]*\b(SET\s+DATA\s+)?TYPE\b/i.test(code)) {
+            return { destructive: true, reason: "changes a column's type" };
+        }
+        if (/\bSET\s+NOT\s+NULL\b/i.test(code)) {
+            return { destructive: true, reason: 'adds a NOT NULL constraint to an existing column' };
+        }
+        if (/\bADD\s+COLUMN\b/i.test(code)) {
+            for (const clause of splitTopLevelCommas(code)) {
+                if (!/\bADD\s+COLUMN\b/i.test(clause))
+                    continue;
+                if (/\bNOT\s+NULL\b/i.test(clause) && !/\bDEFAULT\b/i.test(clause)) {
+                    return { destructive: true, reason: 'adds a NOT NULL column with no default' };
+                }
+            }
+            return { destructive: false, reason: 'adds a column' };
+        }
+        if (/\bADD\s+CONSTRAINT\b/i.test(code))
+            return { destructive: false, reason: 'adds a constraint' };
+        return null;
+    }
+    if (/^DROP\s+(TABLE|INDEX|TYPE|SCHEMA|FUNCTION|PROCEDURE|TRIGGER|VIEW|MATERIALIZED\s+VIEW|EXTENSION|SEQUENCE)\b/i.test(code)) {
+        return { destructive: true, reason: 'drops something the live release may still read' };
+    }
+    if (/^(TRUNCATE|DELETE\s+FROM|UPDATE\s+\S+\s+SET)\b/i.test(code)) {
+        return { destructive: true, reason: 'removes or rewrites existing rows' };
+    }
+    if (/^ALTER\s+(INDEX|SEQUENCE|VIEW|TYPE|SCHEMA)\b[\s\S]*\bRENAME\b/i.test(code)) {
+        return { destructive: true, reason: 'renames something' };
+    }
+    return null;
+}
+const splitHelp = (what) => `${what}; split this into two releases: stop using it in one, remove it in a later release once that one is no longer on live, idle or draining`;
+/** A destructive statement or step named `since` is drained once that release deploys nowhere. */
+function hasDrained(since, deployedReleases) {
+    return !deployedReleases.includes(since);
+}
+function sqlProblems(migrationsJson, liveMigrationIds, deployedReleases) {
+    let declared;
+    try {
+        declared = parseMigrations(migrationsJson);
+    }
+    catch (error) {
+        return [{ migration: '', statement: '', reason: error.message }];
+    }
+    let pending;
+    try {
+        pending = unappliedDatabaseMigrations(declared, liveMigrationIds);
+    }
+    catch (error) {
+        return [{ migration: '', statement: '', reason: error.message }];
+    }
+    const problems = [];
+    for (const migration of pending) {
+        for (const statement of splitStatements(migration.sql)) {
+            const code = withoutLeadingComments(statement);
+            const classified = classifyStatement(code);
+            if (classified === null) {
+                problems.push({
+                    migration: migration.id,
+                    statement: oneLine(code),
+                    reason: 'this statement is not one foundry recognises as additive; split it into its own release and ask a person',
+                });
+                continue;
+            }
+            if (!classified.destructive)
+                continue;
+            const since = declaredSince(statement);
+            if (since === null) {
+                problems.push({
+                    migration: migration.id,
+                    statement: oneLine(code),
+                    reason: splitHelp(classified.reason),
+                });
+                continue;
+            }
+            if (!hasDrained(since, deployedReleases)) {
+                problems.push({
+                    migration: migration.id,
+                    statement: oneLine(code),
+                    reason: `${classified.reason}; declared as the second step after release ${since}, but ${since} is still on live, idle or draining -- wait for it to fully drain, then release this one`,
+                });
+            }
+        }
+    }
+    return problems;
+}
+function doProblems(doMigrations, liveDoTag, declaredRemovals, deployedReleases) {
+    if (doMigrations.length === 0)
+        return [];
+    let appliedCount = 0;
+    if (liveDoTag !== undefined) {
+        const index = doMigrations.findIndex((m) => m.tag === liveDoTag);
+        if (index < 0) {
+            return [
+                {
+                    migration: liveDoTag,
+                    statement: '',
+                    reason: "the live release holds a Durable Object migration that is not in this release's declared list; migrations are append-only",
+                },
+            ];
+        }
+        appliedCount = index + 1;
+    }
+    const folded = foldMigrationClasses(doMigrations.slice(0, appliedCount));
+    if ('error' in folded)
+        return [{ migration: '', statement: '', reason: folded.error }];
+    const problems = [];
+    for (const migration of doMigrations.slice(appliedCount)) {
+        for (const className of migration.deletedClasses ?? []) {
+            if (!folded.classes.has(className))
+                continue; // never reached live: nothing running still uses it
+            const removal = declaredRemovals.find((r) => r.className === className);
+            const statement = `deleted_classes: ${className}`;
+            if (!removal) {
+                problems.push({
+                    migration: migration.tag,
+                    statement,
+                    reason: splitHelp(`deletes the Durable Object class '${className}', which the live release still uses`),
+                });
+                continue;
+            }
+            if (!hasDrained(removal.sinceRelease, deployedReleases)) {
+                problems.push({
+                    migration: migration.tag,
+                    statement,
+                    reason: `deletes the Durable Object class '${className}', declared as the second step after release ${removal.sinceRelease}, but ${removal.sinceRelease} is still on live, idle or draining -- wait for it to fully drain, then release this one`,
+                });
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Whether a release's migrations (SQL and Durable Object) may go to idle, given what the
+ * previous live release already applied and which releases are deployed anywhere right now. See
+ * the module docstring for the rule and the removal convention.
+ */
+export function checkMigrationCompatibility(input) {
+    const deployedReleases = input.deployedReleases ?? [];
+    const problems = [
+        ...sqlProblems(input.migrationsJson, input.liveMigrationIds ?? [], deployedReleases),
+        ...doProblems(input.doMigrations ?? [], input.liveDoTag, input.declaredRemovals ?? [], deployedReleases),
+    ];
+    return problems.length === 0 ? { ok: true } : { ok: false, problems };
+}

package/dist/release/run.d.ts

@@ -1,6 +1,22 @@
 import { type Decision, type Observation, type ReleaseEffect, type ReleaseEntryConfig } from './decide.js';
 import { type ReleaseStore } from './state.js';
-import type { Color } from './types.js';
+import { type Color } from './types.js';
+/** What a stage copy request came to. Fixed text only: a reason, a step name or an id. */
+export type StageCopyOutcome = {
+    outcome: 'ok';
+    detail: string;
+    recorded: boolean;
+} | {
+    outcome: 'refused';
+    reason: string;
+} | {
+    outcome: 'failed';
+    step: string;
+}
+/** Another run holds the copy lock: leave the request open and write nothing. */
+ | {
+    outcome: 'busy';
+};
 /** What the runner needs from the outside. Each call is bounded by its own timeout. */
 export interface ReleaseDeps {
     /** The reporting health read for the range, or null when it failed. */
@@ -11,6 +27,17 @@ export interface ReleaseDeps {
     /** The Coolify status and the own-address check of a color. */
     observeColor(color: Color): Promise<Pick<Observation, 'status' | 'address'>>;
     effect(effect: ReleaseEffect): Promise<void>;
+    /**
+     * Runs one stage copy request (the copy can take ~45 minutes); {@link runStageCopy} calls it after the run
+     * that decided on the copy is done. It answers with the outcome and throws only for a lost lock. Absent: the
+     * request is refused with `no-copy-port`.
+     */
+    stageCopy?(request: {
+        mode: 'copy' | 'undo';
+        requestId: number;
+        actor: string;
+        runId?: string;
+    }): Promise<StageCopyOutcome>;
 }
 export interface ReleaseRunResult {
     /** Scope keys to record (null removes one). The caller persists them with the rest of the run. */
@@ -20,6 +47,22 @@ export interface ReleaseRunResult {
     decision: Decision | null;
     /** The requests this run acted on. The caller consumes them with `store.consumeRequests` after it persists `writes`. */
     requestIds: number[];
+    /** A stage copy request was left open because this run does not run copies. */
+    deferredCopy: boolean;
+    /**
+     * The stage copy this run decided on, not yet run. The caller runs it (`runStageCopy`) after it has persisted
+     * `writes` and written the weights, so a rollback decided in the same run never waits for the copy. Its
+     * request is not in `requestIds`: {@link settleStageCopy} says when it is consumed.
+     */
+    copy: StageCopyJob | null;
+}
+/** One stage copy request a run decided to act on. */
+export interface StageCopyJob {
+    mode: 'copy' | 'undo';
+    requestId: number;
+    actor: string;
+    /** The token of the run that took the copy lock. Set by the caller that claims the lock. */
+    runId?: string;
 }
 /**
  * One run for one entry. Reads the recorded keys fresh and the open
@@ -36,4 +79,31 @@ export declare function runRelease(input: {
     deps: ReleaseDeps;
     /** No reporting health read: only hard fails count (see `decide`). */
     hardOnly?: boolean;
+    /** Leave stage copy requests open and untouched (an apply, and the tick's first phase). */
+    deferCopies?: boolean;
 }): Promise<ReleaseRunResult>;
+/** What a finished stage copy writes and whether its request is done. */
+export interface StageCopySettled {
+    writes: Record<string, string | null>;
+    /** Fixed texts for the operator. */
+    refused: string[];
+    /** The request is consumed. False: it stays open (busy, or the first failure). */
+    consume: boolean;
+}
+/**
+ * Runs the copy `job` with `deps.stageCopy` (absent: refused with `no-copy-port`). Call it after the run that
+ * decided on it has persisted its writes and written the weights: the copy takes up to ~45 minutes.
+ */
+export declare function runStageCopy(deps: ReleaseDeps, job: StageCopyJob): Promise<StageCopyOutcome>;
+/**
+ * What a copy outcome records. `ids` are the recorded keys now (the retry mark is read from them). A failure is
+ * retried once, and only a failure before the switch can come back as `failed`: the host reports a failure after
+ * the switch as `ok`, so a retry never sweeps the database stage runs on or its undo target.
+ */
+export declare function settleStageCopy(input: {
+    ids: Readonly<Record<string, string>>;
+    entryKey: string;
+    now: Date;
+    job: StageCopyJob;
+    outcome: StageCopyOutcome;
+}): StageCopySettled;

package/dist/release/run.js

@@ -1,5 +1,9 @@
 import { decide, healthRange, } from './decide.js';
 import { formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
+import { isStageCopyAction } from './types.js';
+const REFUSAL_TEXT = {
+    'no-copy-port': 'copy refused: this host cannot restore',
+};
 /**
  * One run for one entry. Reads the recorded keys fresh and the open
  * requests (it consumes none), decides and runs the effects. A failure, or a
@@ -10,9 +14,25 @@ export async function runRelease(input) {
     const { store, orgId, entryKey, deps, now } = input;
     const ids = await store.getScopeIds(orgId);
     const recorded = recordedFrom(ids, entryKey);
-    if (!recorded)
-        return { writes: {}, blocked: [], refused: [], decision: null, requestIds: [] };
-    const open = await store.openRequests({ orgId, entryKey });
+    if (!recorded) {
+        return {
+            writes: {},
+            blocked: [],
+            refused: [],
+            decision: null,
+            requestIds: [],
+            deferredCopy: false,
+            copy: null,
+        };
+    }
+    const k = releaseKeys(entryKey);
+    const all = await store.openRequests({ orgId, entryKey });
+    // A stage request whose result was persisted before a crash is consumed, never run a second time.
+    const handledId = ids[k.stageCopyHandled];
+    const replayed = all.filter((r) => isStageCopyAction(r.action) && String(r.id) === handledId);
+    const fresh = all.filter((r) => !replayed.includes(r));
+    const deferred = input.deferCopies ? fresh.filter((r) => isStageCopyAction(r.action)) : [];
+    const open = fresh.filter((r) => !deferred.includes(r));
     const actions = open.map((r) => r.action);
     const range = healthRange(recorded, now);
     const target = recorded.release?.to ?? null;
@@ -33,11 +53,25 @@ export async function runRelease(input) {
         observation: { health, ...seen },
         ...(input.hardOnly ? { hardOnly: true } : {}),
     });
-    for (const effect of decision.effects)
-        await deps.effect(effect);
-    const k = releaseKeys(entryKey);
+    const extra = {};
+    const refused = [...decision.refused];
+    const stamp = now.toISOString();
+    let copy = null;
+    const requestOf = (kind) => open.find((r) => r.action.kind === kind);
+    for (const effect of decision.effects) {
+        if (effect.kind !== 'stage_copy') {
+            await deps.effect(effect);
+            continue;
+        }
+        const request = requestOf(effect.mode === 'copy' ? 'copy_prod_to_stage' : 'undo_stage_copy');
+        if (request)
+            copy = { mode: effect.mode, requestId: request.id, actor: request.actor };
+    }
+    if (decision.stageRefusal)
+        extra[k.stageCopy] = `${stamp}|refused|${decision.stageRefusal}`;
     const next = decision.recorded;
     const writes = {
+        ...extra,
         [k.live]: next.live,
         [k.weights]: formatWeights(next.weights),
         [k.digest('blue')]: next.digests.blue,
@@ -54,8 +88,58 @@ export async function runRelease(input) {
     return {
         writes,
         blocked: decision.blocked,
-        refused: decision.refused,
+        refused,
         decision,
-        requestIds: open.map((r) => r.id),
+        requestIds: [...replayed, ...open.filter((r) => r.id !== copy?.requestId)].map((r) => r.id),
+        deferredCopy: deferred.length > 0,
+        copy,
     };
 }
+/**
+ * Runs the copy `job` with `deps.stageCopy` (absent: refused with `no-copy-port`). Call it after the run that
+ * decided on it has persisted its writes and written the weights: the copy takes up to ~45 minutes.
+ */
+export async function runStageCopy(deps, job) {
+    return deps.stageCopy
+        ? deps.stageCopy({
+            mode: job.mode,
+            requestId: job.requestId,
+            actor: job.actor,
+            ...(job.runId ? { runId: job.runId } : {}),
+        })
+        : { outcome: 'refused', reason: 'no-copy-port' };
+}
+/**
+ * What a copy outcome records. `ids` are the recorded keys now (the retry mark is read from them). A failure is
+ * retried once, and only a failure before the switch can come back as `failed`: the host reports a failure after
+ * the switch as `ok`, so a retry never sweeps the database stage runs on or its undo target.
+ */
+export function settleStageCopy(input) {
+    const { ids, outcome: result, job } = input;
+    const k = releaseKeys(input.entryKey);
+    const stamp = input.now.toISOString();
+    const writes = {};
+    const refused = [];
+    if (result.outcome === 'busy')
+        return { writes, refused, consume: false };
+    if (result.outcome === 'ok') {
+        if (!result.recorded)
+            writes[k.stageCopy] = `${stamp}|${result.detail}|ok`;
+        writes[k.stageCopyRetry] = null;
+        return { writes, refused, consume: true };
+    }
+    if (result.outcome === 'refused') {
+        writes[k.stageCopy] = `${stamp}|refused|${result.reason}`;
+        writes[k.stageCopyRetry] = null;
+        refused.push(REFUSAL_TEXT[result.reason] ?? `copy refused: ${result.reason}`);
+        return { writes, refused, consume: true };
+    }
+    writes[k.stageCopy] = `${stamp}|failed|${result.step}`;
+    if (ids[k.stageCopyRetry] === String(job.requestId)) {
+        writes[k.stageCopyRetry] = null;
+        return { writes, refused, consume: true };
+    }
+    // The first failure leaves the request open for the next run; the second consumes it.
+    writes[k.stageCopyRetry] = String(job.requestId);
+    return { writes, refused, consume: false };
+}

package/dist/release/state.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { type Recorded, resolveReleaseConfig } from './decide.js';
-import type { Color, ReleaseAction, ReleaseSignal, ReleaseState, WindowState } from './types.js';
+import type { Color, ReleaseAction, ReleaseSignal, ReleaseState, StageCopyState, WindowState } from './types.js';
 /**
  * The persistence the release runner and Archon share. `getScopeIds` is the
  * recorded `bg.*` keys of an org's applied state (or of the platform, for the
@@ -33,10 +33,21 @@ export declare function releaseKeys(entry: string): {
     digest: (c: Color) => string;
     weights: string;
     stage: string;
+    stageDeploy: string;
     window: string;
     signal: string;
     heldPrefix: string;
     held: (digest: string) => string;
+    /** Set once stage holds the sink env (`bg.<id>.stagesink`, written by the structure apply). */
+    stageSink: string;
+    /** `<ISO time>|<execution id>|ok`, `<ISO time>|undo|ok`, `<ISO time>|refused|<reason>` or `<ISO time>|failed|<step>`. */
+    stageCopy: string;
+    /** `<expiry ms>|<request id>` while a copy runs. An unexpired lock makes another run leave the request open. */
+    stageCopyLock: string;
+    /** The id of the last stage request whose result was persisted: a replay of it is consumed, not run again. */
+    stageCopyHandled: string;
+    /** The id of a request whose copy failed once; a second failure consumes it. */
+    stageCopyRetry: string;
 };
 export declare function formatWeights(w: Record<Color, number>): string;
 export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
@@ -47,6 +58,8 @@ export declare function parseWindow(value: string | undefined): {
 };
 export declare function formatWindow(window: WindowState, release: Recorded['release']): string;
 export declare function recordedFrom(ids: Record<string, string>, entryKey: string): Recorded | null;
+/** Reads `bg.<id>.stagecopy`; a damaged value reads as absent. */
+export declare function parseStageCopy(value: string | undefined): StageCopyState | undefined;
 export declare function readSignal(ids: Record<string, string>, entryKey: string): ReleaseSignal | null;
 /** C2: the release state of one hosting entry, or null before blue/green recorded anything. */
 export declare function readReleaseState(store: ReleaseStore, input: {

package/dist/release/state.js

@@ -10,10 +10,21 @@ export function releaseKeys(entry) {
         digest: (c) => `${p}.digest.${c}`,
         weights: `${p}.weights`,
         stage: `${p}.stage`,
+        stageDeploy: `${p}.stagedeploy`,
         window: `${p}.window`,
         signal: `${p}.signal`,
         heldPrefix: `${p}.held.`,
         held: (digest) => `${p}.held.${digest}`,
+        /** Set once stage holds the sink env (`bg.<id>.stagesink`, written by the structure apply). */
+        stageSink: `${p}.stagesink`,
+        /** `<ISO time>|<execution id>|ok`, `<ISO time>|undo|ok`, `<ISO time>|refused|<reason>` or `<ISO time>|failed|<step>`. */
+        stageCopy: `${p}.stagecopy`,
+        /** `<expiry ms>|<request id>` while a copy runs. An unexpired lock makes another run leave the request open. */
+        stageCopyLock: `${p}.stagecopylock`,
+        /** The id of the last stage request whose result was persisted: a replay of it is consumed, not run again. */
+        stageCopyHandled: `${p}.stagecopyhandled`,
+        /** The id of a request whose copy failed once; a second failure consumes it. */
+        stageCopyRetry: `${p}.stagecopyretry`,
     };
 }
 export function formatWeights(w) {
@@ -87,12 +98,30 @@ export function recordedFrom(ids, entryKey) {
         weights: parseWeights(ids[k.weights]) ?? { ...{ blue: 0, green: 0 }, [live.data]: 100 },
         window,
         release,
+        stageSink: Boolean(ids[k.stageSink]),
         held: Object.keys(ids)
             .filter((key) => key.startsWith(k.heldPrefix))
             .map((key) => key.slice(k.heldPrefix.length))
             .sort(),
     };
 }
+const STAGE_COPY_DETAIL = /^[A-Za-z0-9_-]{1,64}$/;
+/** Reads `bg.<id>.stagecopy`; a damaged value reads as absent. */
+export function parseStageCopy(value) {
+    const parts = (value ?? '').split('|');
+    if (parts.length !== 3)
+        return undefined;
+    const [at, middle, last] = parts;
+    if (Number.isNaN(Date.parse(at)))
+        return undefined;
+    if (last === 'ok') {
+        return STAGE_COPY_DETAIL.test(middle) ? { at, outcome: 'ok', detail: middle } : undefined;
+    }
+    if ((middle === 'refused' || middle === 'failed') && STAGE_COPY_DETAIL.test(last)) {
+        return { at, outcome: middle, detail: last };
+    }
+    return undefined;
+}
 export function readSignal(ids, entryKey) {
     const parsed = signalSchema.safeParse(parseJson(ids[releaseKeys(entryKey).signal]));
     return parsed.success ? parsed.data : null;
@@ -103,6 +132,7 @@ export async function readReleaseState(store, input) {
     const r = recordedFrom(ids, input.entryKey);
     if (!r)
         return null;
+    const stageCopy = parseStageCopy(ids[releaseKeys(input.entryKey).stageCopy]);
     return {
         entryKey: input.entryKey,
         live: r.live,
@@ -113,6 +143,17 @@ export async function readReleaseState(store, input) {
         signal: readSignal(ids, input.entryKey),
         held: r.held,
         config: resolveReleaseConfig(input.entry),
+        ...(stageCopy ? { stageCopy } : {}),
+        ...stageDeployOf(ids[releaseKeys(input.entryKey).stageDeploy]),
+    };
+}
+/** The last stage deploy from `<ISO time>|ok|<commit>` or `<ISO time>|failed|<step>`; nothing for a damaged value. */
+function stageDeployOf(value) {
+    const m = /^([^|]+)\|(ok|failed)\|([^|]*)$/.exec(value ?? '');
+    if (!m || Number.isNaN(Date.parse(m[1])))
+        return {};
+    return {
+        stageDeploy: { at: m[1], outcome: m[2], detail: m[3] },
     };
 }
 const actionSchema = z.discriminatedUnion('kind', [
@@ -123,6 +164,8 @@ const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('approve_step') }),
     z.object({ kind: z.literal('open') }),
     z.object({ kind: z.literal('deploy_stage'), ref: z.string().regex(STAGE_REF_PATTERN) }),
+    z.object({ kind: z.literal('copy_prod_to_stage') }),
+    z.object({ kind: z.literal('undo_stage_copy') }),
 ]);
 /** C2: ask the runner to apply an action on its next run. Archon audits it. */
 export async function requestReleaseAction(store, input) {