Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
44.9 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Stable channel promotion (.github/workflows/promote-stable.yml).
 *
 *   PROMOTE_VERSION=<v> PROMOTE_SOAK_RUN_URL=<url> [PROMOTE_SCOREBOARD_URL=<url>]
 *   [PROMOTE_ROLLBACK=true PROMOTE_REASON=<why>] bun run scripts/promote-stable.ts
 *
 * Promotes an already published release (the immutable `v<VERSION>` tag that
 * release.yml minted) to the stable channel, only after the production-shaped
 * soak passed on its exact git tree:
 *
 * 1. the dispatching actor has the admin or maintain role, or the run is the
 *    scheduled stable-daily.yml check on the default branch (scheduleAuthorized:
 *    only code already merged to master runs on a schedule, and it promotes by
 *    rule, docs/RELEASING.md#daily-stable-check);
 * 2. `refs/tags/v<VERSION>` exists, its VERSION file says <VERSION>, and its
 *    GitHub release is published (not a draft); its commit and tree are the
 *    release;
 * 3. the soak run URL names a run of this repository whose workflow file is
 *    the STABLE_SOAK_WORKFLOW repository variable, completed with success;
 * 4. the run's head commit has the release tree (the same bytes, not merely
 *    the same version);
 * 4b. a forward promotion by the schedule names a green upgrade matrix run on
 *    the release's exact tag and tree (matrix_run_url; scripts/stable-matrix.ts
 *    judgeMatrixRun), and any matrix run named is checked the same way, so a
 *    red or foreign run is refused; a maintainer may promote without one, and
 *    the record then says matrix_run: null with the maintainer as promoted_by;
 * 5. the version is strictly newer than the current stable, unless this is a
 *    rollback with a reason; promoting the current stable again moves no
 *    tag and only writes its evidence record when the published one does
 *    not name it (recordCurrentStable, the GBRA-346 backfill), else no-ops;
 * 6. the annotated record tag `stable-v<VERSION>` is created (once per
 *    version, never moved) and the annotated `stable` tag is moved to the
 *    release commit, both carrying renderTagMessage();
 * 7. the evidence record (renderRecord(): version, commit, tree, soak run,
 *    and the `known_bad` list, carried forward from the previous record plus
 *    this run's `withdraw` versions, and the `not_promotable` list stable-daily
 *    skips, carried forward the same way) is committed as `stable.json` on the
 *    `stable-record` branch, parented on the previous record commit. One
 *    atomic push moves all three, `stable` and `stable-record` leased on
 *    the values read, so a failed push leaves the remote unchanged and a
 *    re-run starts clean.
 * 8. the release's GitHub release is marked "Latest" (pre-release cleared):
 *    release.yml publishes every batch release as a pre-release, so the
 *    stable channel is the one release GitHub calls Latest. A forward
 *    promotion replaces its notes with a short summary of the behavior
 *    changes since the previous stable (upgradeSummary()), then every
 *    CHANGELOG entry since it (rolledUpNotes()); a rollback keeps the notes. If this
 *    last step fails, stable has already moved: the refusal names
 *    `bun scripts/release-channel.ts backfill --apply`, which sets it.
 *
 * Clients read the record at
 * https://raw.githubusercontent.com/garrytan/gbrain/stable-record/stable.json
 * (src/core/stable-channel.ts: no API call, no git) and an explicit upgrade
 * checks it against `refs/tags/stable^{}` and `v<VERSION>`. Records carry the
 * soak run and, from the matrix gate on, matrix_run; clients require matrix_run
 * only once MATRIX_REQUIRED_FROM in src/core/self-upgrade.ts is set.
 * Side effects (gh, git, clock, log, step summary) come in through
 * PromoteDeps, so the decisions are tested without network or a real remote
 * (test/scripts/promote-stable.test.ts). Every refusal exits 1 with one
 * sentence saying what to do. Docs: docs/RELEASING.md#stable-channel-promotion
 */
import { spawnSync } from 'node:child_process';
import { appendFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { upgradeSummary } from '../src/core/upgrade-summary.ts';
import { judgeMatrixRun, MATRIX_RECEIPT_ARTIFACT, type BreakIssue, type MatrixReceipt, type MatrixRunRow } from './stable-matrix.ts';

export const DOCS = 'docs/RELEASING.md#stable-channel-promotion';
export const STABLE_REF = 'refs/tags/stable';
export const RECORD_BRANCH_REF = 'refs/heads/stable-record';
export const RECORD_REMOTE_REF = 'refs/remotes/origin/stable-record';
export const RECORD_FILE = 'stable.json';
const VERSION_RE = /^\d+\.\d+\.\d+(\.\d+)?$/;
const SHA_RE = /^[0-9a-f]{40}$/;
const PROMOTER_ROLES = new Set(['admin', 'maintain']);
const ROLLBACK_NEEDS_REASON = 'A rollback needs a reason: re-run with the reason input saying why stable moves back.';

export class Refusal extends Error {}

export interface PromoteInputs {
  version: string;
  soakRunUrl: string;
  scoreboardUrl: string;
  rollback: boolean;
  reason: string;
  /** Versions to add to the record's known_bad list (withdrawn releases clients move off). */
  withdraw?: string[];
  /** Releases to add to the record's not_promotable list: stable-daily never soaks or promotes them; clients never read it. */
  notPromotable?: NotPromotable[];
  /** Releases to take off the record's not_promotable list (one listed by mistake, say). */
  notPromotableRemove?: string[];
  /** The upgrade matrix run on this release (required for a scheduled forward promotion). */
  matrixRunUrl?: string;
  /** The open break issue a security or data-loss promotion passes (stable-daily only); the run may fail only on its named from-versions. */
  matrixExcuse?: BreakIssue | null;
}

/** A release outside evidence shows is bad although it may soak clean, with the release that fixes it. */
export interface NotPromotable { version: string; reason: string; fixed_in: string }

/** The largest stable.json clients accept (src/core/stable-channel.ts RECORD_MAX_BYTES; a test pins the two). */
export const STABLE_RECORD_MAX_BYTES = 64 * 1024;
const NOT_PROMOTABLE_REASON_MAX = 500;

export interface GitResult { code: number; stdout: string; stderr: string }

export interface PromoteDeps {
  repo: string;
  actor: string;
  /** True only for the scheduled stable-daily.yml run (scheduleAuthorized); it replaces the role check. */
  scheduled?: boolean;
  soakWorkflow: string;
  ghApi(path: string): Promise<unknown>;
  /** A write to the GitHub API (only the release edit that marks stable Latest). */
  ghApiWrite(method: 'PATCH', path: string, body: Record<string, unknown>): Promise<unknown>;
  git(args: string[], input?: string): Promise<GitResult>;
  /** The upgrade-matrix-receipt artifact of a matrix run, or null when it cannot be read. */
  matrixReceipt?(runId: number): Promise<MatrixReceipt | null>;
  now(): Date;
  log(line: string): void;
  summary(markdown: string): void;
}

export interface SoakRun {
  status?: string | null;
  conclusion?: string | null;
  path?: string | null;
  head_sha?: string | null;
}

export interface TagFields {
  version: string;
  commit: string;
  tree: string;
  soakRun: string;
  scoreboard: string;
  /** The upgrade matrix run; absent or empty when a maintainer promoted without one. */
  matrixRun?: string;
  promotedBy: string;
  promotedAt: string;
  previous: string | null;
  rollback: boolean;
  reason: string;
}

export interface Promotion extends TagFields { recordCreated: boolean; knownBad: string[] }

/** The evidence record clients read (src/core/stable-channel.ts parseStableRecord); generation 1: soak evidence. */
export function renderRecord(f: TagFields, knownBad: readonly string[], notPromotable: readonly NotPromotable[] = []): string {
  return JSON.stringify({
    schema: 1,
    channel: 'stable',
    version: f.version,
    commit: f.commit,
    tree: f.tree,
    soak_run: f.soakRun,
    scoreboard: f.scoreboard,
    matrix_run: f.matrixRun || null,
    promoted_by: f.promotedBy,
    promoted_at: f.promotedAt,
    previous: f.previous,
    rollback: f.rollback,
    reason: f.reason.trim().replace(/\s+/g, ' '),
    known_bad: [...knownBad],
    not_promotable: notPromotable.map(e => ({ version: e.version, reason: e.reason, fixed_in: e.fixed_in })),
  }, null, 2) + '\n';
}

/** The previous record's known_bad plus this run's withdrawals, deduplicated and sorted; refuses withdrawing the promoted version. */
export function mergeKnownBad(previous: readonly string[], withdraw: readonly string[], version: string): string[] {
  for (const v of withdraw) {
    if (!VERSION_RE.test(v)) throw new Refusal(`withdraw entry "${v}" is not a release version; pass versions like 0.60.361.0, comma-separated.`);
  }
  const all = [...new Set([...previous, ...withdraw])].sort(compareVersions);
  if (all.includes(version)) throw new Refusal(`v${version} is on the stable record's known_bad list (withdrawn); promote a different release.`);
  return all;
}

/** The previous record's not_promotable minus `remove`, plus this run's entries (a new entry replaces one for its version), sorted; refuses one naming the promoted version. */
export function mergeNotPromotable(previous: readonly NotPromotable[], add: readonly NotPromotable[], version: string, remove: readonly string[] = []): NotPromotable[] {
  for (const v of remove) {
    if (add.some(e => e.version === v)) throw new Refusal(`v${v} is both added to and removed from the not_promotable list; pass it in one of not_promotable or not_promotable_remove.`);
    if (!previous.some(e => e.version === v)) throw new Refusal(`v${v} is not on the not_promotable list, so there is nothing to remove; check the version against stable.json on stable-record.`);
  }
  for (const e of add) {
    if (!VERSION_RE.test(e.version)) throw new Refusal(`not_promotable entry "${e.version}" is not a release version; pass versions like 0.60.649.0, comma-separated.`);
    if (!VERSION_RE.test(e.fixed_in) || compareVersions(e.fixed_in, e.version) <= 0) throw new Refusal(`not_promotable v${e.version} needs fixed_in: the newer release that carries the fix, like 0.60.652.0 (got "${e.fixed_in}").`);
    if (!e.reason.trim()) throw new Refusal(`not_promotable v${e.version} needs a reason: say what shows the release is bad.`);
    const length = e.reason.trim().replace(/\s+/g, ' ').length;
    if (length > NOT_PROMOTABLE_REASON_MAX) throw new Refusal(`not_promotable v${e.version}'s reason is ${length} characters; keep it to ${NOT_PROMOTABLE_REASON_MAX} (link the evidence instead of pasting it).`);
  }
  const byVersion = new Map(previous.filter(e => !remove.includes(e.version)).map(e => [e.version, e]));
  for (const e of add) byVersion.set(e.version, { version: e.version, reason: e.reason.trim().replace(/\s+/g, ' '), fixed_in: e.fixed_in });
  const all = [...byVersion.values()].sort((a, b) => compareVersions(a.version, b.version));
  const own = all.find(e => e.version === version);
  if (own) throw new Refusal(`v${version} is on the stable record's not_promotable list (${own.reason}; fixed in v${own.fixed_in}); promote a different release.`);
  return all;
}

export const DAILY_WORKFLOW = '.github/workflows/stable-daily.yml';

/**
 * The scheduled daily check promotes without a maintainer: a schedule event only ever runs the workflow file as
 * merged on the default branch, so the rule it applies is reviewed code. Any other event (a dispatch of either
 * workflow) keeps the role check.
 */
export function scheduleAuthorized(env: NodeJS.ProcessEnv, repo: string): boolean {
  return env.GITHUB_EVENT_NAME === 'schedule' && (env.GITHUB_WORKFLOW_REF ?? '').startsWith(`${repo}/${DAILY_WORKFLOW}@refs/heads/`);
}

/** The branch release.yml mints release tags from; a scheduled promotion only takes a release whose commit is on it. */
export const RELEASE_BRANCH_REF = 'refs/remotes/origin/master';

export async function onReleaseBranch(deps: PromoteDeps, commit: string): Promise<boolean> {
  return (await deps.git(['merge-base', '--is-ancestor', commit, RELEASE_BRANCH_REF])).code === 0;
}

/** The scheduled daily check promotes by rule; everyone else needs the admin or maintain role. */
export async function authorize(deps: PromoteDeps): Promise<void> {
  if (deps.scheduled) {
    deps.log(`[promote-stable] scheduled daily check (${DAILY_WORKFLOW} on the default branch): promoting by rule.`);
    return;
  }
  // `permission` is the legacy base role (maintain reads as write); `role_name` names maintain.
  const perm = await deps.ghApi(`repos/${deps.repo}/collaborators/${encodeURIComponent(deps.actor)}/permission`) as { permission?: string; role_name?: string };
  const role = perm.role_name || perm.permission || 'none';
  if (perm.permission !== 'admin' && !PROMOTER_ROLES.has(role)) throw new Refusal(`${deps.actor} has the ${role} role on ${deps.repo}; only admins and maintainers promote to stable, so ask one to dispatch this workflow.`);
  deps.log(`[promote-stable] ${deps.actor} has the ${role} role: allowed to promote.`);
}

export function compareVersions(a: string, b: string): number {
  const pa = a.split('.').map(Number);
  const pb = b.split('.').map(Number);
  for (let i = 0; i < 4; i++) {
    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
    if (d !== 0) return Math.sign(d);
  }
  return 0;
}

export function parseRunUrl(url: string, repo: string, input: 'soak_run_url' | 'matrix_run_url' = 'soak_run_url'): { runId: string; attempt: string | null } {
  const what = input === 'soak_run_url' ? 'soak' : 'upgrade matrix';
  const m = /^https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/actions\/runs\/(\d+)(?:\/attempts\/(\d+))?\/?$/.exec(url.trim());
  if (!m) throw new Refusal(`${input} "${url}" is not a GitHub Actions run URL; pass https://github.com/${repo}/actions/runs/<run id> (optionally /attempts/<n>) of the ${what} run.`);
  if (m[1]!.toLowerCase() !== repo.toLowerCase()) throw new Refusal(`${input} names a run of ${m[1]}, not ${repo}; pass the ${what} run from this repository's Actions tab.`);
  return { runId: m[2]!, attempt: m[3] ?? null };
}

export function normaliseWorkflowPath(value: string): string {
  const bare = value.trim().replace(/@.*$/, '').replace(/^\.\//, '');
  return bare.startsWith('.github/workflows/') ? bare : `.github/workflows/${bare}`;
}

export function requireSoakWorkflow(soakWorkflow: string): string {
  if (!soakWorkflow.trim()) throw new Refusal('The soak workflow is not configured: set the repository variable STABLE_SOAK_WORKFLOW to the soak workflow\'s file (Settings → Secrets and variables → Actions → Variables), then re-run this workflow.');
  return normaliseWorkflowPath(soakWorkflow);
}

export function checkSoakRun(run: SoakRun, soakWorkflow: string, url: string): void {
  const expected = requireSoakWorkflow(soakWorkflow);
  const actual = normaliseWorkflowPath(run.path ?? '');
  if (actual !== expected) throw new Refusal(`Soak run ${url} ran ${actual}, not the soak workflow ${expected}; pass a run of ${expected} (or fix the STABLE_SOAK_WORKFLOW repository variable).`);
  if (run.status !== 'completed') throw new Refusal(`Soak run ${url} is ${run.status ?? 'in an unknown state'}, not completed; wait for it to finish, then re-run this workflow.`);
  if (run.conclusion !== 'success') throw new Refusal(`Soak run ${url} concluded ${run.conclusion ?? 'without a conclusion'}, not success; promote only a release whose soak passed.`);
}

export function checkOrder(next: string, current: string | null, rollback: boolean, reason: string): void {
  if (rollback && !reason.trim()) throw new Refusal(ROLLBACK_NEEDS_REASON);
  if (current === null) return;
  const cmp = compareVersions(next, current);
  if (cmp === 0) throw new Refusal(`v${next} is already the stable release, so there is nothing to promote.`);
  if (cmp < 0 && !rollback) throw new Refusal(`v${next} is older than the current stable v${current}; to move stable back, re-run with rollback=true and a reason.`);
}

export function renderTagMessage(f: TagFields): string {
  return [
    `gbrain stable channel: v${f.version}`,
    '',
    `version: ${f.version}`,
    `commit: ${f.commit}`,
    `tree: ${f.tree}`,
    `soak_run: ${f.soakRun}`,
    `scoreboard: ${f.scoreboard}`,
    ...(f.matrixRun ? [`matrix_run: ${f.matrixRun}`] : []),
    `promoted_by: ${f.promotedBy}`,
    `promoted_at: ${f.promotedAt}`,
    `previous: ${f.previous ?? 'none'}`,
    `rollback: ${f.rollback}`,
    `reason: ${f.reason.trim().replace(/\s+/g, ' ') || '-'}`,
    '',
  ].join('\n');
}

/**
 * The fields a promotion wrote into the stable tag's message (renderTagMessage), or null when the message is not one.
 * GBRA-346: promotions made before the evidence record existed left only this message, so it is what stable.json is
 * backfilled from when the current stable is promoted again (recordCurrentStable).
 */
export function parseTagMessage(message: string): TagFields | null {
  if (!message.startsWith('gbrain stable channel: v')) return null;
  const kv = new Map<string, string>();
  for (const line of message.split('\n')) {
    const m = /^([a-z_]+): (.+)$/.exec(line);
    if (m && !kv.has(m[1]!)) kv.set(m[1]!, m[2]!);
  }
  const [version, commit, tree, soakRun, scoreboard, promotedBy, promotedAt, previous, rollback, reason] =
    ['version', 'commit', 'tree', 'soak_run', 'scoreboard', 'promoted_by', 'promoted_at', 'previous', 'rollback', 'reason'].map(k => kv.get(k));
  if (!version || !VERSION_RE.test(version) || !commit || !SHA_RE.test(commit) || !tree || !SHA_RE.test(tree)) return null;
  if (!soakRun || !scoreboard || !promotedBy || !promotedAt || !reason || (rollback !== 'true' && rollback !== 'false')) return null;
  if (!previous || (previous !== 'none' && !VERSION_RE.test(previous))) return null;
  const matrixRun = kv.get('matrix_run');
  return {
    version, commit, tree, soakRun, scoreboard, ...(matrixRun ? { matrixRun } : {}), promotedBy, promotedAt,
    previous: previous === 'none' ? null : previous,
    rollback: rollback === 'true',
    reason: reason === '-' ? '' : reason,
  };
}

export function renderSummary(p: Promotion, notPromotable: readonly NotPromotable[] = []): string {
  const rows: Array<[string, string]> = [
    ['Version', `v${p.version}`],
    ['Commit', `\`${p.commit}\``],
    ['Tree', `\`${p.tree}\``],
    ['Soak run', p.soakRun],
    ['Scoreboard', p.scoreboard],
    ['Upgrade matrix', p.matrixRun || 'none (promoted without one)'],
    ['Previous stable', p.previous ? `v${p.previous}` : 'none'],
    ['Rollback', p.rollback ? `yes: ${p.reason.trim()}` : 'no'],
    ['Known bad', p.knownBad.length ? p.knownBad.map(v => `v${v}`).join(', ') : 'none'],
    ['Not promotable', notPromotable.length ? notPromotable.map(e => `v${e.version} (${e.reason}; fixed in v${e.fixed_in})`).join(', ') : 'none'],
    ['Record tag', p.recordCreated ? `\`stable-v${p.version}\` created` : `\`stable-v${p.version}\` already existed (re-promotion)`],
    ['Promoted by', `${p.promotedBy} at ${p.promotedAt}`],
  ];
  const cell = (v: string) => v.replace(/\s+/g, ' ').replace(/\|/g, '\\|');
  return [`## Stable channel: v${p.version}`, '', '| Field | Value |', '|---|---|', ...rows.map(([k, v]) => `| ${k} | ${cell(v)} |`), ''].join('\n');
}

async function gitOut(deps: PromoteDeps, args: string[], refusal: string, input?: string): Promise<string> {
  const r = await deps.git(args, input);
  if (r.code !== 0) throw new Refusal(`${refusal}${r.stderr.trim() ? ` (git: ${r.stderr.trim().split('\n').at(-1)})` : ''}`);
  return r.stdout.trim();
}

export async function refExists(deps: PromoteDeps, ref: string): Promise<boolean> {
  return (await deps.git(['rev-parse', '--verify', '--quiet', ref])).code === 0;
}

/** The current stable: the highest `v*` tag on the commit `refs/tags/stable` peels to (plus the tag object, for the push lease), or null when stable does not exist. */
export async function currentStable(deps: PromoteDeps): Promise<{ version: string; tagObject: string } | null> {
  if (!(await refExists(deps, STABLE_REF))) return null;
  const tagObject = await gitOut(deps, ['rev-parse', STABLE_REF], `Could not read ${STABLE_REF}; re-run this workflow.`);
  const commit = await gitOut(deps, ['rev-parse', `${STABLE_REF}^{commit}`], `Could not peel ${STABLE_REF} to a commit; repair the tag by hand (${DOCS}).`);
  const versions = (await gitOut(deps, ['tag', '--points-at', commit, '--list', 'v*'], `Could not list the tags on ${commit}; re-run this workflow.`))
    .split('\n').map(t => t.trim().replace(/^v/, '')).filter(v => VERSION_RE.test(v));
  if (versions.length === 0) throw new Refusal(`${STABLE_REF} points at ${commit}, which carries no v<VERSION> release tag; repair the stable tag by hand before promoting (${DOCS}).`);
  return { version: versions.sort(compareVersions).at(-1)!, tagObject };
}

export interface PriorRecord { commit: string; version: string | null; releaseCommit: string | null; knownBad: string[]; notPromotable: NotPromotable[] }

/** The published evidence record (the remote stable-record head), or null before the first record. */
export async function readPriorRecord(deps: PromoteDeps): Promise<PriorRecord | null> {
  await deps.git(['fetch', '--no-tags', 'origin', `+${RECORD_BRANCH_REF}:${RECORD_REMOTE_REF}`]);
  if (!(await refExists(deps, `${RECORD_REMOTE_REF}^{commit}`))) return null;
  const commit = await gitOut(deps, ['rev-parse', `${RECORD_REMOTE_REF}^{commit}`], `Could not resolve ${RECORD_REMOTE_REF}; re-run this workflow.`);
  const shown = await deps.git(['show', `${commit}:${RECORD_FILE}`]);
  let prior: { version?: unknown; commit?: unknown; known_bad?: unknown; not_promotable?: unknown };
  try {
    prior = JSON.parse(shown.stdout);
  } catch {
    throw new Refusal(`The previous stable record (${commit}:${RECORD_FILE}) is not JSON, so its known_bad list cannot be carried forward; repair the stable-record branch by hand (${DOCS}).`);
  }
  const notPromotable = prior.not_promotable ?? [];
  const entry = (e: unknown): e is NotPromotable => {
    const r = e as Partial<NotPromotable> | null;
    return !!r && typeof r.version === 'string' && VERSION_RE.test(r.version) && typeof r.fixed_in === 'string' && VERSION_RE.test(r.fixed_in) && typeof r.reason === 'string';
  };
  if (!Array.isArray(notPromotable) || !notPromotable.every(entry)) {
    throw new Refusal(`The previous stable record (${commit}:${RECORD_FILE}) has a not_promotable list that is not {version, reason, fixed_in} entries, so it cannot be carried forward; repair the stable-record branch by hand (${DOCS}).`);
  }
  return {
    commit,
    version: typeof prior.version === 'string' ? prior.version : null,
    releaseCommit: typeof prior.commit === 'string' ? prior.commit : null,
    knownBad: Array.isArray(prior.known_bad) ? prior.known_bad.filter((v): v is string => typeof v === 'string' && VERSION_RE.test(v)) : [],
    notPromotable: notPromotable.map(e => ({ version: e.version, reason: e.reason, fixed_in: e.fixed_in })),
  };
}

/** Commit stable.json for `fields` on top of the previous record commit (none before the first record). */
async function commitRecord(deps: PromoteDeps, fields: TagFields, knownBad: string[], notPromotable: NotPromotable[], parent: string | null): Promise<string> {
  const record = renderRecord(fields, knownBad, notPromotable);
  const bytes = Buffer.byteLength(record);
  if (bytes > STABLE_RECORD_MAX_BYTES) throw new Refusal(`stable.json would be ${bytes} bytes, over the ${STABLE_RECORD_MAX_BYTES} clients accept, so nothing was pushed; shorten the not_promotable reasons or take old entries off with not_promotable_remove.`);
  const blob = await gitOut(deps, ['hash-object', '-w', '--stdin'], 'Could not write the stable record blob; re-run this workflow.', record);
  const recordTree = await gitOut(deps, ['mktree'], 'Could not write the stable record tree; re-run this workflow.', `100644 blob ${blob}\t${RECORD_FILE}\n`);
  const recordCommit = await gitOut(deps, ['commit-tree', recordTree, ...(parent ? ['-p', parent] : []), '-m', `stable record: v${fields.version}`],
    'Could not commit the stable record; re-run this workflow.');
  deps.log(`[promote-stable] stable record ${recordCommit} (known_bad: ${knownBad.length ? knownBad.join(', ') : 'none'}; not_promotable: ${notPromotable.length ? notPromotable.map(e => e.version).join(', ') : 'none'}).`);
  return recordCommit;
}

/**
 * GBRA-346 bridge: promoting the current stable again writes its stable.json and moves no tag. Promotions made before
 * the evidence record existed moved `stable` without one, so a client that reads only the record would see
 * `stable_missing`. The record is the stable tag's own message (the release, its tree and the soak run it was promoted
 * on), checked against the release just verified and the soak run passed in, with known_bad carried forward. The push
 * leases both `stable` (re-pushed unchanged) and the record branch, so a stable tag moved since it was read refuses.
 */
async function recordCurrentStable(deps: PromoteDeps, inputs: PromoteInputs, release: { version: string; commit: string; tree: string }, current: { tagObject: string }): Promise<Promotion> {
  const { version, commit, tree } = release;
  const already = `v${version} is already the stable release`;
  const tagged = parseTagMessage((await deps.git(['for-each-ref', '--format=%(contents)', STABLE_REF])).stdout);
  if (!tagged || tagged.version !== version) throw new Refusal(`${already}, but the stable tag carries no promotion message for it (the key: value body this script writes) to write stable.json from; write the record by hand (${DOCS}).`);
  if (tagged.commit !== commit) throw new Refusal(`${already}, but the stable tag's message names commit ${tagged.commit}, not v${version}'s commit ${commit}; investigate the stable tag before writing its record (${DOCS}).`);
  if (tagged.tree !== tree) throw new Refusal(`${already}, but the stable tag's message names tree ${tagged.tree}, not v${version}'s tree ${tree}; investigate the stable tag before writing its record (${DOCS}).`);
  if (tagged.soakRun !== inputs.soakRunUrl.trim()) throw new Refusal(`${already}, promoted on soak run ${tagged.soakRun}, not ${inputs.soakRunUrl.trim()}; pass the soak run the stable tag names to write its record.`);

  const prior = await readPriorRecord(deps);
  const knownBad = mergeKnownBad(prior?.knownBad ?? [], inputs.withdraw ?? [], version);
  const notPromotable = mergeNotPromotable(prior?.notPromotable ?? [], inputs.notPromotable ?? [], version, inputs.notPromotableRemove ?? []);
  const sameNotPromotable = JSON.stringify(notPromotable) === JSON.stringify(mergeNotPromotable(prior?.notPromotable ?? [], [], version));
  if (prior && prior.version === version && prior.releaseCommit === commit && knownBad.length === new Set(prior.knownBad).size && sameNotPromotable) {
    throw new Refusal(`${already}, and stable.json on stable-record records it, so there is nothing to promote.`);
  }
  deps.log(`[promote-stable] ${already}; writing its stable.json from the stable tag's message (${prior ? `the record named v${prior.version ?? 'nothing'}` : 'no record was published'}).`);
  const recordCommit = await commitRecord(deps, tagged, knownBad, notPromotable, prior?.commit ?? null);
  await gitOut(deps, ['push', '--atomic', `--force-with-lease=${STABLE_REF}:${current.tagObject}`, `--force-with-lease=${RECORD_BRANCH_REF}:${prior?.commit ?? ''}`, 'origin',
    `${STABLE_REF}:${STABLE_REF}`, `${recordCommit}:${RECORD_BRANCH_REF}`],
    'Writing the stable record failed and nothing changed on the remote (stable or the record may have moved since this run read them); re-run this workflow, which re-reads both.');
  deps.log(`[promote-stable] stable.json now records v${version} (${commit}); no tag moved.`);
  const promotion: Promotion = { ...tagged, recordCreated: false, knownBad };
  deps.summary(renderSummary(promotion, notPromotable));
  return promotion;
}

export async function promote(deps: PromoteDeps, inputs: PromoteInputs): Promise<Promotion> {
  const { version, rollback, reason } = inputs;

  await authorize(deps);

  if (!VERSION_RE.test(version)) throw new Refusal(`version "${version}" is not a release version; pass the VERSION of a published release, like 0.60.361.0.`);
  if (rollback && !reason.trim()) throw new Refusal(ROLLBACK_NEEDS_REASON);
  const releaseRef = `refs/tags/v${version}`;
  if (!(await refExists(deps, `${releaseRef}^{commit}`))) throw new Refusal(`There is no release tag v${version}; promote a version release.yml has already published.`);
  const commit = await gitOut(deps, ['rev-parse', `${releaseRef}^{commit}`], `Could not resolve ${releaseRef}; re-run this workflow.`);
  const tree = await gitOut(deps, ['rev-parse', `${releaseRef}^{tree}`], `Could not resolve the tree of ${releaseRef}; re-run this workflow.`);
  if (deps.scheduled && !(await onReleaseBranch(deps, commit))) throw new Refusal(`v${version} (${commit}) is not on master; the scheduled check only promotes a release minted from master, so a maintainer decides on this one.`);
  const taggedVersion = (await deps.git(['show', `${releaseRef}:VERSION`])).stdout.trim();
  if (taggedVersion !== version) throw new Refusal(`v${version}'s VERSION file says "${taggedVersion || 'nothing'}"; promote a tag release.yml minted for its own VERSION.`);
  let release: { draft?: boolean; id?: unknown };
  try {
    release = await deps.ghApi(`repos/${deps.repo}/releases/tags/v${version}`) as { draft?: boolean; id?: unknown };
  } catch (error) {
    throw new Refusal(`v${version} has no published GitHub release (${(error as Error).message.split('\n')[0]}); wait for release.yml to publish it, then promote.`);
  }
  if (release.draft) throw new Refusal(`The GitHub release for v${version} is still a draft; publish it (release.yml does), then promote.`);
  if (typeof release.id !== 'number') throw new Refusal(`The GitHub release for v${version} has no id, so it cannot be marked Latest; re-run this workflow.`);
  const releaseId = release.id;
  deps.log(`[promote-stable] v${version} is commit ${commit}, tree ${tree}, and its GitHub release is published.`);

  const { runId, attempt } = parseRunUrl(inputs.soakRunUrl, deps.repo);
  const soakPath = requireSoakWorkflow(deps.soakWorkflow);
  const run = await deps.ghApi(`repos/${deps.repo}/actions/runs/${runId}${attempt ? `/attempts/${attempt}` : ''}`) as SoakRun;
  checkSoakRun(run, deps.soakWorkflow, inputs.soakRunUrl);
  const headSha = run.head_sha ?? '';
  if (!SHA_RE.test(headSha)) throw new Refusal(`Soak run ${inputs.soakRunUrl} reports no head commit; pass a run that checked out a commit.`);
  deps.log(`[promote-stable] soak run ${runId}${attempt ? ` attempt ${attempt}` : ''} of ${soakPath} succeeded on ${headSha}.`);

  if (!(await refExists(deps, `${headSha}^{commit}`))) await deps.git(['fetch', '--no-tags', 'origin', headSha]);
  const soakTree = await gitOut(deps, ['rev-parse', `${headSha}^{tree}`], `Could not fetch the soak run's head commit ${headSha}; check it still exists on the remote, then re-run this workflow.`);
  if (soakTree !== tree) throw new Refusal(`The soak ran tree ${soakTree} (run head ${headSha}) but v${version} is tree ${tree}; soak this exact release, then promote that run.`);
  deps.log(`[promote-stable] the soak ran the release's exact tree ${tree}.`);

  const current = await currentStable(deps);
  if (current && !rollback && compareVersions(version, current.version) === 0) return recordCurrentStable(deps, inputs, { version, commit, tree }, current);
  checkOrder(version, current?.version ?? null, rollback, reason);
  const matrixRun = await checkMatrix(deps, inputs, { version, commit, tree });
  deps.log(`[promote-stable] current stable is ${current ? `v${current.version}` : 'none'}; ${rollback ? `rollback to v${version}: ${reason.trim()}` : `v${version} is newer`}.`);

  const recordRef = `refs/tags/stable-v${version}`;
  const recordExists = await refExists(deps, recordRef);
  if (recordExists && !rollback) throw new Refusal(`stable-v${version} already exists, so v${version} was promoted before; to make it stable again, re-run with rollback=true and a reason.`);
  if (recordExists) {
    const recordCommit = await gitOut(deps, ['rev-parse', `${recordRef}^{commit}`], `Could not resolve ${recordRef}; re-run this workflow.`);
    if (recordCommit !== commit) throw new Refusal(`stable-v${version} points at ${recordCommit}, not the release commit ${commit}; investigate the tags before promoting.`);
  }
  deps.log(`[promote-stable] record tag stable-v${version} ${recordExists ? 'exists (rollback re-promotion): keeping it' : 'is new: creating it'}.`);

  const fields: TagFields = {
    version, commit, tree,
    soakRun: inputs.soakRunUrl.trim(),
    scoreboard: inputs.scoreboardUrl.trim() || inputs.soakRunUrl.trim(),
    ...(matrixRun ? { matrixRun } : {}),
    promotedBy: deps.scheduled ? `schedule (${DAILY_WORKFLOW})` : deps.actor,
    promotedAt: deps.now().toISOString().replace(/\.\d{3}Z$/, 'Z'),
    previous: current?.version ?? null,
    rollback, reason,
  };
  const message = renderTagMessage(fields);
  const changelog = rollback ? null : await deps.git(['show', `${releaseRef}:CHANGELOG.md`]);
  const notes = changelog === null ? null : rolledUpNotes(changelog.code === 0 ? changelog.stdout : '', fields.previous, version, deps.repo, fields.previous ? upgradeSummary(fields.previous, version) : null);

  // The evidence record: carried forward from the previous record commit (none before the first promotion).
  const prior = await readPriorRecord(deps);
  const priorRecordCommit = prior?.commit ?? null;
  const knownBad = mergeKnownBad(prior?.knownBad ?? [], inputs.withdraw ?? [], version);
  const notPromotable = mergeNotPromotable(prior?.notPromotable ?? [], inputs.notPromotable ?? [], version, inputs.notPromotableRemove ?? []);
  const recordCommit = await commitRecord(deps, fields, knownBad, notPromotable, priorRecordCommit);

  if (!recordExists) {
    await gitOut(deps, ['tag', '-a', '--cleanup=verbatim', '-m', message, `stable-v${version}`, commit], `Could not create the tag stable-v${version}; re-run this workflow.`);
  }
  await gitOut(deps, ['tag', '-a', '-f', '--cleanup=verbatim', '-m', message, 'stable', commit], 'Could not create the stable tag; re-run this workflow.');
  // One atomic push: the record tag, stable and the evidence record land together or not at all. stable and the record
  // branch are leased on the values read above (empty: must not exist yet), so a concurrent move refuses instead of being
  // overwritten.
  await gitOut(deps, ['push', '--atomic', `--force-with-lease=${STABLE_REF}:${current?.tagObject ?? ''}`,
    `--force-with-lease=${RECORD_BRANCH_REF}:${priorRecordCommit ?? ''}`, 'origin',
    ...(recordExists ? [] : [`${recordRef}:${recordRef}`]), `${STABLE_REF}:${STABLE_REF}`, `${recordCommit}:${RECORD_BRANCH_REF}`],
    'Moving the stable tag failed and nothing changed on the remote (stable may have moved since this run read it); re-run this workflow, which re-reads the current stable.');
  if (!recordExists) deps.log(`[promote-stable] pushed record tag stable-v${version}.`);
  deps.log(`[promote-stable] stable now points at v${version} (${commit}).`);
  await markLatest(deps, releaseId, version, notes, rollback);

  const promotion: Promotion = { ...fields, recordCreated: !recordExists, knownBad };
  deps.summary(renderSummary(promotion, notPromotable));
  return promotion;
}

/**
 * The upgrade matrix run a promotion names, judged by judgeMatrixRun (scripts/stable-matrix.ts); refuses a red,
 * foreign or unreadable run. A scheduled forward promotion must name one; a maintainer may promote without one.
 */
async function checkMatrix(deps: PromoteDeps, inputs: PromoteInputs, release: { version: string; commit: string; tree: string }): Promise<string> {
  const url = (inputs.matrixRunUrl ?? '').trim();
  if (!url) {
    if (inputs.rollback) return '';
    if (deps.scheduled) throw new Refusal(`a scheduled promotion needs a green upgrade matrix run on v${release.version}'s exact tree; the daily check dispatches one (${MATRIX_DOCS}).`);
    deps.log(`[promote-stable] no upgrade matrix run given: v${release.version} is promoted on ${deps.actor}'s decision, and the record's matrix_run is null.`);
    return '';
  }
  const { runId, attempt } = parseRunUrl(url, deps.repo, 'matrix_run_url');
  if (attempt) throw new Refusal(`matrix_run_url names attempt ${attempt}; pass the run URL without /attempts/, whose receipt is the run's latest.`);
  if (!deps.matrixReceipt) throw new Refusal('This caller cannot read upgrade matrix receipts; run the promotion from promote-stable.yml or stable-daily.yml.');
  const run = await deps.ghApi(`repos/${deps.repo}/actions/runs/${runId}`) as MatrixRunRow;
  const judged = judgeMatrixRun({ ...run, html_url: url }, await deps.matrixReceipt(Number(runId)), release, inputs.matrixExcuse);
  if (!judged.ok) throw new Refusal(`${judged.why}; promote only a release whose upgrade matrix run passed on its exact tree (${MATRIX_DOCS}).`);
  deps.log(`[promote-stable] ${judged.why}.`);
  return url;
}

const MATRIX_DOCS = 'docs/RELEASING.md#daily-stable-check';

/** GitHub's limit on a release body is 125,000 characters; stay under it with room for the trailer. */
export const RELEASE_NOTES_MAX = 120_000;

/**
 * The stable release's notes: every CHANGELOG.md section newer than `previous` up to and including `version`, newest
 * first, under one line naming the previous stable. Oldest sections drop first when the roll-up would pass
 * RELEASE_NOTES_MAX, and a link to the full CHANGELOG at the tag says so. With no previous stable it is the release's
 * own entry; with no matching section it is the same link stub release.yml writes. The behavior-change summary sits
 * under the opening line, and is left out when it alone would pass RELEASE_NOTES_MAX.
 */
export function rolledUpNotes(changelog: string, previous: string | null, version: string, repo: string, summary: string[] | null = null): string {
  const link = `https://github.com/${repo}/blob/v${version}/CHANGELOG.md`;
  const wanted = (v: string) => compareVersions(v, version) <= 0 && (previous === null ? compareVersions(v, version) === 0 : compareVersions(v, previous) > 0);
  const sections: string[][] = [];
  let current: string[] | null = null;
  for (const line of changelog.split('\n')) {
    if (line.startsWith('## [')) {
      const v = /^## \[(\d+(?:\.\d+){2,3})\]/.exec(line)?.[1];
      current = v && wanted(v) ? [line] : null;
      if (current) sections.push(current);
      continue;
    }
    current?.push(line);
  }
  if (sections.length === 0) return `See [CHANGELOG.md](${link}) for v${version}.\n`;
  const opening = previous === null ? `Stable release v${version}.\n` : `Stable release v${version}: every change since the previous stable release, v${previous}, newest first.\n`;
  const summarized = summary ? `${opening}\n${summary.join('\n')}\n` : opening;
  const intro = summarized.length + 200 > RELEASE_NOTES_MAX ? opening : summarized;
  const bodies = sections.map(s => `${s.join('\n').trimEnd()}\n`);
  const kept: string[] = [];
  let size = intro.length;
  for (const body of bodies) {
    if (kept.length > 0 && size + body.length + 200 > RELEASE_NOTES_MAX) break;
    kept.push(body);
    size += body.length + 1;
  }
  if (kept[0]!.length + intro.length + 200 > RELEASE_NOTES_MAX) return `${intro}\nThe notes are too long for this page; read them in [CHANGELOG.md](${link}).\n`;
  const dropped = bodies.length - kept.length;
  const tail = dropped ? `\n${dropped} older ${dropped === 1 ? 'entry is' : 'entries are'} in [CHANGELOG.md](${link}).\n` : '';
  return [intro, ...kept].join('\n') + tail;
}

/** The version of the release GitHub calls Latest now, or null when there is none or it cannot be read. */
export async function latestReleaseVersion(deps: Pick<PromoteDeps, 'repo' | 'ghApi'>): Promise<string | null> {
  return readLatestReleaseVersion(deps).catch(() => null);
}

/** The current Latest release's version; null when there is none (404). Any other failed read throws. */
async function readLatestReleaseVersion(deps: Pick<PromoteDeps, 'repo' | 'ghApi'>): Promise<string | null> {
  let release: { tag_name?: string };
  try {
    release = (await deps.ghApi(`repos/${deps.repo}/releases/latest`)) as { tag_name?: string };
  } catch (error) {
    if (/HTTP 404/.test((error as Error).message)) return null;
    throw error;
  }
  const v = (release.tag_name ?? '').replace(/^v/, '');
  return VERSION_RE.test(v) ? v : null;
}

/**
 * Mark a release GitHub's "Latest": clear pre-release, set make_latest, and replace the notes when `notes` is given.
 * A forward promotion never moves Latest to an older release than the current one: binaries released before
 * pre-releases existed download `releases/latest` as their newest release, so moving it back would downgrade them. Latest
 * then stays put until stable passes it. A rollback moves it back on purpose.
 */
export async function markLatest(deps: PromoteDeps, releaseId: number, version: string, notes: string | null, rollback = false): Promise<void> {
  let latest: string | null = null;
  if (!rollback) {
    try {
      latest = await readLatestReleaseVersion(deps);
    } catch (error) {
      throw new Refusal(`stable now points at v${version}, but GitHub's current Latest release could not be read (${(error as Error).message.split('\n')[0]}), so Latest was left alone; run \`bun scripts/release-channel.ts backfill --apply\` from a checkout to set it (${DOCS}).`);
    }
  }
  if (latest && compareVersions(latest, version) > 0) {
    deps.log(`[promote-stable] GitHub's Latest stays v${latest}, which is newer than v${version}; it moves to the stable release once stable passes it.`);
    return;
  }
  try {
    await deps.ghApiWrite('PATCH', `repos/${deps.repo}/releases/${releaseId}`, { prerelease: false, make_latest: 'true', ...(notes === null ? {} : { body: notes }) });
  } catch (error) {
    throw new Refusal(`stable now points at v${version}, but marking its GitHub release Latest failed (${(error as Error).message.split('\n')[0]}); run \`bun scripts/release-channel.ts backfill --apply\` from a checkout to set it (${DOCS}).`);
  }
  deps.log(`[promote-stable] the GitHub release v${version} is now Latest${notes === null ? '' : ', with notes rolled up since the previous stable'}.`);
}

export function processDeps(env: NodeJS.ProcessEnv = process.env, cwd = process.cwd()): PromoteDeps {
  return {
    repo: env.GITHUB_REPOSITORY ?? '',
    actor: env.GITHUB_ACTOR ?? '',
    soakWorkflow: env.STABLE_SOAK_WORKFLOW ?? '',
    async ghApi(path) {
      const r = spawnSync('gh', ['api', path], { cwd, env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
      if (r.status !== 0) throw new Error(`gh api ${path} failed: ${(r.stderr || r.error?.message || '').trim()}`);
      return JSON.parse(r.stdout);
    },
    async ghApiWrite(method, path, body) {
      const r = spawnSync('gh', ['api', '--method', method, path, '--input', '-'], { cwd, env, encoding: 'utf8', input: JSON.stringify(body) });
      if (r.status !== 0) throw new Error(`gh api ${method} ${path} failed: ${(r.stderr || r.error?.message || '').trim()}`);
      return JSON.parse(r.stdout || '{}');
    },
    async git(args, input) {
      const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, ...(input !== undefined ? { input } : {}) });
      return { code: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
    },
    async matrixReceipt(runId) {
      const dir = mkdtempSync(join(tmpdir(), 'matrix-'));
      try {
        const r = spawnSync('gh', ['run', 'download', String(runId), '-R', env.GITHUB_REPOSITORY ?? '', '-n', MATRIX_RECEIPT_ARTIFACT, '-D', dir], { cwd, env, encoding: 'utf8' });
        if (r.status !== 0) return null;
        return JSON.parse(readFileSync(join(dir, `${MATRIX_RECEIPT_ARTIFACT}.json`), 'utf8')) as MatrixReceipt;
      } catch {
        return null;
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
    now: () => new Date(),
    log: line => console.log(line),
    summary: markdown => { if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, markdown); },
  };
}

if (import.meta.main) {
  const env = process.env;
  const inputs: PromoteInputs = {
    version: (env.PROMOTE_VERSION ?? '').trim().replace(/^v/, ''),
    soakRunUrl: env.PROMOTE_SOAK_RUN_URL ?? '',
    scoreboardUrl: env.PROMOTE_SCOREBOARD_URL ?? '',
    rollback: env.PROMOTE_ROLLBACK === 'true',
    reason: env.PROMOTE_REASON ?? '',
    withdraw: (env.PROMOTE_WITHDRAW ?? '').split(',').map(v => v.trim().replace(/^v/, '')).filter(Boolean),
    notPromotable: (env.PROMOTE_NOT_PROMOTABLE ?? '').split(',').map(v => v.trim().replace(/^v/, '')).filter(Boolean)
      .map(version => ({ version, reason: env.PROMOTE_NOT_PROMOTABLE_REASON ?? '', fixed_in: (env.PROMOTE_NOT_PROMOTABLE_FIXED_IN ?? '').trim().replace(/^v/, '') })),
    notPromotableRemove: (env.PROMOTE_NOT_PROMOTABLE_REMOVE ?? '').split(',').map(v => v.trim().replace(/^v/, '')).filter(Boolean),
    matrixRunUrl: env.PROMOTE_MATRIX_RUN_URL ?? '',
  };
  const deps = processDeps();
  try {
    if (!deps.repo || !deps.actor) throw new Refusal('GITHUB_REPOSITORY and GITHUB_ACTOR are unset; run this from the Promote stable workflow (gh workflow run promote-stable.yml).');
    await promote(deps, inputs);
  } catch (e) {
    const why = e instanceof Refusal ? e.message : `the promotion stopped on an unexpected error (${e instanceof Error ? e.message : String(e)}); re-run this workflow, and read the log above if it repeats.`;
    console.log(`::error::Stable not promoted: ${why} Docs: ${DOCS}`);
    process.exit(1);
  }
}