@wtfalch/foundry 0.73.0 → 0.75.0

package/dist/release/golive.js

@@ -0,0 +1,151 @@
+import { formatReleased, releaseKeys, releasedKey } from './state.js';
+/** A go-live tries each deploy step this many ticks before it is refused. */
+export const GO_LIVE_TRIES = 3;
+export function parseGoLive(value) {
+    const m = /^(\d+)\|(\d+)\|(\d*)(?:\|(\d+))?$/.exec(value ?? '');
+    if (!m)
+        return null;
+    return {
+        requestId: Number(m[1]),
+        tries: Number(m[2]),
+        release: m[3] ? Number(m[3]) : null,
+        idle: m[4] ? Number(m[4]) : 0,
+    };
+}
+export function formatGoLive(s) {
+    return `${s.requestId}|${s.tries}|${s.release ?? ''}|${s.idle}`;
+}
+/**
+ * Decides one `go_live`. Stage is deployed at the tag's commit when it differs, then the idle color is deployed
+ * with the tag's env (`promote`, also for a commit the live color already runs), then it is opened (the staff hold
+ * is passed here: stage was the review) only when the idle color runs and answers, and the request waits until
+ * the release completes, one color at 100 % with the window closed. Only then is the version recorded, and only
+ * when `bg.<entry>.golive` holds the release number this request's own idle deploy reserved: a tag no color
+ * carries is never recorded. Each deploy step is tried `GO_LIVE_TRIES` ticks, a history line for each retry.
+ */
+export function planGoLive(input) {
+    const { action, recorded } = input;
+    const k = releaseKeys(input.app);
+    const state = parseGoLive(input.ids[k.goLive]);
+    const mine = state?.requestId === input.requestId ? state : null;
+    const reserved = mine?.release ?? null;
+    const refuse = (reason) => ({
+        actions: [],
+        record: false,
+        consume: true,
+        claim: false,
+        refused: reason,
+        state: null,
+        events: [{ kind: 'go_live_refused', reason }],
+    });
+    const same = input.released.find((v) => v.tag === action.tag);
+    if (same) {
+        if (same.sha === action.ref) {
+            return { actions: [], record: false, consume: true, claim: false, state: null, events: [] };
+        }
+        return refuse('go_live refused: that tag already went live on another commit');
+    }
+    const rel = recorded.release;
+    if (rel) {
+        // Only the release this request's own idle deploy started carries the tag's env.
+        if (rel.digest !== action.ref || reserved === null) {
+            return {
+                actions: [],
+                record: false,
+                consume: false,
+                claim: false,
+                blocked: 'go live waiting: another release is running',
+                events: [],
+            };
+        }
+        const ready = input.observation.status === 'running' && input.observation.address === 'ok';
+        if (recorded.window.kind === 'staff' && ready) {
+            return {
+                actions: [{ kind: 'open' }],
+                record: false,
+                consume: false,
+                claim: true,
+                events: [],
+            };
+        }
+        return { actions: [], record: false, consume: false, claim: true, events: [] };
+    }
+    // Held first: a rolled-back redeploy of a commit already live still finds that commit live.
+    if (recorded.held.includes(action.ref)) {
+        return refuse('go_live refused: that commit was rolled back and is held');
+    }
+    if (reserved !== null && recorded.digests[recorded.live] === action.ref) {
+        return { actions: [], record: true, consume: true, claim: true, state: null, events: [] };
+    }
+    const tries = mine?.tries ?? 0;
+    const idle = mine?.idle ?? 0;
+    if (recorded.stageDigest === action.ref) {
+        if (idle >= GO_LIVE_TRIES)
+            return refuse('go_live refused: the idle color could not be deployed');
+        const promote = {
+            kind: 'promote',
+            ...(recorded.digests[recorded.live] === action.ref ? { redeploy: true } : {}),
+        };
+        const release = releaseNumber(input.now, input.released);
+        const probe = {
+            app: input.app,
+            tag: action.tag,
+            sha: action.ref,
+            release,
+            required: action.required,
+            requires: action.requires,
+            at: input.now.toISOString(),
+        };
+        return {
+            actions: [promote],
+            promote,
+            record: false,
+            consume: false,
+            claim: true,
+            appEnv: {
+                tag: action.tag,
+                release,
+                minimum: minimumFor([probe, ...input.released], release),
+            },
+            carry: { tries, idle },
+            events: [],
+        };
+    }
+    if (tries >= GO_LIVE_TRIES)
+        return refuse('go_live refused: stage did not take that commit');
+    return {
+        actions: [{ kind: 'deploy_stage', ref: action.ref }],
+        record: false,
+        consume: false,
+        claim: true,
+        state: { requestId: input.requestId, tries: tries + 1, release: null, idle },
+        events: tries > 0
+            ? [
+                {
+                    kind: 'go_live_failed',
+                    reason: `stage did not take that commit (try ${tries} of ${GO_LIVE_TRIES})`,
+                },
+            ]
+            : [],
+    };
+}
+/** The highest release at or below `release` that is required; null when none. */
+export function minimumFor(versions, release) {
+    let min = null;
+    for (const v of versions) {
+        if (v.required && v.release <= release && (min === null || v.release > min))
+            min = v.release;
+    }
+    return min;
+}
+/** A free release number: the unix second of `now`, or the next free one when a version already took it. */
+export function releaseNumber(now, versions) {
+    let n = Math.floor(now.getTime() / 1000);
+    while (versions.some((v) => v.release === n))
+        n += 1;
+    return n;
+}
+/** The scope writes that record `v`. */
+export function recordWrites(v) {
+    return { [releasedKey(v.app, v.release)]: formatReleased(v) };
+}

package/dist/release/run.d.ts

@@ -49,6 +49,10 @@ export interface ReleaseRunResult {
     requestIds: number[];
     /** A stage copy request was left open because this run does not run copies. */
     deferredCopy: boolean;
+    /** The go-live requests this run started: the caller marks them claimed (`store.claimRequests`) after it persists. */
+    claimIds: number[];
+    /** A go-live request is still open and not waiting for another release: the next run may take its next step. */
+    goLiveOpen: 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
@@ -76,8 +80,10 @@ export interface StageCopyJob {
  * the recorded keys as they were: the next run decides again from them.
  */
 export declare function runRelease(input: {
-    store: Pick<ReleaseStore, 'getScopeIds' | 'openRequests'>;
+    store: Pick<ReleaseStore, 'getScopeIds' | 'openRequests'> & Partial<Pick<ReleaseStore, 'claimRequests'>>;
     orgId: string;
+    /** `DeclaredPlatform.ownerOrgId`: only the owner org's go_live and set_required requests run. */
+    ownerOrgId?: string;
     entryKey: string;
     entry: ReleaseEntryConfig;
     now: Date;

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;