toolroll 0.9.104 → 0.9.105

package/dist/release-links.d.ts

@@ -1,29 +0,0 @@
-/**
- * Both CLI names, moved to a deployed runtime (release.ts, step `link`): `toolroll` and `standing-orders` are pointed
- * at `<runtime>/bin.js`, each link replaced whole (a new link renamed over the old one). Each name must then resolve to
- * that file and answer with the released version, or every link goes back to where it pointed before.
- *
- * The coordinator saves what `findCliLinks` saw before switching, so a release killed halfway through relinking still
- * knows where to put each name back. A name on PATH that is a file rather than a link is someone else's and never
- * replaced.
- */
-export declare const CLI_NAMES: readonly ["toolroll", "standing-orders"];
-/** One name on PATH: where its link is and what it pointed at before the release (null: not there yet). */
-export type CliLink = {
-    name: string;
-    path: string;
-    before: string | null;
-    foreign?: true;
-};
-/** Where each name is on PATH. A missing name is made beside the other one; none on PATH at all is an empty list. */
-export declare function findCliLinks(path?: string, names?: readonly string[]): CliLink[];
-/** Point `link` at `target`, atomically: a new link beside it, renamed over it. */
-export declare function pointLink(link: string, target: string): void;
-/**
- * Switch every link to `bin`. `answers(path)` says whether that name now answers as the released build. Any failure
- * puts every link back where `links` says it was, and throws. Switching a link already at `bin` changes nothing, so a
- * resumed relink repeats safely.
- */
-export declare function switchCliLinks(links: readonly CliLink[], bin: string, answers: (path: string) => boolean): CliLink[];
-/** Each link where it pointed before; a link that wasn't there before is removed. */
-export declare function restoreCliLinks(links: readonly CliLink[]): void;

package/dist/release-net.d.ts

@@ -1,90 +0,0 @@
-/**
- * The release tool's one way through a short network failure on the way to GitHub (git or gh): a read that failed for a
- * transient reason — a connection refused or reset, a name that didn't resolve, a time limit, a 5xx, a truncated or
- * unparseable answer, GitHub's secondary rate limit — is asked again with backoff for up to about three minutes, then
- * fails with its original error. A definitive answer (404, 401/403, bad credentials, a missing program) is never asked
- * again. Nothing here ever turns "couldn't read" into an answer: the caller still sees the failure and fails closed.
- *
- * Only a read is retried blindly. A call that changes something (a merge, a tag, a branch push, a release, a tap
- * change) goes through `writeWithRecheck`: after a transient failure it re-reads GitHub to learn whether the write
- * happened, and asks again only when it provably didn't.
- */
-import type { Exec } from "./release-adapters.js";
-export type ExecResult = {
-    code: number;
-    stdout: string;
-    stderr: string;
-};
-/** How long one call may keep asking, and how far apart. */
-export declare const NET_RETRY_BUDGET_MS = 180000;
-export declare const NET_RETRY_MAX_ATTEMPTS = 12;
-export declare const netBackoff: (retry: number) => number;
-type RetryBudget = {
-    remaining: () => number;
-    sleep: (ms: number) => Promise<void>;
-};
-declare const sharedBudget: unique symbol;
-export type RetryOptions = {
-    say: (line: string) => void;
-    sleep: (ms: number) => Promise<void>;
-    now?: () => Date;
-    budgetMs?: number;
-    maxAttempts?: number;
-    /** Recovery reads inherit their write's budget, including under an injected clock. */
-    [sharedBudget]?: RetryBudget;
-};
-/**
- * Whether a failure (its words, and the exit code when it came from a program) is transient: the phrase worth saying,
- * and how long GitHub asked to wait (Retry-After) when it said. Null for a definitive answer or anything unknown —
- * an unknown failure is never retried.
- */
-export declare function transientFailure(text: string, code?: number): {
-    words: string;
-    retryAfterMs: number | null;
-} | null;
-/** Whether one exec result failed transiently (exit 0 never did, unless its answer doesn't parse; see readOnlyCall). */
-export declare function transientResult(result: ExecResult): ReturnType<typeof transientFailure>;
-/**
- * Whether a call only reads (and so may be asked again blindly): `git ls-remote` and `git fetch` (which only moves the
- * coordinator's own remote-tracking refs); REST repository `gh api` reads with only the flags below (gh turns
- * fields or input into a POST); `gh pr list|view|checks`, `gh release view`, `gh repo view`. Anything else is a write, or
- * unknown, and is never retried by `retryingExec`.
- */
-export declare function readOnlyCall(command: string, args: readonly string[]): {
-    kind: "git" | "gh-api" | "gh";
-    jsonBody: boolean;
-} | null;
-/** A short name for a call, said once when it is asked again: `gh api repos/…/check-runs`, `git ls-remote`. */
-export declare function callLabel(command: string, args: readonly string[]): string;
-/**
- * An Exec that asks a read again after a transient failure, with backoff, for up to `budgetMs` (about three minutes)
- * and `maxAttempts` calls; it says why once per call. When the budget runs out it answers the FIRST failure, exactly as
- * the program gave it, so the caller stops with the original error. A definitive answer or a success is returned at
- * once. A call that isn't provably a read (readOnlyCall) is passed straight through, never retried.
- */
-export declare function retryingExec(run: Exec, options: RetryOptions): Exec;
-/** One read, asked again as retryingExec describes. `call` may do more than the read itself (the release's Git
- * re-checks the checkout's config first); anything it throws ends the read at once. */
-export declare function retryCall(call: (remainingMs: number) => Promise<ExecResult>, label: string, options: RetryOptions, jsonBody?: boolean): Promise<ExecResult>;
-/**
- * A write that may be asked again only once GitHub says it didn't happen (idempotency). `write` makes the call;
- * `accept` reads a successful answer into the value (a SyntaxError there is an answer cut short: transient);
- * `refuse` throws for a failure. After a transient failure, `recheck` reads the state (its own reads retried): `done`
- * with the value when the write happened, `not-done` when it provably didn't (only then is it asked again), and
- * anything else — or a recheck that can't read — stops with the write's original error.
- */
-export declare function writeWithRecheck<T>(label: string, options: RetryOptions, steps: {
-    write: (remainingMs: number) => Promise<ExecResult>;
-    accept: (result: ExecResult) => T;
-    refuse: (result: ExecResult) => never;
-    recheck: (options: RetryOptions) => Promise<{
-        state: "done";
-        value: T;
-    } | {
-        state: "not-done";
-    } | {
-        state: "other";
-        why: string;
-    }>;
-}): Promise<T>;
-export {};

package/dist/release-next.d.ts

@@ -1,48 +0,0 @@
-import { deployActionOf, type DeployAction } from "./deploy-phase.js";
-import { type RescueWorld } from "./deploy-rescue.js";
-import { type GateReleaseWorld } from "./release-gate.js";
-import { type ReleaseJournal } from "./release.js";
-import type { Store } from "./store.js";
-/** How long a run waits for another before it says so and stops. */
-export declare const RELEASE_WAIT_MS: number;
-export type RunHolder = {
-    host: string;
-    pid: number;
-};
-export type RunLockSeams = {
-    host?: string;
-    pid?: number;
-    alive?: (pid: number) => boolean;
-    sleep?: (ms: number) => Promise<void>;
-    now?: () => number;
-    waitMs?: number;
-    pollMs?: number;
-};
-/** Take this branch's run lock, waiting for a live holder. Answers how to give it back, or who kept it. */
-export declare function takeReleaseRun(stateDir: string, branch: string, say: (line: string) => void, seams?: RunLockSeams): Promise<{
-    ok: true;
-    release: () => void;
-} | {
-    ok: false;
-    holder: RunHolder;
-}>;
-export type SettleWorld = {
-    rescue: RescueWorld;
-    gate: GateReleaseWorld;
-};
-/** The one action a deployment's journal calls for: a row of the one phase table (deploy-phase.ts). */
-export { deployActionOf, type DeployAction };
-/** Settle what a stopped deployment left, saying what was done. A refusal stops the release before it does anything. */
-export declare function settleDeployment(world: SettleWorld, say: (line: string) => void): Promise<{
-    ok: true;
-} | {
-    ok: false;
-    message: string;
-}>;
-export declare const RELEASE_RESUMED_ACTION = "release resumed";
-/**
- * A person let a held release go on (release-auto.ts allowAutoPublish; the Release sheet's button or `publish-ok`): each
- * sweep, its journal goes on from where it stopped, once per that person's act, under the same run lock. It was merged
- * already, so only the tag, publication and Homebrew are left, and each re-proves itself.
- */
-export declare function resumeAllowedReleases(store: Store, stateDir: string, run: (journal: ReleaseJournal) => Promise<unknown>, now: Date): Promise<number>;

package/dist/release-recheck.d.ts

@@ -1,146 +0,0 @@
-import { type CheckContext, type CheckPart, type CheckReport, type ObligationSnapshot, type SealedInventory, type TargetedPlan } from "./contracts/release-check.js";
-import { type CheckAttempt, type Store, type VerifyCommand } from "./store.js";
-/** The sanity pass every targeted check runs beside its plan: a few fast tests of the core rules, when the tree has them. */
-export declare const SANITY_UNITS: readonly string[];
-/** A run's sealed check evidence, read back and verified (check-report.ts). */
-export type SealedRun = {
-    run: number;
-    attempt: CheckAttempt;
-    report: CheckReport | null;
-    reportDigest: string | null;
-    inventory: SealedInventory | null;
-    context: CheckContext | null;
-    plan: TargetedPlan | null;
-    planDigest: string | null;
-    snapshot: ObligationSnapshot | null;
-    snapshotDigest: string | null;
-};
-export declare function sealedRun(store: Store, root: string, run: number): SealedRun | null;
-/** R(A): what a later check must run again, from A's sealed evidence alone — or why only a full check will do. */
-export type Obligations = {
-    full: string | null;
-    units: string[];
-    parts: CheckPart[];
-    groups: {
-        script: "app" | "flows";
-        kind: "scripted" | "real";
-        groups: string[];
-    }[];
-    versions: string[];
-    /** The identities that have to be reported, and pass. */
-    required: string[];
-    /** Identities skipped at A: they may stay skipped. */
-    skipped: string[];
-};
-/** The disposition of every outcome at A (the table in the plan). */
-export declare function requiredSet(a: {
-    report: CheckReport | null;
-    inventory: SealedInventory | null;
-}): Obligations;
-/** The identities that failed in one run's sealed report (for an obligation snapshot). */
-export declare function failedIdentities(report: CheckReport | null): string[];
-/** The earlier targeted runs of this generation after A, with their sealed report digests and what failed in them. */
-export declare function obligationSnapshot(store: Store, root: string, authority: number, base: number, before: number): ObligationSnapshot;
-/** The plan a targeted run runs: R(A), the snapshot's failures, every test changed since A, and the sanity pass. */
-export declare function planFrom(base: number, obligations: Obligations, snapshot: ObligationSnapshot, changed: readonly string[], units: readonly string[], journeysRan: readonly CheckPart[]): TargetedPlan;
-export type RecheckDecision = {
-    mode: "targeted";
-    authority: number;
-    plan: TargetedPlan;
-    snapshot: ObligationSnapshot;
-    watch: string[];
-} | {
-    mode: "full";
-    authority: number | null;
-    why: string;
-    watch: string[];
-};
-/**
- * Whether the check about to run for this release task may be targeted (planTargetedRecheck): only when A and this run
- * are gate tasks of the same current generation, A is the generation's newest full check with a valid report that
- * accounts for every item and reused nothing from CI, everything since A is test-only (the carry proved it), the
- * execution context matches A's, and no main-check failure is open. Otherwise a full check, told which identities it
- * must still report (watch).
- */
-export declare function planTargetedRecheck(store: Store, root: string, input: {
-    runId: number;
-    taskId: string;
-    repo: string;
-    head: string;
-    command: VerifyCommand;
-    access: string;
-    now: Date;
-}): RecheckDecision;
-/** Coverage of a check: full, composed from A, partial (never passes), or identity-removed (asks again). */
-export type Coverage = "full" | "composed" | "partial" | "identity-removed" | "no-result";
-/**
- * Whether a targeted run B, with A's sealed evidence, its plan and snapshot, covers every item of B's inventory
- * (coverage conservation), and every required identity passed — re-derived from sealed values only.
- */
-export declare function coverageOf(input: {
-    a: {
-        report: CheckReport;
-        inventory: SealedInventory;
-    };
-    b: {
-        report: CheckReport | null;
-        inventory: SealedInventory | null;
-        exitCode: number | null;
-    };
-    plan: TargetedPlan;
-    snapshot: ObligationSnapshot;
-}): Coverage;
-/** A full run's own check: a required identity of the generation that is gone or newly skipped. */
-export declare function fullRunRemovedIdentity(report: CheckReport | null, watch: readonly string[], skippedAtBase: readonly string[]): boolean;
-/** What a composed receipt names (receipt version 3): each link is proved again by provedComposition. */
-export type ComposedLinks = {
-    base: number;
-    baseReceipt: string;
-    baseReport: string;
-    authority: number;
-    carries: number[];
-    artifacts: string;
-    plan: string;
-    snapshot: string;
-    report: string;
-};
-/**
- * After the check: its coverage, and for a composed one the links its receipt names. An identity-removed result stops
- * the release carrying (a person approves it again). `gateOf` reads a run's verified receipt digest.
- */
-export declare function settleCoverage(store: Store, root: string, input: {
-    runId: number;
-    taskId: string;
-    exitCode: number | null;
-    now: Date;
-}, gateOf: (run: number) => string | null): {
-    coverage: Coverage;
-    composed: ComposedLinks | null;
-};
-/**
- * Re-prove every link a composed receipt names, from sealed artifacts and the store: A's receipt and report, this run's
- * plan (re-derived from A's sealed evidence and the sealed snapshot), its snapshot and report, the release's artifact
- * digest on every carry of this task, the generation and the grant. Null when every link holds; else why not.
- */
-export declare function provedComposition(store: Store, root: string, runId: number, links: ComposedLinks, gateOf: (run: number) => string | null, grantOf: (run: number) => string | null): string | null;
-/** The identities a later check of this release still has to run again and pass (the anchor page's obligations). */
-export declare function releaseObligationsOf(store: Store, root: string, authority: number): string[];
-/**
- * The identities a release generation still owes, independent of whether a targeted check is allowed (review round
- * 1): every identity that failed in any of its checks before `before`, until a later check reported it PASSED by name.
- * A failed typecheck or build doesn't wipe them, and a full fallback keeps them: each must be reported again, and a
- * check that drops or newly skips one asks a person again.
- */
-export declare function owedIdentities(store: Store, root: string, authority: number, before: number): string[];
-/**
- * The generation's protected identities (review round 2): every identity that failed in any of its checks before
- * `before`. Never shrinks — a later pass doesn't forgive a later removal: removing, renaming or newly skipping any of
- * them, in any later run of the generation, asks a person again. Separate from what is still owed (owedIdentities).
- */
-export declare function protectedIdentities(store: Store, root: string, authority: number, before: number): string[];
-/**
- * Whether a run's report removed one of the protected identities: a unit test or journey gone or newly skipped from a
- * file or group the run did report, a unit file gone from its inventory, a group or upgrade version missing from a lane
- * that finished. A lane that didn't run or finish is no pass, so it is judged by the next run that does.
- */
-export declare function removedProtected(report: CheckReport | null, inventory: SealedInventory | null, kept: readonly string[]): boolean;

package/dist/release-refusal.d.ts

@@ -1,32 +0,0 @@
-import type { Scope } from "./scope.js";
-import type { Store } from "./store.js";
-/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
-export declare const RELEASE_CI_SEEN_ACTION = "release CI observed";
-/** One check's newest attempt, as the coordinator's own gh read it. A re-run is a new check run id. */
-export type ReleaseCiRun = {
-    id: number | null;
-    name: string;
-    status: string;
-    conclusion: string | null;
-};
-export type ReleaseCiSnapshot = {
-    candidate: string;
-    at: string;
-    state: "passed" | "running" | "failed";
-    failed: string[];
-    runs: ReleaseCiRun[];
-};
-export declare const ciName: (value: unknown) => string;
-/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
-export declare function releaseCiOf(store: Store, taskId: string, candidate: string): ReleaseCiSnapshot | null;
-/** GitHub CI in one line, as the sheet and the CLI say it. */
-export declare function ciWords(ci: ReleaseCiSnapshot | null, candidate: string): string;
-/** Why a release can't be approved now, from the plane's own state, or null. */
-export declare function refusalOf(store: Store, taskId: string, scope: Scope, ci: ReleaseCiSnapshot | null): string | null;
-/**
- * The release refusals every approval road shares (scope.ts approve(), read inside its transaction): for a scope
- * sealing release terms or a release check's purpose, the sheet's own reasons in the sheet's own words, so the task
- * page, Home's in-place yes, chat and `toolroll task approve` refuse exactly what `/t/<id>/release` refuses. Null for
- * every other scope, and for a release nothing stops. The sheet's card digest binding stays the sheet's.
- */
-export declare function releaseApprovalRefusal(store: Store, taskId: string, scope: Scope): string | null;

package/dist/release-view.d.ts

@@ -1,37 +0,0 @@
-import { type Store } from "./store.js";
-export type LandedView = {
-    sha: string;
-    task: string;
-    files: {
-        path: string;
-        added: number;
-        deleted: number;
-    }[];
-};
-export type ReleaseView = {
-    kind: "anchor" | "carried";
-    authority: number;
-    version: string;
-    pr: number;
-    state: string;
-    /** Whether the release still carries later commits, and why not. */
-    carrying: boolean;
-    why: string | null;
-    approver: string | null;
-    anchorTask: string;
-    tipTask: string;
-    expiresAt: string;
-    landed: LandedView[];
-    /** Identities a later check of this release must run again and pass (release-recheck.ts). */
-    obligations: string[];
-    nightly: {
-        at: string;
-        sha: string;
-        outcome: string | null;
-    } | null;
-    openMainFailures: number;
-    /** GitHub's nightly (nightly-github.ts): each open lane failure, held or exempted for this release's tip, and a
-     * warning when it couldn't be read or hasn't run lately. */
-    githubNightly: string[];
-};
-export declare function releaseViewOf(store: Store, taskId: string, now: Date, obligations?: (authority: number) => string[]): ReleaseView | null;