@wtfalch/foundry 0.64.0 → 0.66.0

package/dist/release/decide.js

@@ -68,7 +68,11 @@ function dailyRate(h) {
 /** The time a health read should cover: from the step or window start to now. */
 export function healthRange(r, now) {
     const w = r.window;
-    if (w.kind === 'step' || w.kind === 'inconclusive' || w.kind === 'window' || w.kind === 'cap') {
+    if (w.kind === 'step' ||
+        w.kind === 'inconclusive' ||
+        w.kind === 'paused' ||
+        w.kind === 'window' ||
+        w.kind === 'cap') {
         if (w.kind === 'inconclusive' && w.percent === 0)
             return null;
         return { from: w.since, to: now.toISOString() };
@@ -81,6 +85,7 @@ function applyActions(r, actions, now, out, kind) {
     let ended = false;
     let approved = false;
     let opened = false;
+    let stepNow = false;
     const stageRequests = [];
     for (const a of actions) {
         if (a.kind === 'deploy_stage') {
@@ -97,8 +102,10 @@ function applyActions(r, actions, now, out, kind) {
             const waiting = (kind.advance === 'approval' || capped) &&
                 cur.release !== null &&
                 ((w.kind === 'step' && w.percent > 0) || (w.kind === 'inconclusive' && w.percent > 0));
-            if (waiting)
+            if (waiting) {
                 approved = true;
+                out.applied.push(a);
+            }
             else
                 out.refused.push('approve_step refused: no step is waiting for approval');
         }
@@ -106,10 +113,42 @@ function applyActions(r, actions, now, out, kind) {
             if (cur.window.kind === 'staff' && cur.release) {
                 cur = stepTo(cur, cur.release, kind.steps[0], now);
                 opened = true;
+                out.applied.push(a);
             }
             else
                 out.refused.push('open refused: no release is waiting for staff');
         }
+        else if (a.kind === 'pause') {
+            const w = cur.window;
+            if (w.kind === 'paused')
+                out.refused.push('pause refused: the release is already paused');
+            else if (cur.release && (w.kind === 'step' || (w.kind === 'inconclusive' && w.percent > 0))) {
+                cur = { ...cur, window: { kind: 'paused', percent: w.percent, since: w.since } };
+                stepNow = false;
+                out.applied.push(a);
+            }
+            else
+                out.refused.push('pause refused: no step is running');
+        }
+        else if (a.kind === 'resume') {
+            const w = cur.window;
+            if (w.kind === 'paused' && cur.release) {
+                cur = { ...cur, window: { kind: 'step', percent: w.percent, since: w.since } };
+                out.applied.push(a);
+            }
+            else
+                out.refused.push('resume refused: the release is not paused');
+        }
+        else if (a.kind === 'step_now') {
+            const w = cur.window;
+            if (cur.release &&
+                (w.kind === 'step' || w.kind === 'paused' || (w.kind === 'inconclusive' && w.percent > 0))) {
+                stepNow = true;
+                out.applied.push(a);
+            }
+            else
+                out.refused.push('step_now refused: no step is running');
+        }
         else if (a.kind === 'clear_held') {
             cur = { ...cur, held: cur.held.filter((d) => d !== a.digest) };
         }
@@ -134,6 +173,7 @@ function applyActions(r, actions, now, out, kind) {
                 };
                 out.effects.push({ kind: 'deploy', color: to, digest });
                 promoted = true;
+                out.applied.push(a);
             }
         }
         else if (a.kind === 'copy_prod_to_stage' || a.kind === 'undo_stage_copy') {
@@ -145,6 +185,7 @@ function applyActions(r, actions, now, out, kind) {
             else {
                 cur = rollback(cur, now, 'operator');
                 ended = true;
+                out.applied.push(a);
             }
         }
         else if (a.kind === 'decide_at_cap') {
@@ -153,11 +194,13 @@ function applyActions(r, actions, now, out, kind) {
             else if (a.decision === 'rollback') {
                 cur = rollback(cur, now, 'operator at cap');
                 ended = true;
+                out.applied.push(a);
             }
             else {
                 out.effects.push({ kind: 'stop', color: cur.release.from });
                 cur = { ...cur, window: { kind: 'passed', at: now.toISOString() }, release: null };
                 ended = true;
+                out.applied.push(a);
             }
         }
     }
@@ -181,7 +224,7 @@ function applyActions(r, actions, now, out, kind) {
             out.effects.push({ kind: 'stage_copy', mode: copy ? 'copy' : 'undo' });
         }
     }
-    return { recorded: cur, promoted, ended, approved, opened };
+    return { recorded: cur, promoted, ended, approved, opened, stepNow };
 }
 /**
  * The whole release decision for one run: from the recorded state, the
@@ -196,6 +239,7 @@ export function decide(input) {
         effects: [],
         refused: [],
         stageRefusal: null,
+        applied: [],
     };
     const advance = input.advance ?? DEFAULT_ADVANCE;
     const minRequests = input.minRequests ?? RELATIVE_MIN_REQUESTS;
@@ -268,19 +312,31 @@ export function decide(input) {
                     };
                     if (!atWindow) {
                         const pct = r.window.percent;
+                        const paused = r.window.kind === 'paused';
                         const holdDone = elapsed >= holdMs;
-                        const stepUp = advance === 'time'
-                            ? holdDone && verdict !== 'fail'
-                            : advance === 'signal'
-                                ? (holdDone && verdict === 'pass') || (applied.approved && verdict !== 'fail')
-                                : applied.approved && verdict !== 'fail';
-                        if (applied.approved && advance !== 'time' && verdict === 'fail')
+                        const nowStep = applied.stepNow && verdict !== 'fail';
+                        // A pause holds the step: only step_now leaves it. Hard fails and failed checks still roll back above.
+                        const stepUp = paused
+                            ? nowStep
+                            : nowStep ||
+                                (advance === 'time'
+                                    ? holdDone && verdict !== 'fail'
+                                    : advance === 'signal'
+                                        ? (holdDone && verdict === 'pass') || (applied.approved && verdict !== 'fail')
+                                        : applied.approved && verdict !== 'fail');
+                        if (applied.approved && advance !== 'time' && verdict === 'fail') {
                             out.refused.push('approve_step refused: the error rate is failing');
+                            out.applied = out.applied.filter((x) => x.kind !== 'approve_step');
+                        }
+                        if (applied.stepNow && verdict === 'fail') {
+                            out.refused.push('step_now refused: the error rate is failing');
+                            out.applied = out.applied.filter((x) => x.kind !== 'step_now');
+                        }
                         if (stepUp) {
                             const next = steps.find((s) => s > pct);
                             r = stepTo(r, rel, next, now);
                         }
-                        else {
+                        else if (!paused) {
                             const kind = verdict === 'inconclusive' ? 'inconclusive' : 'step';
                             r = {
                                 ...r,
@@ -320,6 +376,7 @@ export function decide(input) {
         blocked,
         refused: out.refused,
         stageRefusal: out.stageRefusal,
+        applied: out.applied,
     };
 }
 function stepTo(r, rel, percent, now) {

package/dist/release/events.d.ts

@@ -0,0 +1,13 @@
+import type { Decision, Recorded } from './decide.js';
+import type { ReleaseAction, ReleaseEvent } from './types.js';
+/**
+ * The history lines of one run: the actions that took effect, then the check, then what the run did with the
+ * release (a step, a pass, a rollback or a hard fail). Pure: `before` is what the run read, `decision` what it
+ * decided. `actors` names who asked for each requested action (by the action object `decide` was given).
+ */
+export declare function eventsOf(input: {
+    before: Recorded;
+    decision: Decision;
+    actors: ReadonlyMap<ReleaseAction, string>;
+    now: Date;
+}): ReleaseEvent[];

package/dist/release/events.js

@@ -0,0 +1,67 @@
+const percentOf = (w) => w.kind === 'step' || w.kind === 'inconclusive' || w.kind === 'paused' ? w.percent : undefined;
+/**
+ * The history lines of one run: the actions that took effect, then the check, then what the run did with the
+ * release (a step, a pass, a rollback or a hard fail). Pure: `before` is what the run read, `decision` what it
+ * decided. `actors` names who asked for each requested action (by the action object `decide` was given).
+ */
+export function eventsOf(input) {
+    const { before, decision, actors } = input;
+    const after = decision.recorded;
+    const at = input.now.toISOString();
+    const events = [];
+    const percent = percentOf(before.window) ?? percentOf(after.window);
+    const withPercent = percent === undefined ? {} : { percent };
+    const actorOf = (action) => {
+        const actor = action ? actors.get(action) : undefined;
+        return actor ? { actor } : {};
+    };
+    for (const a of decision.applied) {
+        if (a.kind === 'promote' && after.release) {
+            events.push({
+                at,
+                kind: 'promote',
+                release: { from: after.release.from, to: after.release.to },
+                ...actorOf(a),
+            });
+        }
+        else if (a.kind === 'approve_step') {
+            events.push({ at, kind: 'approve', ...withPercent, ...actorOf(a) });
+        }
+        else if (a.kind === 'open' ||
+            a.kind === 'pause' ||
+            a.kind === 'resume' ||
+            a.kind === 'step_now') {
+            events.push({ at, kind: a.kind, ...withPercent, ...actorOf(a) });
+        }
+    }
+    if (decision.signal)
+        events.push({ at, kind: 'check', ...withPercent, signal: decision.signal });
+    const w = after.window;
+    const release = before.release
+        ? { release: { from: before.release.from, to: before.release.to } }
+        : {};
+    const operator = decision.applied.find((a) => a.kind === 'rollback' || a.kind === 'decide_at_cap');
+    const was = before.window;
+    const newStep = w.kind === 'step'
+        ? !('percent' in was && 'since' in was && was.percent === w.percent && was.since === w.since)
+        : w.kind === 'window' && was.kind !== 'window';
+    if (newStep && (w.kind === 'step' || w.kind === 'window')) {
+        events.push({ at, kind: 'step', percent: w.kind === 'step' ? w.percent : 100 });
+    }
+    else if (w.kind === 'rolled_back' && was.kind !== 'rolled_back') {
+        const hard = w.reason.startsWith('hard fail');
+        events.push({
+            at,
+            kind: hard ? 'hard_fail' : 'rollback',
+            ...withPercent,
+            reason: w.reason,
+            ...release,
+            ...(hard && decision.signal ? { signal: decision.signal } : {}),
+            ...(w.reason.startsWith('operator') ? actorOf(operator) : {}),
+        });
+    }
+    else if (w.kind === 'passed' && was.kind !== 'passed') {
+        events.push({ at, kind: 'passed', ...release, ...actorOf(operator) });
+    }
+    return events;
+}

package/dist/release/health.d.ts

@@ -6,6 +6,11 @@ export declare const HEALTH_READ_TIMEOUT_MS = 10000;
 export declare const ADDRESS_CHECK_TIMEOUT_MS = 10000;
 /** A health body larger than this is refused unread (a runaway or hostile response must not fill memory). */
 export declare const HEALTH_BODY_MAX_BYTES: number;
+/**
+ * The response body as text, or null when it is larger than {@link HEALTH_BODY_MAX_BYTES}. Reads in chunks and
+ * stops at the cap, so an endless body is never held.
+ */
+export declare function readCappedText(res: Response, maxBytes?: number): Promise<string | null>;
 /** C1's 200 body. */
 export declare const healthBody: z.ZodObject<{
     colors: z.ZodObject<{

package/dist/release/health.js

@@ -9,9 +9,9 @@ export const HEALTH_BODY_MAX_BYTES = 64 * 1024;
  * The response body as text, or null when it is larger than {@link HEALTH_BODY_MAX_BYTES}. Reads in chunks and
  * stops at the cap, so an endless body is never held.
  */
-async function readCappedText(res) {
+export async function readCappedText(res, maxBytes = HEALTH_BODY_MAX_BYTES) {
     const declared = Number(res.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > HEALTH_BODY_MAX_BYTES)
+    if (Number.isFinite(declared) && declared > maxBytes)
         return null;
     if (!res.body)
         return '';
@@ -23,7 +23,7 @@ async function readCappedText(res) {
         if (done)
             break;
         total += value.byteLength;
-        if (total > HEALTH_BODY_MAX_BYTES) {
+        if (total > maxBytes) {
             await reader.cancel().catch(() => undefined);
             return null;
         }

package/dist/release/run.d.ts

@@ -1,6 +1,6 @@
 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, type ReleaseEvent } 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';
@@ -55,6 +55,11 @@ export interface ReleaseRunResult {
      * request is not in `requestIds`: {@link settleStageCopy} says when it is consumed.
      */
     copy: StageCopyJob | null;
+    /**
+     * The history lines of this run (`foundry_release_events`). The caller appends them with `store.appendEvents`
+     * after it persists `writes`, so a run that fails leaves none.
+     */
+    events: ReleaseEvent[];
 }
 /** One stage copy request a run decided to act on. */
 export interface StageCopyJob {
@@ -71,7 +76,7 @@ export interface StageCopyJob {
  * the recorded keys as they were: the next run decides again from them.
  */
 export declare function runRelease(input: {
-    store: ReleaseStore;
+    store: Pick<ReleaseStore, 'getScopeIds' | 'openRequests'>;
     orgId: string;
     entryKey: string;
     entry: ReleaseEntryConfig;

package/dist/release/run.js

@@ -1,5 +1,6 @@
 import { decide, healthRange, } from './decide.js';
-import { formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
+import { eventsOf } from './events.js';
+import { formatRefusals, formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
 import { isStageCopyAction } from './types.js';
 const REFUSAL_TEXT = {
     'no-copy-port': 'copy refused: this host cannot restore',
@@ -23,6 +24,7 @@ export async function runRelease(input) {
             requestIds: [],
             deferredCopy: false,
             copy: null,
+            events: [],
         };
     }
     const k = releaseKeys(entryKey);
@@ -79,6 +81,10 @@ export async function runRelease(input) {
         [k.window]: formatWindow(next.window, next.release),
         [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];
+    if (lines.length > 0)
+        writes[k.refused] = formatRefusals(stamp, lines);
     for (const d of recorded.held)
         if (!next.held.includes(d))
             writes[k.held(d)] = null;
@@ -93,6 +99,12 @@ export async function runRelease(input) {
         requestIds: [...replayed, ...open.filter((r) => r.id !== copy?.requestId)].map((r) => r.id),
         deferredCopy: deferred.length > 0,
         copy,
+        events: eventsOf({
+            before: recorded,
+            decision,
+            actors: new Map(open.map((r) => [r.action, r.actor])),
+            now,
+        }),
     };
 }
 /**
@@ -132,6 +144,7 @@ export function settleStageCopy(input) {
         writes[k.stageCopy] = `${stamp}|refused|${result.reason}`;
         writes[k.stageCopyRetry] = null;
         refused.push(REFUSAL_TEXT[result.reason] ?? `copy refused: ${result.reason}`);
+        writes[k.refused] = formatRefusals(stamp, refused);
         return { writes, refused, consume: true };
     }
     writes[k.stageCopy] = `${stamp}|failed|${result.step}`;

package/dist/release/series.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import type { ReleaseSeries } from './types.js';
+/** The reporting series read has this long to answer. */
+export declare const SERIES_READ_TIMEOUT_MS = 15000;
+/** 8 days of 10-minute buckets is about 1150 buckets of about 300 bytes; a larger body is refused unread. */
+export declare const SERIES_BODY_MAX_BYTES: number;
+/** The longest range reporting serves. */
+export declare const SERIES_MAX_DAYS = 8;
+export declare const SERIES_BUCKET_MINUTES: readonly [10, 20, 60];
+/** C2's 200 body. */
+export declare const seriesBody: z.ZodObject<{
+    bucketMinutes: z.ZodNumber;
+    buckets: z.ZodArray<z.ZodObject<{
+        start: z.ZodString;
+        colors: z.ZodObject<{
+            blue: z.ZodObject<{
+                requests: z.ZodNumber;
+                errors: z.ZodNumber;
+                slow: z.ZodNumber;
+                durationMsSum: z.ZodNumber;
+                signIns: z.ZodNumber;
+                signInFailures: z.ZodNumber;
+            }, z.core.$strip>;
+            green: z.ZodObject<{
+                requests: z.ZodNumber;
+                errors: z.ZodNumber;
+                slow: z.ZodNumber;
+                durationMsSum: z.ZodNumber;
+                signIns: z.ZodNumber;
+                signInFailures: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export interface ReleaseSeriesQuery {
+    from: string;
+    to: string;
+    /** Bucket minutes: 10, 20 (default) or 60. */
+    bucket?: (typeof SERIES_BUCKET_MINUTES)[number];
+}
+/**
+ * `GET <address>/api/reporting/release-series?from&to&bucket` with the bearer token. Returns null for any
+ * failure (a bad range, network, timeout, status, body shape): the page then shows no chart rather than a wrong
+ * one. Nothing about the response or the token reaches a log or an error.
+ */
+export declare function fetchReleaseSeries(input: {
+    address: string;
+    token: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    query: ReleaseSeriesQuery;
+}): Promise<ReleaseSeries | null>;
+/** Something that can read one entry's series: a {@link import('../plan/release-host.js').ReleaseHost}. */
+export interface ReleaseSeriesHost {
+    readSeries?(entry: string, query: ReleaseSeriesQuery): Promise<ReleaseSeries | null>;
+}
+/** C2: the entry's requests, errors, slow requests and sign-ins per bucket and color, or null when unavailable. */
+export declare function readReleaseSeries(host: ReleaseSeriesHost, entry: string, query: ReleaseSeriesQuery): Promise<ReleaseSeries | null>;

package/dist/release/series.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { readCappedText } from './health.js';
+/** The reporting series read has this long to answer. */
+export const SERIES_READ_TIMEOUT_MS = 15_000;
+/** 8 days of 10-minute buckets is about 1150 buckets of about 300 bytes; a larger body is refused unread. */
+export const SERIES_BODY_MAX_BYTES = 1024 * 1024;
+/** The longest range reporting serves. */
+export const SERIES_MAX_DAYS = 8;
+export const SERIES_BUCKET_MINUTES = [10, 20, 60];
+const count = z.number().finite().nonnegative();
+const color = z.object({
+    requests: count,
+    errors: count,
+    slow: count,
+    durationMsSum: count,
+    signIns: count,
+    signInFailures: count,
+});
+/** C2's 200 body. */
+export const seriesBody = z.object({
+    bucketMinutes: z.number().int().positive(),
+    buckets: z.array(z.object({
+        start: z.string().refine((v) => !Number.isNaN(Date.parse(v))),
+        colors: z.object({ blue: color, green: color }),
+    })),
+});
+/**
+ * `GET <address>/api/reporting/release-series?from&to&bucket` with the bearer token. Returns null for any
+ * failure (a bad range, network, timeout, status, body shape): the page then shows no chart rather than a wrong
+ * one. Nothing about the response or the token reaches a log or an error.
+ */
+export async function fetchReleaseSeries(input) {
+    const { from, to } = input.query;
+    const bucket = input.query.bucket ?? 20;
+    const span = Date.parse(to) - Date.parse(from);
+    if (!(span > 0) || span > SERIES_MAX_DAYS * 86_400_000)
+        return null;
+    if (!SERIES_BUCKET_MINUTES.includes(bucket))
+        return null;
+    try {
+        const url = new URL('/api/reporting/release-series', input.address);
+        url.searchParams.set('from', from);
+        url.searchParams.set('to', to);
+        url.searchParams.set('bucket', String(bucket));
+        const res = await (input.fetchImpl ?? fetch)(url, {
+            headers: { ...input.headers, authorization: `Bearer ${input.token}` },
+            signal: AbortSignal.timeout(SERIES_READ_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const text = await readCappedText(res, SERIES_BODY_MAX_BYTES);
+        if (text === null)
+            return null;
+        const parsed = seriesBody.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        // Network error, timeout or invalid JSON: all the same to the caller.
+        return null;
+    }
+}
+/** C2: the entry's requests, errors, slow requests and sign-ins per bucket and color, or null when unavailable. */
+export async function readReleaseSeries(host, entry, query) {
+    return host.readSeries ? host.readSeries(entry, query) : null;
+}

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, StageCopyState, WindowState } from './types.js';
+import type { Color, ReleaseAction, ReleaseEvent, 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
@@ -26,6 +26,19 @@ export interface ReleaseStore {
     }[]>;
     /** 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. */
+    appendEvents(input: {
+        orgId: string;
+        entryKey: string;
+        events: readonly ReleaseEvent[];
+    }): Promise<void>;
+    /** The history of one entry, newest first. `since` is inclusive. Rows that no longer parse are skipped. */
+    readEvents(input: {
+        orgId: string;
+        entryKey: string;
+        since?: string;
+        limit: number;
+    }): Promise<ReleaseEvent[]>;
 }
 /** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
 export declare function releaseKeys(entry: string): {
@@ -48,9 +61,46 @@ export declare function releaseKeys(entry: string): {
     stageCopyHandled: string;
     /** The id of a request whose copy failed once; a second failure consumes it. */
     stageCopyRetry: string;
+    /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
+    refused: 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"];
+/** 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>;
+    actor: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    release: z.ZodOptional<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>>;
+    signal: z.ZodOptional<z.ZodObject<{
+        requests: z.ZodNumber;
+        errors: z.ZodNumber;
+        baselineRate: z.ZodNullable<z.ZodNumber>;
+        verdict: z.ZodEnum<{
+            inconclusive: "inconclusive";
+            pass: "pass";
+            fail: "fail";
+            hard_fail: "hard_fail";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const releaseEventKind: z.ZodEnum<{
+    step: "step";
+    open: "open";
+    check: "check";
+    passed: "passed";
+    hard_fail: "hard_fail";
+    promote: "promote";
+    rollback: "rollback";
+    pause: "pause";
+    resume: "resume";
+    step_now: "step_now";
+    approve: "approve";
+}>;
 /** The window JSON is the C2 state plus the active release's `release` field. */
 export declare function parseWindow(value: string | undefined): {
     window: WindowState;
@@ -60,6 +110,13 @@ export declare function formatWindow(window: WindowState, release: Recorded['rel
 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;
+/**
+ * The value of `bg.<id>.refused`: the run time and its refused lines, then its blocked lines. Capped at 20 lines
+ * of 300 characters so a bad run cannot grow the row. Callers write it only when `lines` is not empty.
+ */
+export declare function formatRefusals(at: string, lines: readonly string[]): string;
+/** Reads `bg.<id>.refused`; a damaged value reads as absent. */
+export declare function parseRefusals(value: string | undefined): ReleaseState['refused'];
 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: {
@@ -77,3 +134,12 @@ export declare function requestReleaseAction(store: ReleaseStore, input: {
     actor: string;
 }): Promise<void>;
 export { actionSchema as releaseActionSchema };
+export declare const RELEASE_HISTORY_DEFAULT_LIMIT = 200;
+export declare const RELEASE_HISTORY_MAX_LIMIT = 1000;
+/** C1: the history of one entry (a release's steps, checks, actions and outcome), newest first. */
+export declare function readReleaseHistory(store: Pick<ReleaseStore, 'readEvents'>, q: {
+    orgId: string;
+    entryKey: string;
+    since?: string;
+    limit?: number;
+}): Promise<ReleaseEvent[]>;