@wtfalch/foundry 0.73.0 → 0.74.0

package/dist/release/run.js

@@ -1,7 +1,9 @@
+import { StaleLeaseError } from '../store.js';
 import { decide, healthRange, } from './decide.js';
 import { eventsOf } from './events.js';
-import { formatRefusals, formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
-import { isStageCopyAction } from './types.js';
+import { formatGoLive, parseGoLive, planGoLive, recordWrites, } from './golive.js';
+import { formatRefusals, formatReleased, formatWeights, formatWindow, recordedFrom, releaseKeys, releasedFrom, releasedKey, } from './state.js';
+import { isStageCopyAction, } from './types.js';
 const REFUSAL_TEXT = {
     'no-copy-port': 'copy refused: this host cannot restore',
 };
@@ -23,29 +25,44 @@ export async function runRelease(input) {
             decision: null,
             requestIds: [],
             deferredCopy: false,
+            goLiveOpen: false,
+            claimIds: [],
             copy: null,
             events: [],
         };
     }
     const k = releaseKeys(entryKey);
     // `fanout_retry` belongs to the built-in fan-out (`fanout.ts`), which consumes it; this run leaves it open.
-    const all = (await store.openRequests({ orgId, entryKey })).filter((r) => r.action.kind !== 'fanout_retry');
+    // A request with a time that has not come is left alone whatever the store returned.
+    const all = (await store.openRequests({ orgId, entryKey, now })).filter((r) => r.action.kind !== 'fanout_retry' && !(r.notBefore && Date.parse(r.notBefore) > now.getTime()));
     // 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 due = fresh.filter((r) => !deferred.includes(r));
+    const isRelease = (a) => a.kind === 'go_live' || a.kind === 'set_required';
+    const open = due.filter((r) => !isRelease(r.action));
+    const releaseRequests = due.filter((r) => isRelease(r.action));
     const range = healthRange(recorded, now);
     const target = recorded.release?.to ?? null;
     const health = range && !input.hardOnly ? await deps.readHealth(range) : null;
     const seen = target
         ? await deps.observeColor(target)
         : { status: 'other', address: 'unchecked' };
-    const decision = decide({
+    const go = planReleaseRequests({
+        app: entryKey,
+        requests: releaseRequests,
         recorded,
-        actions,
+        ids,
+        now,
+        owner: input.ownerOrgId === orgId,
+        observation: seen,
+    });
+    const actions = [...open.map((r) => r.action), ...go.actions];
+    const decideWith = (acts) => decide({
+        recorded,
+        actions: acts,
         steps: input.entry.steps,
         stepHoldMinutes: input.entry.stepHoldMinutes,
         advance: input.entry.advance,
@@ -56,12 +73,41 @@ export async function runRelease(input) {
         observation: { health, ...seen },
         ...(input.hardOnly ? { hardOnly: true } : {}),
     });
-    const extra = {};
-    const refused = [...decision.refused];
+    let decision = decideWith(actions);
+    const refused = [...decision.refused, ...go.refused];
     const stamp = now.toISOString();
     let copy = null;
     const requestOf = (kind) => open.find((r) => r.action.kind === kind);
+    // A go-live's idle deploy goes first and may fail: the go-live then stays open and the run goes on without the
+    // promote, so a rollback or any other decision of this run is still persisted.
+    // Claimed before any effect, so a cancel can never race a deploy this run starts.
+    if (go.claim.length > 0) {
+        if (!store.claimRequests)
+            throw new Error('release store cannot claim a go-live');
+        await store.claimRequests(go.claim);
+    }
+    let deployFailed = false;
+    let ran = null;
+    const promoted = go.promote !== undefined && decision.applied.includes(go.promote);
+    const goDeploy = promoted ? decision.effects.find((e) => e.kind === 'deploy') : undefined;
+    if (goDeploy?.kind === 'deploy' && go.appEnv) {
+        const withEnv = { ...goDeploy, appEnv: go.appEnv };
+        try {
+            await deps.effect(withEnv);
+            ran = goDeploy;
+        }
+        catch (error) {
+            if (error instanceof StaleLeaseError)
+                throw error;
+            console.error(`release ${entryKey}: go-live request ${go.requestId}: the idle deploy failed`);
+            deployFailed = true;
+            decision = decideWith(actions.filter((a) => a !== go.promote));
+            refused.push(...decision.refused.filter((line) => !refused.includes(line)));
+        }
+    }
     for (const effect of decision.effects) {
+        if (effect === ran)
+            continue;
         if (effect.kind !== 'stage_copy') {
             await deps.effect(effect);
             continue;
@@ -70,6 +116,9 @@ export async function runRelease(input) {
         if (request)
             copy = { mode: effect.mode, requestId: request.id, actor: request.actor };
     }
+    const finished = go.finish(decision, deployFailed);
+    const extra = {};
+    Object.assign(extra, finished.writes);
     if (decision.stageRefusal)
         extra[k.stageCopy] = `${stamp}|refused|${decision.stageRefusal}`;
     const next = decision.recorded;
@@ -83,7 +132,8 @@ export async function runRelease(input) {
         [k.signal]: decision.signal ? JSON.stringify(decision.signal) : null,
     };
     // Part of the run's writes: persisted with them, so a failed persist leaves neither. A run with none keeps it.
-    const lines = [...refused, ...decision.blocked];
+    const blocked = [...decision.blocked, ...go.blocked];
+    const lines = [...refused, ...blocked];
     if (lines.length > 0)
         writes[k.refused] = formatRefusals(stamp, lines);
     for (const d of recorded.held)
@@ -94,18 +144,24 @@ export async function runRelease(input) {
             writes[k.held(d)] = now.toISOString();
     return {
         writes,
-        blocked: decision.blocked,
+        blocked,
         refused,
         decision,
-        requestIds: [...replayed, ...open.filter((r) => r.id !== copy?.requestId)].map((r) => r.id),
+        requestIds: [
+            ...replayed,
+            ...open.filter((r) => r.id !== copy?.requestId),
+            ...finished.consumed,
+        ].map((r) => r.id),
         deferredCopy: deferred.length > 0,
+        goLiveOpen: finished.goLiveOpen,
+        claimIds: go.claim,
         copy,
         events: eventsOf({
             before: recorded,
             decision,
-            actors: new Map(open.map((r) => [r.action, r.actor])),
+            actors: new Map([...open.map((r) => [r.action, r.actor]), ...go.actors]),
             now,
-        }),
+        }).concat(finished.events),
     };
 }
 /**
@@ -157,3 +213,138 @@ export function settleStageCopy(input) {
     writes[k.stageCopyRetry] = String(job.requestId);
     return { writes, refused, consume: false };
 }
+const NOT_BUILTIN = 'go_live and set_required refused: only the entries boule and agora are released this way';
+/**
+ * The due `go_live` and `set_required` requests of one run. `set_required` takes effect and is consumed at once;
+ * only the due `go_live` with the earliest time is judged per run, the others wait their turn. Nothing here
+ * persists or consumes: the caller does both, in the order of the release runner's rules.
+ */
+function planReleaseRequests(input) {
+    const none = {
+        actions: [],
+        actors: [],
+        claim: [],
+        refused: [],
+        blocked: [],
+        finish: () => ({ writes: {}, consumed: [], events: [], goLiveOpen: false }),
+    };
+    if (input.requests.length === 0 || !input.owner)
+        return none;
+    const { app, requests, recorded, now } = input;
+    if (app !== 'boule' && app !== 'agora') {
+        return {
+            ...none,
+            refused: [NOT_BUILTIN],
+            finish: () => ({
+                writes: {},
+                consumed: requests,
+                claimed: [],
+                events: [],
+                goLiveOpen: false,
+            }),
+        };
+    }
+    const k = releaseKeys(app);
+    const stamp = now.toISOString();
+    let versions = releasedFrom(input.ids, app);
+    const writes = {};
+    const consumed = [];
+    const refused = [];
+    const events = [];
+    for (const r of requests) {
+        if (r.action.kind !== 'set_required')
+            continue;
+        const a = r.action;
+        consumed.push(r);
+        const hit = versions.find((v) => v.tag === a.tag);
+        if (!hit) {
+            refused.push('set_required refused: that tag has not gone live');
+            continue;
+        }
+        const next = { ...hit, required: a.required };
+        versions = versions.map((v) => (v === hit ? next : v));
+        writes[releasedKey(app, hit.release)] = formatReleased(next);
+    }
+    const goRequest = requests
+        .filter((r) => r.action.kind === 'go_live')
+        .sort((a, b) => (a.notBefore ?? '').localeCompare(b.notBefore ?? '') || a.id - b.id)[0];
+    const goAction = goRequest?.action;
+    const plan = goRequest && goAction
+        ? planGoLive({
+            app,
+            action: goAction,
+            requestId: goRequest.id,
+            recorded,
+            ids: input.ids,
+            released: versions,
+            now,
+            observation: input.observation,
+        })
+        : null;
+    const syntheticActions = plan?.actions ?? [];
+    return {
+        actions: syntheticActions,
+        ...(plan?.promote ? { promote: plan.promote } : {}),
+        ...(plan?.appEnv ? { appEnv: plan.appEnv } : {}),
+        actors: goRequest ? syntheticActions.map((a) => [a, goRequest.actor]) : [],
+        claim: goRequest && plan?.claim ? [goRequest.id] : [],
+        ...(goRequest ? { requestId: goRequest.id } : {}),
+        refused: [...refused, ...(plan?.refused ? [plan.refused] : [])],
+        blocked: plan?.blocked ? [plan.blocked] : [],
+        finish(decision, deployFailed) {
+            if (!goRequest || !goAction || !plan)
+                return { writes, consumed, events, goLiveOpen: false };
+            const applied = (a) => a !== undefined && decision.applied.includes(a);
+            const keep = !plan.consume;
+            for (const e of plan.events)
+                events.push({ at: stamp, ...e, actor: goRequest.actor });
+            if (deployFailed) {
+                events.push({
+                    at: stamp,
+                    kind: 'go_live_failed',
+                    reason: 'the idle color could not be deployed',
+                    actor: goRequest.actor,
+                });
+            }
+            const promoted = plan.promote !== undefined && applied(plan.promote) && !deployFailed;
+            if (plan.state !== undefined && !plan.promote) {
+                writes[k.goLive] = plan.state ? formatGoLive(plan.state) : null;
+            }
+            if (plan.promote && plan.appEnv && plan.carry && (promoted || deployFailed)) {
+                // The idle deploy worked: its release number is reserved for this request. It failed: count the try.
+                writes[k.goLive] = formatGoLive({
+                    requestId: goRequest.id,
+                    tries: plan.carry.tries,
+                    release: promoted ? plan.appEnv.release : null,
+                    idle: plan.carry.idle + (promoted ? 0 : 1),
+                });
+            }
+            if (!keep)
+                consumed.push(goRequest);
+            if (plan.record) {
+                const held = parseGoLive(input.ids[k.goLive]);
+                // `planGoLive` records only a tag whose own idle deploy reserved a number.
+                const release = held?.requestId === goRequest.id ? held.release : null;
+                if (release === null)
+                    throw new Error('go-live recorded without a reserved release');
+                const v = {
+                    app,
+                    tag: goAction.tag,
+                    sha: goAction.ref,
+                    release,
+                    required: goAction.required,
+                    requires: goAction.requires,
+                    at: stamp,
+                };
+                Object.assign(writes, recordWrites(v));
+                events.push({ at: stamp, kind: 'released', reason: v.tag, actor: goRequest.actor });
+            }
+            return {
+                writes,
+                consumed,
+                events,
+                goLiveOpen: keep && plan.blocked === undefined,
+            };
+        },
+    };
+}

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, ReleaseEvent, ReleaseSignal, ReleaseState, StageCopyState, WindowState } from './types.js';
+import type { Color, ReleaseAction, ReleaseEvent, ReleaseSignal, ReleaseState, ReleasedVersion, 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
@@ -14,16 +14,61 @@ export interface ReleaseStore {
         entryKey: string;
         action: ReleaseAction;
         actor: string;
+        /** ISO time. The runner sees the request only from then on. Absent: due at once. */
+        notBefore?: string;
     }): Promise<void>;
-    /** The open requests, oldest first. Reading consumes nothing: a run that fails leaves them open. */
+    /**
+     * The open requests that are due, oldest first. Reading consumes nothing: a run that fails leaves them open.
+     * `now` defaults to the database's clock.
+     */
     openRequests(input: {
         orgId: string;
         entryKey: string;
+        now?: Date;
     }): Promise<{
         id: number;
         action: ReleaseAction;
         actor: string;
+        notBefore?: string | null;
     }[]>;
+    /** Marks go-live requests the runner has started. A claimed request cannot be cancelled or moved. */
+    claimRequests(ids: readonly number[]): Promise<void>;
+    /**
+     * Takes back a request that waits for a time; writes the `schedule_cancelled` line in the same transaction.
+     * False when there is no such request: it was consumed, cancelled, claimed, already due, or never had a time.
+     * `now` defaults to the database's clock.
+     */
+    cancelRequest(input: {
+        id: number;
+        orgId: string;
+        entryKey: string;
+        actor: string;
+        now?: Date;
+    }): Promise<boolean>;
+    /** The requests that wait for a time and are not consumed, soonest first. */
+    readScheduled(input: {
+        orgId: string;
+        entryKey: string;
+    }): Promise<{
+        id: number;
+        action: ReleaseAction;
+        notBefore: string;
+        actor: string;
+        claimed: boolean;
+    }[]>;
+    /**
+     * {@link cancelRequest} of `id` and {@link addRequest} of `action` at `notBefore` in one transaction, with the
+     * `schedule_cancelled` and `scheduled` lines. False, and nothing added, when `id` cannot be cancelled.
+     */
+    rescheduleRequest(input: {
+        id: number;
+        orgId: string;
+        entryKey: string;
+        action: ReleaseAction;
+        notBefore: string;
+        actor: string;
+        now?: Date;
+    }): Promise<boolean>;
     /** Marks requests consumed. The runner calls it only after its decision is persisted. */
     consumeRequests(ids: readonly number[]): Promise<void>;
     /** Appends history lines (`foundry_release_events`), oldest first. Nothing is ever updated or deleted. */
@@ -63,10 +108,12 @@ export declare function releaseKeys(entry: string): {
     stageCopyRetry: string;
     /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
     refused: string;
+    /** `<request id>|<stage deploys tried>|<release number or empty>`: where the go-live being run stands. */
+    goLive: string;
 };
 export declare function formatWeights(w: Record<Color, number>): string;
 export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
-export declare const RELEASE_EVENT_KINDS: readonly ["promote", "step", "check", "pause", "resume", "step_now", "approve", "open", "rollback", "passed", "hard_fail", "fanout_done", "fanout_failed"];
+export declare const RELEASE_EVENT_KINDS: readonly ["promote", "step", "check", "pause", "resume", "step_now", "approve", "open", "rollback", "passed", "hard_fail", "fanout_done", "fanout_failed", "scheduled", "schedule_cancelled", "released", "go_live_failed", "go_live_refused"];
 /** What `foundry_release_events.payload` holds: a line's fields besides `at` and `kind`. */
 export declare const releaseEventPayload: z.ZodObject<{
     percent: z.ZodOptional<z.ZodNumber>;
@@ -102,6 +149,11 @@ export declare const releaseEventKind: z.ZodEnum<{
     approve: "approve";
     fanout_done: "fanout_done";
     fanout_failed: "fanout_failed";
+    scheduled: "scheduled";
+    schedule_cancelled: "schedule_cancelled";
+    released: "released";
+    go_live_failed: "go_live_failed";
+    go_live_refused: "go_live_refused";
 }>;
 /** The window JSON is the C2 state plus the active release's `release` field. */
 export declare function parseWindow(value: string | undefined): {
@@ -128,13 +180,39 @@ export declare function readReleaseState(store: ReleaseStore, input: {
     entry?: Parameters<typeof resolveReleaseConfig>[0];
 }): Promise<ReleaseState | null>;
 declare const actionSchema: z.ZodType<ReleaseAction>;
-/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+/** C2: ask the runner to apply an action on its next run. Archon audits it. `notBefore` (a `go_live` only) waits for that time. */
 export declare function requestReleaseAction(store: ReleaseStore, input: {
     orgId: string;
     entryKey: string;
     action: ReleaseAction;
     actor: string;
+    notBefore?: string;
+    /** `DeclaredPlatform.ownerOrgId`: required for `go_live` and `set_required`. */
+    ownerOrgId?: string;
+    /** The clock for the time check; default now. */
+    now?: Date;
 }): Promise<void>;
+/** Moves a queued go-live: cancels `id` and queues `action` at `notBefore` in one transaction. False when `id` is consumed, claimed, cancelled or already due. */
+export declare function rescheduleRelease(store: ReleaseStore, input: {
+    id: number;
+    orgId: string;
+    entryKey: string;
+    action: ReleaseAction;
+    notBefore: string;
+    actor: string;
+    ownerOrgId?: string;
+    now?: Date;
+}): Promise<boolean>;
+/** The applied-state key of one released version: `released.<app>.<release>`. */
+export declare function releasedKey(app: 'boule' | 'agora', release: number): string;
+/** `tag|sha|required|requires|at`; `requires` is comma separated. */
+export declare function formatReleased(v: ReleasedVersion): string;
+/** Reads one `released.*` value; a damaged value reads as absent. */
+export declare function parseReleased(app: 'boule' | 'agora', release: number, value: string | undefined): ReleasedVersion | null;
+/** The released versions of `app` in the owner's applied state, newest first. */
+export declare function releasedFrom(ids: Readonly<Record<string, string>>, app: 'boule' | 'agora'): ReleasedVersion[];
+/** The tags that went live on the owner's Boule or Agora, newest first. A stage-only build is not in it. */
+export declare function readReleasedVersions(store: Pick<ReleaseStore, 'getScopeIds'>, ownerOrgId: string, app: 'boule' | 'agora'): Promise<ReleasedVersion[]>;
 export { actionSchema as releaseActionSchema };
 export declare const RELEASE_HISTORY_DEFAULT_LIMIT = 200;
 export declare const RELEASE_HISTORY_MAX_LIMIT = 1000;

package/dist/release/state.js

@@ -27,6 +27,8 @@ export function releaseKeys(entry) {
         stageCopyRetry: `${p}.stagecopyretry`,
         /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
         refused: `${p}.refused`,
+        /** `<request id>|<stage deploys tried>|<release number or empty>`: where the go-live being run stands. */
+        goLive: `${p}.golive`,
     };
 }
 export function formatWeights(w) {
@@ -80,6 +82,11 @@ export const RELEASE_EVENT_KINDS = [
     'hard_fail',
     'fanout_done',
     'fanout_failed',
+    'scheduled',
+    'schedule_cancelled',
+    'released',
+    'go_live_failed',
+    'go_live_refused',
 ];
 /** What `foundry_release_events.payload` holds: a line's fields besides `at` and `kind`. */
 export const releaseEventPayload = z.object({
@@ -205,6 +212,10 @@ function stageDeployOf(value) {
         stageDeploy: { at: m[1], outcome: m[2], detail: m[3] },
     };
 }
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+/** A tag as a release names it: no `|`, `/` or space, so it fits a key and a `|` separated value. */
+const RELEASE_TAG = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/);
+const BUILTIN_ENTRIES = ['boule', 'agora'];
 const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('promote') }),
     z.object({ kind: z.literal('rollback') }),
@@ -219,11 +230,112 @@ const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('copy_prod_to_stage') }),
     z.object({ kind: z.literal('undo_stage_copy') }),
     z.object({ kind: z.literal('fanout_retry') }),
+    z.object({
+        kind: z.literal('go_live'),
+        tag: RELEASE_TAG,
+        ref: z.string().regex(COMMIT_SHA),
+        required: z.boolean(),
+        requires: z.array(z.enum(['data-service'])),
+    }),
+    z.object({ kind: z.literal('set_required'), tag: RELEASE_TAG, required: z.boolean() }),
 ]);
-/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+const ISO_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/** C2: ask the runner to apply an action on its next run. Archon audits it. `notBefore` (a `go_live` only) waits for that time. */
 export async function requestReleaseAction(store, input) {
     releaseKeys(input.entryKey);
-    await store.addRequest({ ...input, action: actionSchema.parse(input.action) });
+    const action = actionSchema.parse(input.action);
+    assertBuiltinAction(input, action);
+    if (action.kind === 'set_required')
+        await assertReleased(store, input, action.tag);
+    if (action.kind === 'go_live' && input.notBefore === undefined) {
+        throw new Error('go_live needs a time');
+    }
+    if (input.notBefore !== undefined)
+        assertSchedule(action, input.notBefore, input.now);
+    const { ownerOrgId: _owner, now: _now, ...rest } = input;
+    await store.addRequest({ ...rest, action });
+}
+function assertBuiltinAction(input, action) {
+    if (action.kind !== 'go_live' && action.kind !== 'set_required')
+        return;
+    if (!BUILTIN_ENTRIES.includes(input.entryKey)) {
+        throw new Error('go_live and set_required belong to the entry boule or agora');
+    }
+    if (input.ownerOrgId === undefined || input.ownerOrgId !== input.orgId) {
+        throw new Error('go_live and set_required belong to the owner org');
+    }
+}
+async function assertReleased(store, input, tag) {
+    const versions = releasedFrom(await store.getScopeIds(input.orgId), input.entryKey);
+    if (!versions.some((v) => v.tag === tag)) {
+        throw new Error('set_required needs a tag that went live; change the go-live instead');
+    }
+}
+function assertSchedule(action, notBefore, now = new Date()) {
+    if (action.kind !== 'go_live')
+        throw new Error('only go_live can wait for a time');
+    if (!ISO_WITH_ZONE.test(notBefore) || Number.isNaN(Date.parse(notBefore))) {
+        throw new Error('invalid release time: use ISO 8601 with Z or an offset');
+    }
+    if (Date.parse(notBefore) <= now.getTime())
+        throw new Error('the release time is in the past');
+}
+/** Moves a queued go-live: cancels `id` and queues `action` at `notBefore` in one transaction. False when `id` is consumed, claimed, cancelled or already due. */
+export async function rescheduleRelease(store, input) {
+    releaseKeys(input.entryKey);
+    const action = actionSchema.parse(input.action);
+    assertBuiltinAction(input, action);
+    assertSchedule(action, input.notBefore, input.now);
+    const { ownerOrgId: _owner, ...rest } = input;
+    return store.rescheduleRequest({ ...rest, action });
+}
+const RELEASED_PREFIX = 'released.';
+/** The applied-state key of one released version: `released.<app>.<release>`. */
+export function releasedKey(app, release) {
+    return `${RELEASED_PREFIX}${app}.${release}`;
+}
+/** `tag|sha|required|requires|at`; `requires` is comma separated. */
+export function formatReleased(v) {
+    return [v.tag, v.sha, String(v.required), v.requires.join(','), v.at].join('|');
+}
+/** Reads one `released.*` value; a damaged value reads as absent. */
+export function parseReleased(app, release, value) {
+    const parts = (value ?? '').split('|');
+    if (parts.length !== 5)
+        return null;
+    const [tag, sha, required, requires, at] = parts;
+    if (!RELEASE_TAG.safeParse(tag).success || !COMMIT_SHA.test(sha))
+        return null;
+    if (required !== 'true' && required !== 'false')
+        return null;
+    if (Number.isNaN(Date.parse(at)))
+        return null;
+    const list = requires === '' ? [] : requires.split(',');
+    if (!list.every((r) => r === 'data-service'))
+        return null;
+    return { app, tag, sha, release, required: required === 'true', requires: list, at };
+}
+/** The released versions of `app` in the owner's applied state, newest first. */
+export function releasedFrom(ids, app) {
+    const prefix = `${RELEASED_PREFIX}${app}.`;
+    const out = [];
+    for (const key of Object.keys(ids)) {
+        if (!key.startsWith(prefix))
+            continue;
+        const n = key.slice(prefix.length);
+        if (!/^[1-9][0-9]{0,11}$/.test(n))
+            continue;
+        const v = parseReleased(app, Number(n), ids[key]);
+        if (v)
+            out.push(v);
+    }
+    return out.sort((a, b) => b.release - a.release);
+}
+/** The tags that went live on the owner's Boule or Agora, newest first. A stage-only build is not in it. */
+export async function readReleasedVersions(store, ownerOrgId, app) {
+    if (!BUILTIN_ENTRIES.includes(app))
+        throw new Error('invalid released app');
+    return releasedFrom(await store.getScopeIds(ownerOrgId), app);
 }
 export { actionSchema as releaseActionSchema };
 export const RELEASE_HISTORY_DEFAULT_LIMIT = 200;

package/dist/release/types.d.ts

@@ -80,8 +80,11 @@ export interface StageCopyState {
     outcome: 'ok' | 'refused' | 'failed';
     detail: string;
 }
-export type ReleaseAction = {
+export type ReleaseAction = 
+/** `redeploy`: set by a go-live only (a request cannot carry it); promotes the idle color to the commit the live color already runs. */
+{
     kind: 'promote';
+    redeploy?: boolean;
 } | {
     kind: 'rollback';
 } | {
@@ -111,12 +114,55 @@ export type ReleaseAction = {
 /** Owner org, entry key `boule` or `agora`: continue the built-in fan-out from the org that failed. */
  | {
     kind: 'fanout_retry';
+}
+/**
+ * Owner org, entry key `boule` or `agora`: put the tag's commit live. The runner deploys stage at `ref` if stage
+ * differs, deploys the idle color with the tag's `APP_*` env, opens it, and records the {@link ReleasedVersion}
+ * once the release completes (one color at 100 %, window closed). Usually queued with a time.
+ */
+ | {
+    kind: 'go_live';
+    tag: string;
+    ref: string;
+    required: boolean;
+    requires: ReleaseRequirement[];
+}
+/** Owner org, entry key `boule` or `agora`: mark a tag that went live required or not. */
+ | {
+    kind: 'set_required';
+    tag: string;
+    required: boolean;
 };
+/** What a tag needs before a company can take it. `data-service`: the company's data service is applied and its data moved. */
+export type ReleaseRequirement = 'data-service';
+/** One tag that went live on the owner's Boule or Agora. Newest first in {@link readReleasedVersions}. */
+export interface ReleasedVersion {
+    app: 'boule' | 'agora';
+    tag: string;
+    /** The 40-hex commit. */
+    sha: string;
+    /** The UTC second the idle color was deployed with it. The same number on every copy of the tag. */
+    release: number;
+    required: boolean;
+    requires: ReleaseRequirement[];
+    /** ISO time the release completed. */
+    at: string;
+}
 export type ReleaseEventKind = 'promote' | 'step' | 'check' | 'pause' | 'resume' | 'step_now' | 'approve' | 'open' | 'rollback' | 'passed' | 'hard_fail'
 /** The built-in fan-out put an org's copy on the live commit (`reason` is the org slug). */
  | 'fanout_done'
 /** The built-in fan-out stopped at an org (`reason` is `<slug>: <fixed text>`). */
- | 'fanout_failed';
+ | 'fanout_failed'
+/** A go-live was queued for a time (`reason` is `<tag> at <ISO time>`). */
+ | 'scheduled'
+/** A queued go-live was cancelled before its time (`reason` is the tag). */
+ | 'schedule_cancelled'
+/** A tag finished going live: one color at 100 % and the window closed (`reason` is the tag). */
+ | 'released'
+/** A step of a go-live did not work and is tried again by the next tick (`reason` is fixed text). */
+ | 'go_live_failed'
+/** A go-live was refused and its request consumed (`reason` is fixed text). */
+ | 'go_live_refused';
 /** C1: one line of a release's history, written by the release run (`foundry_release_events`). */
 export interface ReleaseEvent {
     at: string;