toolroll 0.9.104 → 0.9.105

package/dist/release-approval.d.ts

@@ -1,180 +0,0 @@
-import { type PullRequestReader, type ReleaseCard, type ReleaseSeal, type TermLine } from "./release-card.js";
-import { type ApproveResult, type Scope } from "./scope.js";
-import { type Notification, type Store } from "./store.js";
-import { type ReleaseCiSnapshot } from "./release-refusal.js";
-export { ciWords, releaseApprovalRefusal, releaseCiOf, RELEASE_CI_SEEN_ACTION, type ReleaseCiRun, type ReleaseCiSnapshot } from "./release-refusal.js";
-/**
- * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
- * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
- * it. The coordinator is Toolroll's own runtime reading GitHub through the plane's recorded repository.
- */
-export declare function recordReleaseCi(store: Store, input: {
-    taskId: string;
-    candidate: string;
-    state: ReleaseCiSnapshot["state"];
-    failed: readonly string[];
-    runs: readonly {
-        id?: number | null;
-        name: string;
-        status: string;
-        conclusion: string | null;
-    }[];
-    now: Date;
-}): boolean;
-/** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
- * in progress read alike (neither is finished); the time it was read is not bound. */
-export declare function ciBinding(ci: ReleaseCiSnapshot | null): unknown;
-export type ReleaseApprovalCard = {
-    taskId: string;
-    taskRef: number;
-    repo: string;
-    scope: Scope;
-    seal: ReleaseSeal;
-    /** The chat release card (release-card.ts): the change list and its own digest. */
-    card: ReleaseCard;
-    /** Every signed term, one line each (release-card.ts approvalTermsOf). */
-    terms: TermLine[];
-    ci: ReleaseCiSnapshot | null;
-    /** Why it can't be approved now, in words; null when it can (or already is). */
-    refusal: string | null;
-    approved: {
-        by: string;
-        at: string;
-    } | null;
-    /** The release coordinator stopped (its last step failed): approving needs `toolroll release` run again. */
-    stopped: {
-        step: string;
-        message: string;
-    } | null;
-    /** Binds everything above that a person is shown and can change under them. */
-    digest: string;
-};
-/** A release task from the plane's own state: a sealed form (terms or a release check's purpose) whose repository is the
- * task's project and whose approved commit is the scope's candidate. Never from a title or a task id. */
-export declare function releaseTaskOf(store: Store, taskId: string): {
-    ref: {
-        id: number;
-        repo: string;
-    };
-    scope: Scope;
-    seal: ReleaseSeal;
-} | null;
-/** The authoritative card for a release task waiting for its person, or why there is none. Reads only. */
-export declare function releaseApprovalCard(store: Store, taskId: string, options?: {
-    read?: PullRequestReader;
-}): {
-    ok: true;
-    card: ReleaseApprovalCard;
-} | {
-    ok: false;
-    why: string;
-};
-/** What approving does, in the sheet's and the CLI's words: the consequence, the check's access, and whether later
- * commits carry. */
-export declare function releaseConsequence(card: ReleaseApprovalCard): string[];
-export type ReleaseCardRefusal = {
-    ok: false;
-    reason: "not-release" | "changed" | "approved" | "refused";
-    message: string;
-} | {
-    ok: false;
-    reason: "approve";
-    result: Exclude<ApproveResult, {
-        ok: true;
-    }>;
-};
-/**
- * The one card-approval wrapper (Codex round 2, finding 2): rebuild the authoritative card and compare the digest the
- * person saw; then, in one transaction, re-read the store's parts (the scope digest, the CI reading, the refusal state)
- * and refuse on any change; then hand THAT snapshot's scope digest to `approveNow`, the caller's unchanged
- * transactional `approve()`, which proves the person and seals. Nothing here proves anyone.
- */
-export declare function approveReleaseCard(store: Store, input: {
-    taskId: string;
-    cardDigest: string;
-    read?: PullRequestReader;
-    approveNow: (scopeDigest: string) => ApproveResult;
-}): {
-    ok: true;
-    scope: Scope;
-} | ReleaseCardRefusal;
-export declare const RELEASE_READY_KIND = "release-ready";
-export declare const RELEASE_STOPPED_KIND = "release-stopped";
-/** The one push phrase for a release waiting on its person (push.ts PUSH_WORDS.release). */
-export declare const RELEASE_PUSH_WORDS = "A release is ready for your approval";
-/** The sheet's own address for a task (the in-app link; a push carries the opaque `/approve/<task ref>` instead). */
-export declare const releaseSheetHref: (taskId: string) => string;
-/**
- * The coordinator asked a person (on entering the approval step, a fresh filing or a resumed one): one notification per
- * task and stable scope digest, so a crash between filing and asking is healed by the next run and a repeat says nothing
- * new. Every older `release-ready` row of the project (another task or digest) is resolved first. Nothing when the task
- * isn't a release waiting for a person.
- */
-export declare function noteReleaseReady(store: Store, input: {
-    taskId: string;
-    now: Date;
-}): boolean;
-/** Resolve a task's `release-ready` rows (it was approved, or the release stopped): a push not sent yet never is. */
-export declare function retireReleaseReady(store: Store, taskRef: number, now: Date): number;
-/**
- * The push class `release` and its link, derived at send time from the plane's own state, never from a title, a task id,
- * the stored link or the stored class: the row is a `release-ready` row for exactly its task ref and a scope digest, and
- * that task is a release scope (terms or a release check's purpose, its candidate the approved commit), not put away,
- * not approved, at that same digest. Null otherwise.
- */
-export declare function releasePushOf(store: Store, notification: Pick<Notification, "kind" | "dedupeKey" | "taskRef" | "resolvedAt">): {
-    link: string;
-} | null;
-/** A `release-ready` row that no longer stands (the push pass resolves it instead of sending it). */
-export declare function releaseReadyObsolete(store: Store, notification: Pick<Notification, "kind" | "dedupeKey" | "taskRef" | "resolvedAt">): boolean;
-/**
- * A person's release stopped (CI failed, the check failed, the deploy, the merge, the tag or publication failed, or it
- * stopped waiting): one attention notification per task, step and reason, with the stop's words in the app (the push
- * says only the fixed attention phrase). Its `release-ready` row is resolved, except while it only stopped waiting
- * for the approval (the sheet still approves it then).
- */
-export declare function noteReleaseStopped(store: Store, input: {
-    taskId: string;
-    step: string;
-    reason: string;
-    message: string;
-    now: Date;
-}): boolean;
-/** The card as the CLI prints it, every line control-free (src/terminal-text.ts). */
-export declare function releaseCardLines(card: ReleaseApprovalCard): string[];
-/** One release journal as discovery reads it: strictly, every field it relies on in its exact shape. */
-export type WaitingJournal = {
-    file: string;
-    branch: string;
-    checkout: string;
-    taskId: string;
-    scopeDigest: string;
-    candidate: string;
-    version: string;
-    pr: number;
-};
-/** A journal's own fields, strictly; null when any is missing or not its exact shape. */
-export declare function readWaitingJournal(file: string, raw: unknown, expectedFile: (branch: string) => string): WaitingJournal | null;
-/**
- * Whether a journal (discovery only) names exactly the release the plane sealed: the task is a release scope whose
- * sealed identity has this exact branch, version, pull request and candidate at this scope digest, and the journal's
- * checkout, the task's project and the sealed repository are one real folder (`repo` too, when given). Why not, in words.
- */
-export declare function journalMatchesPlane(store: Store, journal: WaitingJournal, repo: string | null): {
-    ok: true;
-} | {
-    ok: false;
-    why: string;
-};
-/** Every release journal in the state folder, read strictly; unreadable ones are counted, never guessed at. */
-export declare function waitingJournals(stateDir: string, expectedFile: (branch: string) => string): {
-    journals: WaitingJournal[];
-    unreadable: string[];
-};
-/** A release as Home names it (docs/plans/home-other-asks.md, part 1): its version, and why it can't take a yes now
- * in the sheet's own words (`refusalOf`, the one source), or null when this isn't a release. Reads only; Home never
- * approves one, it links to the sheet. */
-export declare function releaseAskOf(store: Store, taskId: string): {
-    version: string;
-    refusal: string | null;
-} | null;

package/dist/release-authority.d.ts

@@ -1,173 +0,0 @@
-/**
- * The release authority record, read (docs/plans/release-once.md, schema v135): one generation of a release a person
- * approved, its carried commits and its deploy and merge operations. Kept apart from store.ts so the one live-release
- * reader (scope.ts liveReleaseOf) can read it without a module cycle; every write is in store.ts.
- */
-import { type ReleasePolicy, type ReleaseTerms } from "./contracts/release-terms.js";
-import type { Store } from "./store.js";
-export type ReleaseState = "open" | "deploying" | "merge-reserved" | "merged" | "revoked" | "expired" | "superseded";
-export declare const LIVE_RELEASE_STATES: readonly ReleaseState[];
-/**
- * Whether an authority's approval has run out at `now`. Nothing writes the `expired` state: expiry is worked out from
- * `expires_at` here, and every reader that asks whether an authority is still good asks through this (or
- * releaseStateAt). The one SQL reader, approval-authority.ts releaseStandsSql, states the same rule in SQL.
- */
-export declare function releaseExpiredAt(a: Pick<ReleaseAuthority, "state" | "expiresAt">, now: Date): boolean;
-/** An authority's state as read at `now`: a live one (open, deploying, merge-reserved) past its time reads as `expired`;
- * an ended one keeps the state it ended in. */
-export declare function releaseStateAt(a: Pick<ReleaseAuthority, "state" | "expiresAt">, now: Date): ReleaseState;
-/** One generation of a release a person approved: the single source of truth for it. */
-export type ReleaseAuthority = {
-    id: number;
-    repo: string;
-    generation: number;
-    previous: number | null;
-    version: string;
-    pr: number;
-    branch: string;
-    base: string;
-    anchorTask: string;
-    anchorDigest: string;
-    approvedSha: string;
-    approvedTree: string;
-    artifactDigest: string | null;
-    tipSha: string;
-    tipTask: string;
-    policyJson: string;
-    policy: ReleasePolicy | null;
-    policyDigest: string;
-    verifyCommand: number;
-    verifyDigest: string;
-    accessDigest: string;
-    state: ReleaseState;
-    rev: number;
-    leaseOwner: string | null;
-    leaseEpoch: number;
-    leaseExpires: string | null;
-    expiresAt: string;
-    createdAt: string;
-    endedAt: string | null;
-    endedBy: string | null;
-};
-/** One later commit carried under an authority. */
-export type ReleaseCarry = {
-    id: number;
-    authority: number;
-    taskId: string;
-    scopeDigest: string;
-    requestId: string;
-    fromSha: string;
-    toSha: string;
-    toTree: string;
-    artifactDigest: string;
-    commits: {
-        sha: string;
-        files: {
-            path: string;
-            added: number;
-            deleted: number;
-        }[];
-    }[];
-    changedLines: number;
-    files: number;
-    churn: number;
-    runtime: string;
-    provedAt: string;
-};
-/** A deploy or merge that can't be undone, fenced by the lease epoch that reserved it. */
-export type ReleaseOperation = {
-    id: string;
-    authority: number;
-    kind: "deploy" | "merge";
-    taskId: string;
-    candidate: string;
-    epoch: number;
-    state: "reserved" | "running" | "succeeded" | "failed" | "unknown";
-    externalRef: string | null;
-    reservedAt: string;
-    finishedAt: string | null;
-    detail: string | null;
-    /** Reserved by a person's own deploy run, with no coordinator holding the release. */
-    direct: boolean;
-    /** The process that reserved, then issued, it (store.ts currentReleaseIssuer); null when none was recorded. */
-    issuer: {
-        pid: number;
-        started: string | null;
-        at: string;
-    } | null;
-    /** A direct deploy's staging folder. */
-    stage: string | null;
-};
-export declare function releaseAuthority(store: Store, id: number): ReleaseAuthority | null;
-/** The newest generation of a release, whatever its state. */
-export declare function newestReleaseGeneration(store: Store, repo: string, version: string, pr: number): ReleaseAuthority | null;
-/** The release authority a task belongs to — as an anchor (any generation) or as a carried commit — or null. */
-export declare function releaseAuthorityOfTask(store: Store, taskId: string): {
-    authority: ReleaseAuthority;
-    carry: ReleaseCarry | null;
-} | null;
-/** Whether a task belongs to any release authority (anchor or carried), from the records alone. */
-/** "Carry release approvals when checks aren't sandboxed": a project setting, newest choice wins (a ledger row each);
- * off by default. Turning it on is a person's own proven act (release-cli.ts); turning it off is anyone's. */
-export declare const UNSANDBOXED_CARRY_ACTION = "release unsandboxed carrying changed";
-export declare function carriesUnsandboxed(store: Store, repo: string): boolean;
-/** How far a check reaches, narrowest first. */
-export declare const CHECK_ACCESS_WIDTH: Readonly<Record<string, number>>;
-export declare function belongsToRelease(store: Store, taskId: string): boolean;
-export declare function releaseCarries(store: Store, authority: number): ReleaseCarry[];
-export declare function releaseCarryTo(store: Store, authority: number, toSha: string): ReleaseCarry | null;
-export declare function releaseOperations(store: Store, authority: number): ReleaseOperation[];
-export declare function releaseOperation(store: Store, id: string): ReleaseOperation | null;
-/** Operations nobody has settled yet: until each is reconciled, nothing new starts. */
-export declare function outstandingReleaseOperations(store: Store, authority: number): ReleaseOperation[];
-/**
- * Why a person's seal of these release terms can't open a new generation now, in words, or null. A live generation is
- * superseded by the new one — but never while one of its operations is unsettled, and never once its merge started.
- */
-export declare function releaseSealProblem(store: Store, terms: ReleaseTerms): string | null;
-/** "Release approval: Ask me / Approve automatically when checks pass": a project setting, newest choice wins (a ledger
- * row each); `ask` by default. Turning it on is a person's credential act (a password typed now); off is one click. */
-export declare const RELEASE_APPROVAL_ACTION = "release approval changed";
-/** The plane's record of what proved an automatic seal (`auto-check` or `auto-green`): one ledger row per seal, its
- * id named by the seal's `mode_digest` as `auto:<id>`. Only release-auto.ts writes it. */
-export declare const AUTO_EVIDENCE_ACTION = "release auto-approved";
-/** An automatic seal taken back for good (the setting lowered, a refusal): its outcome names the seal's `auto:<id>`, and
- * that evidence never stands again. */
-export declare const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
-export type ReleaseApprovalSetting = {
-    auto: boolean;
-    setBy: string | null;
-    at: string | null;
-};
-/** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
-export declare function releaseApprovalSetting(store: Store, repo: string): ReleaseApprovalSetting;
-export declare const releaseAutoApproves: (store: Store, repo: string) => boolean;
-/** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
-export declare const releaseAutoSql: (repo: string) => string;
-/**
- * SQL over a `task_scope` alias: its automatic seal (`auto-check` or `auto-green`) stands on its own evidence row — this
- * task, this kind, `mode_digest = 'auto:<row id>'`, the row's digest and candidate exactly the sealed ones — on a release
- * task (a candidate and release terms signed in), while the project's setting is on. The approver's standing is read
- * beside it (approval-authority.ts).
- */
-export declare const autoSealSql: (scope: string, repo: string) => string;
-/** The evidence an automatic seal names, read strictly; null when the row is missing or doesn't match the seal. */
-export type AutoEvidence = {
-    id: number;
-    kind: "auto-check" | "auto-green";
-    taskId: string;
-    digest: string;
-    candidate: string;
-    at: string;
-    by: string;
-    /** auto-green only: the build whose check passed, its receipt, the CI check runs observed green and when, the base. */
-    run: number | null;
-    receipt: string | null;
-    ci: {
-        id: number;
-        name: string;
-    }[];
-    observedAt: string | null;
-    base: string | null;
-};
-export declare function autoEvidenceOf(store: Store, taskId: string, modeDigest: string | null | undefined, kind: "auto-check" | "auto-green"): AutoEvidence | null;

package/dist/release-auto.d.ts

@@ -1,184 +0,0 @@
-import { type CheckFailure } from "./release.js";
-import { RELEASE_APPROVAL_ACTION, releaseAutoApproves, type ReleaseApprovalSetting, releaseApprovalSetting } from "./release-authority.js";
-import { type Store } from "./store.js";
-export { RELEASE_APPROVAL_ACTION, releaseApprovalSetting, releaseAutoApproves, type ReleaseApprovalSetting };
-/** The setting's words, one place. */
-export declare const RELEASE_APPROVAL_WORDS: {
-    readonly ask: "Ask me";
-    readonly auto: "Approve automatically when checks pass";
-};
-/** How old the plane's own CI observation may be when it seals. */
-export declare const CI_OBSERVATION_MS: number;
-/** One check run on the candidate as the plane's own `gh` reported it (oldest first). */
-export type ObservedCheckRun = {
-    id: number | null;
-    name: string;
-    status: string;
-    conclusion: string | null;
-    app: string | null;
-    suite?: number | null;
-    head?: string | null;
-    workflow?: number | null;
-    /** The workflow's file (GitHub's workflow-run `path`): a required check counts only from its own (REQUIRED_PR_CHECKS_WORKFLOW). */
-    workflowPath?: string | null;
-    /** GitHub's job record shows this unsuccessful attempt ended before any workflow step ran (release-adapters.ts). */
-    beforeTests?: boolean | null;
-};
-/** The plane's own look at GitHub CI for one commit (release-adapters.ts makes it, right before the seal). */
-export type CiObservation = {
-    head: string;
-    observedAt: string;
-    runs: readonly ObservedCheckRun[];
-    /** Whether the history is whole (fewer check suites than GitHub's check-runs ceiling): false or absent refuses. */
-    complete?: boolean;
-};
-type Refusal = {
-    ok: false;
-    why: string;
-};
-/**
- * Change the setting: an approver's act, proven by the caller (on: a password typed now; off: one click). Lowering it,
- * in the same transaction, unseals every automatic seal of the project whose release hasn't started merging and stops
- * their live releases, so nothing approves — or goes on — on the old setting.
- */
-export declare function setReleaseApproval(store: Store, repo: string, auto: boolean, by: string, now: Date): {
-    changed: boolean;
-    withdrawn: string[];
-};
-/**
- * The approval step with the setting on: seal `auto-check`, so the release task's build runs its check before anyone
- * approves it. Idempotent: an `auto-check` already standing on this digest is the answer. A person's own approval
- * already there is left alone (the coordinator then takes the person's road).
- */
-export declare function authorizeAutoCheck(store: Store, input: {
-    taskId: string;
-    digest: string;
-    candidate: string;
-    /** Where the candidate left its release's base branch, as the plane read it from GitHub (release-adapters.ts
-     * readMergeBase): the one comparison base every check of this commit is judged against. Never a task branch. */
-    base: string;
-    now: Date;
-}): {
-    ok: true;
-    already: boolean;
-} | Refusal;
-/**
- * What an automatic approval may ship without a person, as an allowlist over each changed path (auto-approve-green.md):
- * product code under `src/` (its tests included; never its test helpers or fixtures, nor build configuration), test files
- * under `test/` (only `*.test.ts`: never a helper, fixture or setup file; deleting any test needs a person), docs
- * (never the testing policy or plans, never agent or security policy), the changelog and README, and a version bump of
- * package.json and package-lock.json. Everything else — CI, scripts (the check, the build, the harness), test/,
- * dependencies, the lockfile beyond its version, config — and every path the release carry rules never carry, needs a
- * person. Null when the path may ship.
- */
-export declare function autoPathProblem(path: string): string | null;
-/** One CI attempt that failed before its job's latest attempt passed (GitHub showed its runner failing before the
- * tests ran), as the evidence records it. */
-export type CiFailure = CheckFailure;
-/**
- * GitHub CI on the exact head, as the plane read it (every attempt): fresh, every run GitHub Actions, and the same
- * verdict every later release boundary uses (release.ts prChecksVerdict: exact head, each job by its latest attempt,
- * every required check present), where an earlier failure stands only as confirmed infrastructure (GitHub's job record
- * shows it ended before any workflow step ran), at most INFRA_RERUNS_PER_CANDIDATE of them. The tolerated failures are
- * returned for the evidence.
- */
-export declare function ciVerdict(observation: CiObservation, candidate: string, now: Date): {
-    ok: true;
-    failures: CiFailure[];
-} | {
-    ok: false;
-    problem: string;
-};
-/** ciVerdict's problem, or null when CI passes. */
-export declare function ciProblem(observation: CiObservation, candidate: string, now: Date): string | null;
-/**
- * The release approval, once the check passed: seal `auto-green` over the standing `auto-check`, or refuse in words —
- * and on any refusal take the `auto-check` back, so a person decides. Everything is proven again in this one write
- * transaction (docs/plans/auto-approve-green.md, "What auto-green proves").
- */
-export declare function sealAutoGreen(store: Store, input: {
-    taskId: string;
-    digest: string;
-    candidate: string;
-    run: number;
-    receipt: string;
-    ci: CiObservation;
-    evidenceRoot: string;
-    now: Date;
-    /** Whether main's protection holds for the account that merges (release-adapters.ts readMainProtection), as the plane's gh read it just now (null: unreadable). */
-    mainUpToDate: boolean | null;
-}): {
-    ok: true;
-    by: string;
-    at: string;
-    ci: {
-        id: number;
-        name: string;
-    }[];
-} | Refusal;
-/** The automatic road ended without an approval (a refusal, a failed check, a CI failure after the deploy): take the
- * `auto-check` back so the task asks a person, and tell the owner why. Idempotent. */
-export declare function giveUpAutoApproval(store: Store, input: {
-    taskId: string;
-    why: string;
-    now: Date;
-}): void;
-/** A release check failed while checking automatically: tell the owner. The `auto-check` stays: a rerun the release
- * itself made after confirmed infrastructure may still approve itself; any other failure means a person decides. */
-export declare function noteAutoCheckFailed(store: Store, input: {
-    taskId: string;
-    why: string;
-    now: Date;
-}): void;
-/** "Released 0.9.x automatically": the release that approved itself finished. */
-export declare function noteAutoRelease(store: Store, input: {
-    taskId: string;
-    tag: string;
-    now: Date;
-}): void;
-/** Whether a task carries an automatic release seal (any state): it never merges or deploys outside `toolroll release`. */
-export declare function autoReleaseSealed(store: Store, taskId: string): boolean;
-/** The plane's record that an automatic release's publication waits for a person (CI stopped passing after its merge),
- * and a person's answer. The newest row for the task wins. */
-export declare const PUBLISH_HELD_ACTION = "release publish held";
-export declare const PUBLISH_ALLOWED_ACTION = "release publish allowed";
-export declare function holdAutoPublish(store: Store, input: {
-    taskId: string;
-    why: string;
-    now: Date;
-}): void;
-/** Why the release's tag, publication and Homebrew wait for a person, or null. */
-export declare function autoPublishHeld(store: Store, taskId: string): string | null;
-/** A person lets a held publication go on: the caller proved a person (never the lead, a token or a mode). */
-export declare function allowAutoPublish(store: Store, input: {
-    taskId: string;
-    by: string;
-    now: Date;
-}): {
-    ok: true;
-} | Refusal;
-/**
- * A release filed while its pull request's CI still ran (pipeline-speed.md D2): hold every approval but the automatic
- * road's until the plane reads exact-head CI passing (Codex review round 1, finding 4). Recorded before the task is
- * filed, so no moment exists where the filed task is approvable with CI pending. Idempotent.
- */
-export declare function holdApprovalForCi(store: Store, input: {
-    taskId: string;
-    candidate: string;
-    now: Date;
-}): void;
-/**
- * Lift a release's CI hold (an older coordinator's) or end its "CI still running" note on the plane's own reading of
- * GitHub CI (never the coordinator's word): fresh, whole, every run GitHub Actions, on exactly the held candidate, and
- * every required check passed (release.ts prChecksVerdict, as a person's road judges it: a person decides about earlier
- * attempts). With `ask`, the owner of a held release is told it needs them now. Nothing held or noted is a pass.
- */
-export declare function liftCiHold(store: Store, input: {
-    taskId: string;
-    candidate: string;
-    ci: CiObservation;
-    ask: boolean;
-    now: Date;
-}): {
-    ok: true;
-} | Refusal;