@wtfalch/foundry 0.62.0 → 0.63.0

package/dist/plan/stage-signin.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { bgKey } from './blue-green.js';
+/** Tries the broker write this many times (CLAUDE.md, Platform steps, rule 1). */
+export const STAGE_SIGNIN_DELIVERY_TRIES = 3;
+/** The guard value for a subject that does not sign in. */
+export const STAGE_SIGNIN_NONE = 'none';
+/** Fixed text and ids only: safe to log, record and return. */
+export class StageSignInError extends Error {
+    name = 'StageSignInError';
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * Makes stage's client, mints its app key once and writes its broker entry. Order: the client first (its ids
+ * recorded and persisted at once, a lost answer is adopted by name), then the key (held, its ref recorded under
+ * {@link bgKey.stageSignInKey} and persisted before anything is delivered), then the broker entry (retried).
+ * A run that failed halfway finds both and does the rest; the key is never minted twice. When the ref is
+ * recorded but the held store no longer has the key, this stops: it never mints another.
+ */
+export async function ensureStageSignIn(input) {
+    const { id, port } = input;
+    const at = `stage sign-in for ${id}`;
+    let appId = input.recorded()[bgKey.stageClient(id)];
+    let clientId = input.recorded()[bgKey.stageClientId(id)];
+    if (!appId || !clientId) {
+        const found = await port.findClient(port.spec.clientName);
+        if (found) {
+            if (!found.clientId) {
+                throw new StageSignInError(`${at}: client ${found.appId} exists but its id cannot be read`);
+            }
+            appId = found.appId;
+            clientId = found.clientId;
+        }
+        else {
+            const created = await port.createClient(port.spec);
+            appId = created.appId;
+            clientId = created.clientId;
+        }
+        input.record(bgKey.stageClient(id), appId);
+        input.record(bgKey.stageClientId(id), clientId);
+        await input.persist();
+    }
+    // One mint: the key goes to the held store, its ref is recorded and persisted, and only then is it used.
+    let appKey = await port.held.resolve();
+    if (appKey) {
+        input.secret(appKey);
+    }
+    else {
+        if (input.recorded()[bgKey.stageSignInKey(id)]) {
+            throw new StageSignInError(`${at}: key ${port.held.ref} was minted but is no longer held; restore the held value`);
+        }
+        appKey = input.generate();
+        input.secret(appKey);
+        await port.held.put(appKey);
+        input.record(bgKey.stageSignInKey(id), port.held.ref);
+        await input.persist();
+    }
+    const entry = {
+        name: port.spec.brokerName,
+        organizationId: port.spec.organizationId,
+        clientId,
+        origins: port.spec.origins,
+        from: port.spec.from,
+        registration: port.spec.registration,
+        ...(port.spec.emailLink === undefined ? {} : { emailLink: port.spec.emailLink }),
+    };
+    const sleep = input.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 1;; attempt++) {
+        try {
+            await port.writeBrokerEntry(entry, appKey);
+            break;
+        }
+        catch {
+            // The cause can echo the key; the ref is all a reader needs.
+            if (attempt >= STAGE_SIGNIN_DELIVERY_TRIES) {
+                throw new StageSignInError(`${at}: delivering key ${port.held.ref} to the broker entry ${port.spec.brokerName} failed after ${STAGE_SIGNIN_DELIVERY_TRIES} tries`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+    input.record(bgKey.stageBroker(id), JSON.stringify({ name: entry.name, organizationId: entry.organizationId }));
+    await input.persist();
+    return {
+        env: [
+            { key: 'AUTH_CLIENT_ID', value: clientId },
+            { key: 'AUTH_APP_KEY', value: appKey },
+        ],
+        guard: stageSignInGuard({ appId, clientId, brokerName: entry.name, origins: entry.origins }),
+    };
+}
+/** `ok:<sha256 of the ids>`: the client, the app, the broker entry's name and its origins. No value goes in. */
+export function stageSignInGuard(input) {
+    return `ok:${sha256(JSON.stringify([input.appId, input.clientId, input.brokerName, [...input.origins].sort()]))}`;
+}
+/** Whether the recorded `bg.<id>.stagesignin` lets the copy go on. */
+export const stageSignInReady = (value) => value === STAGE_SIGNIN_NONE || value?.startsWith('ok:') === true;
+/**
+ * Makes the public client of a static SPA's stage (Agora): found by name or created, its ids recorded and
+ * persisted at once. There is no key and no broker entry, so nothing secret exists. The guard hashes the app id,
+ * the client id, the client name and the origins.
+ */
+export async function ensureStagePublicClient(input) {
+    const { id, port } = input;
+    const at = `stage sign-in for ${id}`;
+    let appId = input.recorded()[bgKey.stageClient(id)];
+    let clientId = input.recorded()[bgKey.stageClientId(id)];
+    if (!appId || !clientId) {
+        const found = await port.findClient(port.spec.clientName);
+        if (found) {
+            if (!found.clientId) {
+                throw new StageSignInError(`${at}: client ${found.appId} exists but its id cannot be read`);
+            }
+            appId = found.appId;
+            clientId = found.clientId;
+        }
+        else {
+            const created = await port.createClient(port.spec);
+            appId = created.appId;
+            clientId = created.clientId;
+        }
+        input.record(bgKey.stageClient(id), appId);
+        input.record(bgKey.stageClientId(id), clientId);
+        await input.persist();
+    }
+    return {
+        clientId,
+        guard: stageSignInGuard({
+            appId,
+            clientId,
+            brokerName: port.spec.clientName,
+            origins: port.spec.origins,
+        }),
+    };
+}

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

@@ -26,6 +26,8 @@ type SinkOrg = Pick<DeclaredOrg, 'slug'>;
 export declare const stageSinkAppName: (org: SinkOrg) => string;
 /** The sink's HTTP address on the company's Docker network. */
 export declare const stageSinkInternalUrl: (org: SinkOrg) => string;
+/** The sender stage mails carry. Apps send only when `MAIL_FROM` is set; the address cannot receive mail. */
+export declare const STAGE_MAIL_FROM = "Stage <noreply@stage.invalid>";
 /**
  * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
  * so stage holds no mail token and no Lettermint setting.

package/dist/plan/stage-sink.js

@@ -24,10 +24,15 @@ export const STAGE_SINK_VERSION = 1;
 export const stageSinkAppName = (org) => `${org.slug}-stage-sink`;
 /** The sink's HTTP address on the company's Docker network. */
 export const stageSinkInternalUrl = (org) => `http://${stageSinkAppName(org)}:${STAGE_SINK_HTTP_PORT}`;
+/** The sender stage mails carry. Apps send only when `MAIL_FROM` is set; the address cannot receive mail. */
+export const STAGE_MAIL_FROM = 'Stage <noreply@stage.invalid>';
 /**
  * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
  * so stage holds no mail token and no Lettermint setting.
  */
 export function stageMailEnv(org) {
-    return [{ key: 'MAIL_SINK_URL', value: stageSinkInternalUrl(org) }];
+    return [
+        { key: 'MAIL_SINK_URL', value: stageSinkInternalUrl(org) },
+        { key: 'MAIL_FROM', value: STAGE_MAIL_FROM },
+    ];
 }

package/dist/platform.d.ts

@@ -72,7 +72,7 @@ export declare function uptimeArtifactUrl(tag: string): string;
  * holds the Cloudflare token `<username>.<org domain>` claims use, so no
  * hosting entry ever holds that credential itself.
  */
-export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon' | 'edge' | 'hc' | 'coolify';
+export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon' | 'edge' | 'hc' | 'registry' | 'coolify';
 export declare const PLATFORM_SERVICE_KEYS: readonly PlatformServiceKey[];
 /**
  * The one shared platform every org's services run on -- decided in #165 as
@@ -123,6 +123,12 @@ export interface DeclaredPlatform {
      * `plan/platform-diff.ts`'s `planHeartbeats`.
      */
     hc: PlatformService;
+    /**
+     * The platform's image registry (`registry:3`, htpasswd sign-in): the images the build workflow
+     * pushes and the company servers pull. `gitRef` is the image tag, pinned by digest in
+     * `versions.json` like `hc`'s. See `plan/platform-registry.ts`.
+     */
+    registry: PlatformService;
     /**
      * The Coolify panel. Its address is declared so the platform's hostnames
      * include it; foundry never deploys it, so `enabled` stays false and

package/dist/platform.js

@@ -15,6 +15,7 @@ export const PLATFORM_SERVICE_KEYS = [
     'archon',
     'edge',
     'hc',
+    'registry',
     'coolify',
 ];
 /** The only values {@link DeclaredPlatform.heartbeatsProvider} may hold. */

package/dist/release/decide.d.ts

@@ -51,6 +51,8 @@ export interface Recorded {
     /** Set while window.kind is step, inconclusive, window or cap. */
     release: ActiveRelease | null;
     held: string[];
+    /** Stage holds the sink env. Absent reads as no. */
+    stageSink?: boolean;
 }
 export interface ColorCounts {
     requests: number;
@@ -85,6 +87,14 @@ export type ReleaseEffect = {
  | {
     kind: 'deploy_stage';
     ref: string;
+}
+/**
+ * Run the stage copy (or undo it) for the first open request of that kind. The runner does not execute it: it
+ * hands it to its caller, who runs it after this run's other effects, writes and weights are done.
+ */
+ | {
+    kind: 'stage_copy';
+    mode: 'copy' | 'undo';
 };
 export interface Decision {
     recorded: Recorded;
@@ -94,6 +104,8 @@ export interface Decision {
     blocked: string[];
     /** Actions that changed nothing, with a fixed reason. */
     refused: string[];
+    /** The reason a `copy_prod_to_stage` request was refused here, for `bg.<id>.stagecopy`; else null. */
+    stageRefusal: string | null;
 }
 export declare function normalizeSteps(steps: readonly number[] | undefined): number[];
 /** The time a health read should cover: from the step or window start to now. */

package/dist/release/decide.js

@@ -81,6 +81,7 @@ function applyActions(r, actions, now, out, kind) {
     let ended = false;
     let approved = false;
     let opened = false;
+    const stageRequests = [];
     for (const a of actions) {
         if (a.kind === 'deploy_stage') {
             if (typeof a.ref === 'string' && STAGE_REF_PATTERN.test(a.ref))
@@ -135,6 +136,9 @@ function applyActions(r, actions, now, out, kind) {
                 promoted = true;
             }
         }
+        else if (a.kind === 'copy_prod_to_stage' || a.kind === 'undo_stage_copy') {
+            stageRequests.push(a.kind);
+        }
         else if (a.kind === 'rollback') {
             if (!cur.release)
                 out.refused.push('rollback refused: no release is running');
@@ -157,6 +161,26 @@ function applyActions(r, actions, now, out, kind) {
             }
         }
     }
+    // The stage requests are judged last, against the release the other actions of this run left.
+    for (const kind of stageRequests) {
+        const copy = kind === 'copy_prod_to_stage';
+        const name = copy ? 'copy' : 'undo';
+        if (out.effects.some((e) => e.kind === 'stage_copy')) {
+            out.refused.push(`${name} refused: one stage copy request runs at a time`);
+        }
+        else if (cur.release) {
+            // A copy takes up to ~45 minutes; a release that is stepping needs the runner free to roll back.
+            out.refused.push(`${name} refused: a release is running`);
+            out.stageRefusal = 'release';
+        }
+        else if (copy && !cur.stageSink) {
+            out.refused.push('copy refused: stage sink is not applied');
+            out.stageRefusal = 'sink';
+        }
+        else {
+            out.effects.push({ kind: 'stage_copy', mode: copy ? 'copy' : 'undo' });
+        }
+    }
     return { recorded: cur, promoted, ended, approved, opened };
 }
 /**
@@ -168,7 +192,11 @@ export function decide(input) {
     const { now, observation } = input;
     const steps = normalizeSteps(input.steps);
     const holdMs = (input.stepHoldMinutes ?? DEFAULT_STEP_HOLD_MINUTES) * MINUTE;
-    const out = { effects: [], refused: [] };
+    const out = {
+        effects: [],
+        refused: [],
+        stageRefusal: null,
+    };
     const advance = input.advance ?? DEFAULT_ADVANCE;
     const minRequests = input.minRequests ?? RELATIVE_MIN_REQUESTS;
     const errorMargin = input.errorMargin ?? ERROR_RATE_MARGIN;
@@ -285,7 +313,14 @@ export function decide(input) {
     }
     if (r.window.kind === 'cap')
         blocked.push('release window reached the cap without enough data: pass or roll back in Archon');
-    return { recorded: r, signal, effects: out.effects, blocked, refused: out.refused };
+    return {
+        recorded: r,
+        signal,
+        effects: out.effects,
+        blocked,
+        refused: out.refused,
+        stageRefusal: out.stageRefusal,
+    };
 }
 function stepTo(r, rel, percent, now) {
     const at = now.toISOString();

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) {