@wtfalch/foundry 0.41.2 → 0.43.0

package/dist/release/decide.js

@@ -0,0 +1,242 @@
+import { otherColor, } from './types.js';
+/** ADR 0001 rule 5: the default steps and the least time on each. */
+export const DEFAULT_STEPS = [5, 10, 25, 50, 100];
+export const DEFAULT_STEP_HOLD_MINUTES = 60;
+/** Rule 7: errors this share of requests, with at least HARD_FAIL_MIN_REQUESTS, roll back at any level. */
+export const HARD_FAIL_ERROR_RATE = 0.9;
+export const HARD_FAIL_MIN_REQUESTS = 2;
+/** Rule 8: a relative fail needs this many requests and this many failed checks in a row. */
+export const RELATIVE_MIN_REQUESTS = 20;
+export const RELATIVE_FAILED_CHECKS = 3;
+/** A relative check counts only this long after the last counted one, so runs close together (applies also run releases) are one check. */
+export const CHECK_INTERVAL_MINUTES = 10;
+/** The new color matches the baseline while its error rate is at most baseline plus this (absolute). */
+export const ERROR_RATE_MARGIN = 0.02;
+/** Rules 12 and 13: the window at 100% closes after this long, and at most this long. */
+export const WINDOW_MIN_HOURS = 24;
+export const WINDOW_CAP_DAYS = 7;
+/** The new color must be running and answer on its own address within this time of the deploy. */
+export const DEPLOY_TIMEOUT_MINUTES = 30;
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+export function normalizeSteps(steps) {
+    const wanted = steps && steps.length > 0 ? steps : DEFAULT_STEPS;
+    const valid = [...new Set(wanted.filter((n) => Number.isInteger(n) && n >= 1 && n <= 100))].sort((a, b) => a - b);
+    if (valid.length === 0)
+        return [...DEFAULT_STEPS];
+    if (valid[valid.length - 1] !== 100)
+        valid.push(100);
+    return valid;
+}
+function weightsFor(to, percent) {
+    return { [to]: percent, [otherColor(to)]: 100 - percent };
+}
+function rollback(r, now, reason) {
+    const rel = r.release;
+    if (!rel)
+        return r;
+    return {
+        ...r,
+        live: rel.from,
+        weights: weightsFor(rel.from, 100),
+        window: { kind: 'rolled_back', at: now.toISOString(), reason },
+        release: null,
+        held: r.held.includes(rel.digest) ? r.held : [...r.held, rel.digest],
+    };
+}
+function rate(c) {
+    return c.requests > 0 ? c.errors / c.requests : 0;
+}
+function dailyRate(h) {
+    return h.daily.requestsPerDay > 0 ? h.daily.errorsPerDay / h.daily.requestsPerDay : 0;
+}
+/** 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 === 'inconclusive' && w.percent === 0)
+            return null;
+        return { from: w.since, to: now.toISOString() };
+    }
+    return null;
+}
+function applyActions(r, actions, now, out) {
+    let cur = r;
+    let promoted = false;
+    let ended = false;
+    for (const a of actions) {
+        if (a.kind === 'clear_held') {
+            cur = { ...cur, held: cur.held.filter((d) => d !== a.digest) };
+        }
+        else if (a.kind === 'promote') {
+            const idle = !cur.release;
+            const digest = cur.stageDigest;
+            if (!idle)
+                out.refused.push('promote refused: a release is running');
+            else if (!digest)
+                out.refused.push('promote refused: stage has no digest');
+            else if (cur.held.includes(digest))
+                out.refused.push('promote refused: digest is held');
+            else if (digest === cur.digests[cur.live])
+                out.refused.push('promote refused: digest is already live');
+            else {
+                const to = otherColor(cur.live);
+                cur = {
+                    ...cur,
+                    digests: { ...cur.digests, [to]: digest },
+                    window: { kind: 'inconclusive', percent: 0, since: now.toISOString() },
+                    release: { from: cur.live, to, digest, fails: 0 },
+                };
+                out.effects.push({ kind: 'deploy', color: to, digest });
+                promoted = true;
+            }
+        }
+        else if (a.kind === 'rollback') {
+            if (!cur.release)
+                out.refused.push('rollback refused: no release is running');
+            else {
+                cur = rollback(cur, now, 'operator');
+                ended = true;
+            }
+        }
+        else if (a.kind === 'decide_at_cap') {
+            if (cur.window.kind !== 'cap' || !cur.release)
+                out.refused.push('decision refused: no release is at the cap');
+            else if (a.decision === 'rollback') {
+                cur = rollback(cur, now, 'operator at cap');
+                ended = true;
+            }
+            else {
+                out.effects.push({ kind: 'stop', color: cur.release.from });
+                cur = { ...cur, window: { kind: 'passed', at: now.toISOString() }, release: null };
+                ended = true;
+            }
+        }
+    }
+    return { recorded: cur, promoted, ended };
+}
+/**
+ * The whole release decision for one run: from the recorded state, the
+ * actions requested, one observation and the time, the next recorded state.
+ * Pure: it reads nothing and writes nothing (ADR 0001 rules 5, 7-13, 16).
+ */
+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 applied = applyActions(input.recorded, input.actions, now, out);
+    let r = applied.recorded;
+    let signal = null;
+    const blocked = [];
+    const rel = r.release;
+    if (!applied.promoted && !applied.ended && rel) {
+        const since = Date.parse('since' in r.window ? r.window.since : '');
+        const elapsed = now.getTime() - since;
+        const hard = observation.status === 'crash_loop'
+            ? 'hard fail: crash loop'
+            : observation.address === 'failed'
+                ? 'hard fail: address check failed'
+                : null;
+        if (r.window.kind === 'inconclusive' && r.window.percent === 0) {
+            if (hard)
+                r = rollback(r, now, hard);
+            else if (observation.status === 'running' && observation.address === 'ok') {
+                const first = steps[0];
+                r = stepTo(r, rel, first, now);
+            }
+            else if (elapsed >= DEPLOY_TIMEOUT_MINUTES * MINUTE)
+                r = rollback(r, now, 'deploy timeout');
+        }
+        else {
+            const health = observation.health;
+            const newC = health?.colors[rel.to] ?? { requests: 0, errors: 0 };
+            const atWindow = r.window.kind === 'window' || r.window.kind === 'cap';
+            let baseline = null;
+            if (health) {
+                const old = health.colors[rel.from];
+                baseline = !atWindow && old.requests > 0 ? rate(old) : dailyRate(health);
+            }
+            const hardRate = newC.requests >= HARD_FAIL_MIN_REQUESTS && rate(newC) >= HARD_FAIL_ERROR_RATE;
+            let verdict;
+            if (hard || hardRate)
+                verdict = 'hard_fail';
+            else if (!health || baseline === null || newC.requests < RELATIVE_MIN_REQUESTS)
+                verdict = 'inconclusive';
+            else
+                verdict = rate(newC) > baseline + ERROR_RATE_MARGIN ? 'fail' : 'pass';
+            signal = { requests: newC.requests, errors: newC.errors, baselineRate: baseline, verdict };
+            if (verdict === 'hard_fail') {
+                r = rollback(r, now, hard ?? 'hard fail: error rate');
+            }
+            else {
+                const spaced = !rel.checkedAt ||
+                    now.getTime() - Date.parse(rel.checkedAt) >= CHECK_INTERVAL_MINUTES * MINUTE;
+                const counted = spaced && verdict !== 'inconclusive';
+                const fails = !counted ? rel.fails : verdict === 'fail' ? rel.fails + 1 : 0;
+                if (fails >= RELATIVE_FAILED_CHECKS) {
+                    r = rollback(r, now, 'relative fail: failed checks in a row');
+                }
+                else {
+                    r = {
+                        ...r,
+                        release: { ...rel, fails, ...(counted ? { checkedAt: now.toISOString() } : {}) },
+                    };
+                    if (!atWindow) {
+                        const pct = r.window.percent;
+                        const holdDone = elapsed >= holdMs;
+                        if (holdDone && verdict !== 'fail') {
+                            const next = steps.find((s) => s > pct);
+                            r = stepTo(r, rel, next, now);
+                        }
+                        else {
+                            const kind = verdict === 'inconclusive' ? 'inconclusive' : 'step';
+                            r = {
+                                ...r,
+                                window: { kind, percent: pct, since: r.window.since },
+                            };
+                        }
+                    }
+                    else {
+                        const required = Math.max(1, Math.ceil(health?.daily.requestsPerDay ?? 0));
+                        const closable = health !== null &&
+                            baseline !== null &&
+                            elapsed >= WINDOW_MIN_HOURS * HOUR &&
+                            newC.requests >= required &&
+                            rate(newC) <= baseline + ERROR_RATE_MARGIN;
+                        if (closable) {
+                            out.effects.push({ kind: 'stop', color: rel.from });
+                            r = { ...r, window: { kind: 'passed', at: now.toISOString() }, release: null };
+                        }
+                        else if (elapsed >= WINDOW_CAP_DAYS * DAY) {
+                            r = { ...r, window: { kind: 'cap', since: new Date(since).toISOString() } };
+                        }
+                    }
+                }
+            }
+        }
+    }
+    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 };
+}
+function stepTo(r, rel, percent, now) {
+    const at = now.toISOString();
+    const fresh = { from: rel.from, to: rel.to, digest: rel.digest, fails: 0 };
+    if (percent >= 100) {
+        return {
+            ...r,
+            live: rel.to,
+            weights: weightsFor(rel.to, 100),
+            window: { kind: 'window', since: at },
+            release: fresh,
+        };
+    }
+    return {
+        ...r,
+        weights: weightsFor(rel.to, percent),
+        window: { kind: 'step', percent, since: at },
+        release: fresh,
+    };
+}

package/dist/release/health.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { HealthRead } from './decide.js';
+/** The reporting health read has this long to answer. */
+export declare const HEALTH_READ_TIMEOUT_MS = 10000;
+/** The color's own address check has this long to answer. */
+export declare const ADDRESS_CHECK_TIMEOUT_MS = 10000;
+/** C1's 200 body. */
+export declare const healthBody: z.ZodObject<{
+    colors: z.ZodObject<{
+        blue: z.ZodObject<{
+            requests: z.ZodNumber;
+            errors: z.ZodNumber;
+        }, z.core.$strip>;
+        green: z.ZodObject<{
+            requests: z.ZodNumber;
+            errors: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    daily: z.ZodObject<{
+        days: z.ZodNumber;
+        requestsPerDay: z.ZodNumber;
+        errorsPerDay: z.ZodNumber;
+    }, z.core.$strip>;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `GET <address>/api/reporting/release-health?from&to` with the bearer token.
+ * Returns null for any failure (network, timeout, status, shape): the caller
+ * counts that as inconclusive, never as a pass. Nothing about the response or
+ * the token reaches a log or an error.
+ */
+export declare function readReleaseHealth(input: {
+    address: string;
+    token: string;
+    from: string;
+    to: string;
+    /** Extra request headers, e.g. the load balancer's color pin. */
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}): Promise<HealthRead | null>;
+/** An HTTP check of the color's health path on its own address. */
+export declare function checkColorAddress(input: {
+    address: string;
+    healthPath: string | null;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}): Promise<'ok' | 'failed'>;

package/dist/release/health.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/** The reporting health read has this long to answer. */
+export const HEALTH_READ_TIMEOUT_MS = 10_000;
+/** The color's own address check has this long to answer. */
+export const ADDRESS_CHECK_TIMEOUT_MS = 10_000;
+const counts = z.object({
+    requests: z.number().int().nonnegative(),
+    errors: z.number().int().nonnegative(),
+});
+/** C1's 200 body. */
+export const healthBody = z.object({
+    colors: z.object({ blue: counts, green: counts }),
+    daily: z.object({
+        days: z.number().nonnegative(),
+        requestsPerDay: z.number().nonnegative(),
+        errorsPerDay: z.number().nonnegative(),
+    }),
+    from: z.string(),
+    to: z.string(),
+});
+/**
+ * `GET <address>/api/reporting/release-health?from&to` with the bearer token.
+ * Returns null for any failure (network, timeout, status, shape): the caller
+ * counts that as inconclusive, never as a pass. Nothing about the response or
+ * the token reaches a log or an error.
+ */
+export async function readReleaseHealth(input) {
+    try {
+        const url = new URL('/api/reporting/release-health', input.address);
+        url.searchParams.set('from', input.from);
+        url.searchParams.set('to', input.to);
+        const res = await (input.fetchImpl ?? fetch)(url, {
+            headers: { ...input.headers, authorization: `Bearer ${input.token}` },
+            signal: AbortSignal.timeout(HEALTH_READ_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const parsed = healthBody.safeParse(await res.json());
+        if (!parsed.success)
+            return null;
+        return { colors: parsed.data.colors, daily: parsed.data.daily };
+    }
+    catch {
+        // Network error, timeout or invalid JSON: all the same to the caller.
+        return null;
+    }
+}
+/** An HTTP check of the color's health path on its own address. */
+export async function checkColorAddress(input) {
+    try {
+        const res = await (input.fetchImpl ?? fetch)(new URL(input.healthPath ?? '/', input.address), {
+            ...(input.headers ? { headers: input.headers } : {}),
+            signal: AbortSignal.timeout(ADDRESS_CHECK_TIMEOUT_MS),
+        });
+        return res.ok ? 'ok' : 'failed';
+    }
+    catch {
+        // Unreachable counts as a failed check.
+        return 'failed';
+    }
+}

package/dist/release/run.d.ts

@@ -0,0 +1,40 @@
+import { type Decision, type Observation, type ReleaseEffect } from './decide.js';
+import { type ReleaseStore } from './state.js';
+import type { Color } from './types.js';
+/** 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. */
+    readHealth(range: {
+        from: string;
+        to: string;
+    }): Promise<Observation['health']>;
+    /** The Coolify status and the own-address check of a color. */
+    observeColor(color: Color): Promise<Pick<Observation, 'status' | 'address'>>;
+    effect(effect: ReleaseEffect): Promise<void>;
+}
+export interface ReleaseRunResult {
+    /** Scope keys to record (null removes one). The caller persists them with the rest of the run. */
+    writes: Record<string, string | null>;
+    blocked: string[];
+    refused: string[];
+    decision: Decision | null;
+    /** The requests this run acted on. The caller consumes them with `store.consumeRequests` after it persists `writes`. */
+    requestIds: number[];
+}
+/**
+ * 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
+ * crash before the caller persists and consumes, leaves the requests open and
+ * the recorded keys as they were: the next run decides again from them.
+ */
+export declare function runRelease(input: {
+    store: ReleaseStore;
+    orgId: string;
+    entryKey: string;
+    entry: {
+        steps?: number[];
+        stepHoldMinutes?: number;
+    };
+    now: Date;
+    deps: ReleaseDeps;
+}): Promise<ReleaseRunResult>;

package/dist/release/run.js

@@ -0,0 +1,56 @@
+import { decide, healthRange, } from './decide.js';
+import { formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
+/**
+ * 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
+ * crash before the caller persists and consumes, leaves the requests open and
+ * the recorded keys as they were: the next run decides again from them.
+ */
+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 });
+    const actions = open.map((r) => r.action);
+    const range = healthRange(recorded, now);
+    const target = recorded.release?.to ?? null;
+    const health = range ? await deps.readHealth(range) : null;
+    const seen = target
+        ? await deps.observeColor(target)
+        : { status: 'other', address: 'unchecked' };
+    const decision = decide({
+        recorded,
+        actions,
+        steps: input.entry.steps,
+        stepHoldMinutes: input.entry.stepHoldMinutes,
+        now,
+        observation: { health, ...seen },
+    });
+    for (const effect of decision.effects)
+        await deps.effect(effect);
+    const k = releaseKeys(entryKey);
+    const next = decision.recorded;
+    const writes = {
+        [k.live]: next.live,
+        [k.weights]: formatWeights(next.weights),
+        [k.digest('blue')]: next.digests.blue,
+        [k.digest('green')]: next.digests.green,
+        [k.window]: formatWindow(next.window, next.release),
+        [k.signal]: decision.signal ? JSON.stringify(decision.signal) : null,
+    };
+    for (const d of recorded.held)
+        if (!next.held.includes(d))
+            writes[k.held(d)] = null;
+    for (const d of next.held)
+        if (!recorded.held.includes(d))
+            writes[k.held(d)] = now.toISOString();
+    return {
+        writes,
+        blocked: decision.blocked,
+        refused: decision.refused,
+        decision,
+        requestIds: open.map((r) => r.id),
+    };
+}

package/dist/release/state.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { Recorded } from './decide.js';
+import type { Color, ReleaseAction, ReleaseSignal, ReleaseState, 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
+ * orgId `platform`). Requests live in their own table so a click never races
+ * the runner's snapshot write.
+ */
+export interface ReleaseStore {
+    getScopeIds(orgId: string): Promise<Record<string, string>>;
+    addRequest(input: {
+        orgId: string;
+        entryKey: string;
+        action: ReleaseAction;
+        actor: string;
+    }): Promise<void>;
+    /** The open requests, oldest first. Reading consumes nothing: a run that fails leaves them open. */
+    openRequests(input: {
+        orgId: string;
+        entryKey: string;
+    }): Promise<{
+        id: number;
+        action: ReleaseAction;
+        actor: string;
+    }[]>;
+    /** Marks requests consumed. The runner calls it only after its decision is persisted. */
+    consumeRequests(ids: readonly number[]): Promise<void>;
+}
+/** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
+export declare function releaseKeys(entry: string): {
+    live: string;
+    digest: (c: Color) => string;
+    weights: string;
+    stage: string;
+    window: string;
+    signal: string;
+    heldPrefix: string;
+    held: (digest: string) => string;
+};
+export declare function formatWeights(w: Record<Color, number>): string;
+export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
+/** The window JSON is the C2 state plus the active release's `release` field. */
+export declare function parseWindow(value: string | undefined): {
+    window: WindowState;
+    release: Recorded['release'];
+};
+export declare function formatWindow(window: WindowState, release: Recorded['release']): string;
+export declare function recordedFrom(ids: Record<string, string>, entryKey: string): Recorded | null;
+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: {
+    orgId: string;
+    entryKey: string;
+}): Promise<ReleaseState | null>;
+declare const actionSchema: z.ZodType<ReleaseAction>;
+/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+export declare function requestReleaseAction(store: ReleaseStore, input: {
+    orgId: string;
+    entryKey: string;
+    action: ReleaseAction;
+    actor: string;
+}): Promise<void>;
+export { actionSchema as releaseActionSchema };

package/dist/release/state.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+/** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
+export function releaseKeys(entry) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(entry))
+        throw new Error('invalid release entry key');
+    const p = `bg.${entry}`;
+    return {
+        live: `${p}.live`,
+        digest: (c) => `${p}.digest.${c}`,
+        weights: `${p}.weights`,
+        stage: `${p}.stage`,
+        window: `${p}.window`,
+        signal: `${p}.signal`,
+        heldPrefix: `${p}.held.`,
+        held: (digest) => `${p}.held.${digest}`,
+    };
+}
+export function formatWeights(w) {
+    return `blue:${w.blue},green:${w.green}`;
+}
+export function parseWeights(value) {
+    const m = /^blue:(\d{1,3}),green:(\d{1,3})$/.exec(value ?? '');
+    if (!m)
+        return null;
+    return { blue: Number(m[1]), green: Number(m[2]) };
+}
+const color = z.enum(['blue', 'green']);
+const storedWindow = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('idle') }),
+    z.object({ kind: z.literal('step'), percent: z.number(), since: z.string() }),
+    z.object({ kind: z.literal('inconclusive'), percent: z.number(), since: z.string() }),
+    z.object({ kind: z.literal('window'), since: z.string() }),
+    z.object({ kind: z.literal('passed'), at: z.string() }),
+    z.object({ kind: z.literal('rolled_back'), at: z.string(), reason: z.string() }),
+    z.object({ kind: z.literal('cap'), since: z.string() }),
+]);
+const releaseField = z
+    .object({
+    from: color,
+    to: color,
+    digest: z.string(),
+    fails: z.number().int().nonnegative(),
+    checkedAt: z.string().optional(),
+})
+    .nullable()
+    .optional();
+const signalSchema = z.object({
+    requests: z.number(),
+    errors: z.number(),
+    baselineRate: z.number().nullable(),
+    verdict: z.enum(['pass', 'fail', 'hard_fail', 'inconclusive']),
+});
+function parseJson(value) {
+    if (!value)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // A damaged value reads as absent; the runner rewrites it.
+        return undefined;
+    }
+}
+/** The window JSON is the C2 state plus the active release's `release` field. */
+export function parseWindow(value) {
+    const state = storedWindow.safeParse(parseJson(value));
+    if (!state.success)
+        return { window: { kind: 'idle' }, release: null };
+    const rel = releaseField.safeParse(parseJson(value).release);
+    return { window: state.data, release: rel.success ? (rel.data ?? null) : null };
+}
+export function formatWindow(window, release) {
+    return JSON.stringify(release ? { ...window, release } : window);
+}
+export function recordedFrom(ids, entryKey) {
+    const k = releaseKeys(entryKey);
+    const live = color.safeParse(ids[k.live]);
+    if (!live.success)
+        return null;
+    const { window, release } = parseWindow(ids[k.window]);
+    return {
+        live: live.data,
+        digests: { blue: ids[k.digest('blue')] ?? null, green: ids[k.digest('green')] ?? null },
+        stageDigest: ids[k.stage] ?? null,
+        weights: parseWeights(ids[k.weights]) ?? { ...{ blue: 0, green: 0 }, [live.data]: 100 },
+        window,
+        release,
+        held: Object.keys(ids)
+            .filter((key) => key.startsWith(k.heldPrefix))
+            .map((key) => key.slice(k.heldPrefix.length))
+            .sort(),
+    };
+}
+export function readSignal(ids, entryKey) {
+    const parsed = signalSchema.safeParse(parseJson(ids[releaseKeys(entryKey).signal]));
+    return parsed.success ? parsed.data : null;
+}
+/** C2: the release state of one hosting entry, or null before blue/green recorded anything. */
+export async function readReleaseState(store, input) {
+    const ids = await store.getScopeIds(input.orgId);
+    const r = recordedFrom(ids, input.entryKey);
+    if (!r)
+        return null;
+    return {
+        entryKey: input.entryKey,
+        live: r.live,
+        weights: r.weights,
+        digests: r.digests,
+        stageDigest: r.stageDigest,
+        window: r.window,
+        signal: readSignal(ids, input.entryKey),
+        held: r.held,
+    };
+}
+const actionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('promote') }),
+    z.object({ kind: z.literal('rollback') }),
+    z.object({ kind: z.literal('clear_held'), digest: z.string().min(1) }),
+    z.object({ kind: z.literal('decide_at_cap'), decision: z.enum(['pass', 'rollback']) }),
+]);
+/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+export async function requestReleaseAction(store, input) {
+    releaseKeys(input.entryKey);
+    await store.addRequest({ ...input, action: actionSchema.parse(input.action) });
+}
+export { actionSchema as releaseActionSchema };