toolroll 0.9.71 → 0.9.72

package/dist/store.d.ts

@@ -15,7 +15,7 @@ import { type Actor } from "./actor.js";
 import { type LiveActivityKind } from "./live.js";
 import { type CredentialKind, type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
-import { type ExecutionProfile, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
+import { type ScopeAuthor, type ExecutionProfile, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RouteOverride } from "./phase-routing.js";
 import type { TerminalClass } from "./exhaustion.js";
 import { type ProviderId } from "./provider.js";
@@ -26,6 +26,7 @@ import type { Scope } from "./scope.js";
 import type { QualityMode } from "./quality.js";
 import type { ProgressSnapshot } from "./plan.js";
 import { type CheckProgressSnapshot } from "./check-progress.js";
+import { type ReleaseTerms } from "./contracts/release-terms.js";
 import { type ProjectAccess } from "./project-access.js";
 import { type LedgerEntry } from "./action-ledger.js";
 import type { LimitReading, LimitWindow } from "./provider-limits.js";
@@ -182,7 +183,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 133;
+export declare const SCHEMA_VERSION = 135;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
 /**
@@ -316,6 +317,26 @@ export declare const V129_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record
     definition: string;
     saved: string;
 }>>>>;
+/** v134 (approval policy): how each protected-work vote was proved, and who decided a flow card at a decision zone.
+ * Saved rows read NULL: no proof or authority on record, which never counts as a person. */
+export declare const V134_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/** v135 (docs/plans/release-once.md): a scope's release terms, part of its digest when present. Saved rows read NULL. */
+export declare const V135_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/**
+ * v135: one approval per release (docs/plans/release-once.md). `release_authority` is the single source of truth for a
+ * release a person approved: one row per generation, changed only by compare-and-swap on `rev`, with a lease whose
+ * epoch goes up on every takeover. `release_carry` records each later commit carried under it, `release_operation` each
+ * deploy or merge that can't be undone. `release_check_attempt` seals a check's intended mode, inventory and context
+ * before it runs. `main_check_failure` keeps one row per item the nightly full check on main found failing, until a
+ * qualifying full pass clears that exact item; `nightly_check` records each nightly firing.
+ */
+export declare const RELEASE_ONCE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS release_authority (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  repo            TEXT NOT NULL,\n  generation      INTEGER NOT NULL,\n  previous        INTEGER REFERENCES release_authority(id),\n  version         TEXT NOT NULL,\n  pr              INTEGER NOT NULL,\n  branch          TEXT NOT NULL,\n  base            TEXT NOT NULL,\n  anchor_task     TEXT NOT NULL,\n  anchor_digest   TEXT NOT NULL,\n  approved_sha    TEXT NOT NULL,\n  approved_tree   TEXT NOT NULL,\n  artifact_digest TEXT,\n  tip_sha         TEXT NOT NULL,\n  tip_task        TEXT NOT NULL,\n  policy_json     TEXT NOT NULL,\n  policy_digest   TEXT NOT NULL,\n  verify_command  INTEGER NOT NULL,\n  verify_digest   TEXT NOT NULL,\n  access_digest   TEXT NOT NULL,\n  state           TEXT NOT NULL CHECK (state IN ('open','deploying','merge-reserved','merged','revoked','expired','superseded')),\n  rev             INTEGER NOT NULL DEFAULT 0,\n  lease_owner     TEXT,\n  lease_epoch     INTEGER NOT NULL DEFAULT 0,\n  lease_expires   TEXT,\n  expires_at      TEXT NOT NULL,\n  created_at      TEXT NOT NULL,\n  ended_at        TEXT,\n  ended_by        TEXT,\n  UNIQUE (repo, version, pr, generation)\n);\nCREATE UNIQUE INDEX IF NOT EXISTS release_authority_live ON release_authority (repo, version, pr)\n  WHERE state IN ('open','deploying','merge-reserved');\nCREATE INDEX IF NOT EXISTS release_authority_anchor ON release_authority (anchor_task);\nCREATE TABLE IF NOT EXISTS release_carry (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  authority       INTEGER NOT NULL REFERENCES release_authority(id),\n  task_id         TEXT NOT NULL UNIQUE,\n  scope_digest    TEXT NOT NULL,\n  request_id      TEXT NOT NULL,\n  from_sha        TEXT NOT NULL,\n  to_sha          TEXT NOT NULL,\n  to_tree         TEXT NOT NULL,\n  artifact_digest TEXT NOT NULL,\n  commits_json    TEXT NOT NULL,\n  changed_lines   INTEGER NOT NULL,\n  files           INTEGER NOT NULL,\n  churn           INTEGER NOT NULL,\n  runtime         TEXT NOT NULL,\n  proved_at       TEXT NOT NULL,\n  UNIQUE (authority, to_sha)\n);\nCREATE TABLE IF NOT EXISTS release_operation (\n  id              TEXT PRIMARY KEY,\n  authority       INTEGER NOT NULL REFERENCES release_authority(id),\n  kind            TEXT NOT NULL CHECK (kind IN ('deploy','merge')),\n  task_id         TEXT NOT NULL,\n  candidate       TEXT NOT NULL,\n  epoch           INTEGER NOT NULL,\n  state           TEXT NOT NULL CHECK (state IN ('reserved','running','succeeded','failed','unknown')),\n  external_ref    TEXT,\n  -- The sha256 of a secret only the reserving coordinator holds: a deploy run adopting this operation proves it.\n  secret_hash     TEXT,\n  -- 1: reserved by a person's own deploy run with no coordinator holding the release (its epoch is the one it found).\n  direct          INTEGER NOT NULL DEFAULT 0,\n  -- The process that reserved, then issued, the call: its pid, its start time and when it was recorded (real time).\n  -- Recovery settles a started operation only once that process is proven gone (review round 2).\n  issuer_pid      INTEGER,\n  issuer_started  TEXT,\n  issued_at       TEXT,\n  -- A person's direct deploy: the staging folder its deployment journals in.\n  stage           TEXT,\n  reserved_at     TEXT NOT NULL,\n  finished_at     TEXT,\n  detail          TEXT\n);\nCREATE INDEX IF NOT EXISTS release_operation_open ON release_operation (authority, state);\nCREATE TABLE IF NOT EXISTS release_check_attempt (\n  run              INTEGER PRIMARY KEY REFERENCES run(id),\n  authority        INTEGER REFERENCES release_authority(id),\n  mode             TEXT NOT NULL CHECK (mode IN ('full','targeted')),\n  base_run         INTEGER REFERENCES run(id),\n  plan_digest      TEXT,\n  snapshot_digest  TEXT,\n  inventory_digest TEXT NOT NULL,\n  context_digest   TEXT NOT NULL,\n  nonce_hash       TEXT NOT NULL,\n  created_at       TEXT NOT NULL,\n  settled_at       TEXT\n);\nCREATE TABLE IF NOT EXISTS main_check_failure (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  repo            TEXT NOT NULL,\n  sha             TEXT NOT NULL,\n  run             INTEGER NOT NULL,\n  item            TEXT NOT NULL,\n  opened_at       TEXT NOT NULL,\n  cleared_by_run  INTEGER,\n  cleared_at      TEXT,\n  UNIQUE (repo, run, item)\n);\nCREATE INDEX IF NOT EXISTS main_check_failure_open ON main_check_failure (repo) WHERE cleared_at IS NULL;\nCREATE TABLE IF NOT EXISTS nightly_check (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  repo            TEXT NOT NULL,\n  sha             TEXT NOT NULL,\n  task            TEXT,\n  run             INTEGER,\n  outcome         TEXT,\n  at              TEXT NOT NULL\n);\n";
 /** v130: a project's network (an approver's setting, egress.ts ProjectNetwork as JSON) and the installation's choice
  * whether an agent may run where no OS confinement exists (one row; 0 until an instance operator turns it on). */
 export declare const CONFINEMENT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS project_network (\n  repo          TEXT PRIMARY KEY,\n  network_json  TEXT NOT NULL CHECK (length(network_json) <= 16384),\n  updated_at    TEXT NOT NULL,\n  updated_by    TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS confinement_setting (\n  id               INTEGER PRIMARY KEY CHECK (id = 1),\n  unfenced_allowed INTEGER NOT NULL DEFAULT 0 CHECK (unfenced_allowed IN (0, 1)),\n  updated_at       TEXT,\n  updated_by       TEXT\n);\nINSERT OR IGNORE INTO confinement_setting (id, unfenced_allowed) VALUES (1, 0);\n";
@@ -2312,7 +2333,9 @@ export declare class Store {
         permissionMode?: UnattendedPermissionMode;
         qualityMode?: QualityMode;
         posture?: "escalated";
-        proposedVia?: "mate" | "coordinator" | "scout" | null;
+        proposedVia?: ScopeAuthor | null;
+        /** v135: release terms (release-once.md); undefined keeps the ones the scope carries, null removes them. */
+        releaseTerms?: ReleaseTerms | null;
     }): void;
     /**
      * Re-file a scope under its OWN current words (v47): the route is
@@ -2329,7 +2352,7 @@ export declare class Store {
      * exactly what the signed digest was bound to. Returns false when the
      * scope vanished mid-ceremony. */
     sealScopeApproval(taskId: string, by: string, now: Date, mutation?: Mutation, basis?: {
-        kind: "mode" | "chat" | "grant";
+        kind: "mode" | "chat" | "grant" | "schedule";
         modeDigest: string;
     }, approverKind?: ApproverKind): boolean;
     /** Whether this task's scope carries a LIVE seal: approved, and the
@@ -2449,7 +2472,7 @@ export declare class Store {
      * changed files come from the build's own diff; `null` (unreadable) counts as protected. */
     protectedResultProblem(taskId: string, changed: readonly string[] | null, completer: string | null): string | null;
     /** One person's yes to these exact bytes (protected work counts two). */
-    recordApprovalVote(taskId: string, digest: string, by: string, now: Date): void;
+    recordApprovalVote(taskId: string, digest: string, by: string, now: Date, proof: string): void;
     /** Who has approved the current scope so far (protected work). */
     approvalVotes(taskId: string): {
         approver: string;
@@ -5694,6 +5717,9 @@ export declare class Store {
         expectEntry?: number;
         /** v91: said in the card's history only; the card's note ({{note}}) is left as it is. */
         historyNote?: string;
+        /** v134: who decided a decision move (approval policy §1.7): a person, a subagent, or a machine credential. Only a
+         * person's approval lets a Pull request zone merge. Absent on other moves. */
+        authority?: FlowDecisionAuthority;
     }, now: Date): boolean;
     /** What a card's current zone is doing: its task, the card's main work, what it waits on, what zones reported. */
     /** Read and written in one transaction, so a pass changing one field never writes back another pass's older task or waiting. */
@@ -5707,6 +5733,7 @@ export declare class Store {
         actor: string;
         note: string | null;
         at: string;
+        authority: FlowDecisionAuthority | null;
     }[];
     /** When a card came into the zone it is in: its latest history line (it is written with every move). */
     flowCardEnteredAt(card: number): string | null;
@@ -7522,3 +7549,198 @@ export type VerifiedAuthor = string & {
     readonly __verifiedAuthor: unique symbol;
 };
 export declare function verifiedAuthor(name: string): VerifiedAuthor;
+/**
+ * Who wrote a scope's text after this write (docs/plans/approval-policy.md §1.4), from trusted context only. A person's
+ * write sets what the caller says (null for their own words), as always. A machine's write — the lead's token or a
+ * remote API run — never clears or downgrades a mark: a quarantined author (a chat proposal, a scout, a coordinator)
+ * stays, and otherwise the lead's write is marked `lead` (a remote run's keeps whatever was there).
+ */
+export declare function provenanceAfter(prior: unknown, requested: ScopeAuthor | null): ScopeAuthor | null;
+/** Who decided a flow card at a decision zone (v134, approval policy §1.7). */
+export type FlowDecisionAuthority = "person" | "subagent" | "lead" | "remote";
+export declare const FLOW_DECISION_AUTHORITIES: readonly FlowDecisionAuthority[];
+/** A release check attempt, sealed before its command runs (release_check_attempt). */
+export type CheckAttempt = {
+    run: number;
+    authority: number | null;
+    mode: "full" | "targeted";
+    baseRun: number | null;
+    planDigest: string | null;
+    snapshotDigest: string | null;
+    inventoryDigest: string;
+    contextDigest: string;
+    nonceHash: string;
+    createdAt: string;
+    settledAt: string | null;
+};
+/** Seal a check attempt before its command is spawned. Once written it never changes (bar its settled mark). */
+export declare function recordCheckAttempt(store: Store, attempt: Omit<CheckAttempt, "createdAt" | "settledAt">, now: Date): void;
+/** A run's sealed check attempt, or null. */
+export declare function checkAttemptOf(store: Store, run: number): CheckAttempt | null;
+/** Release terms as this code writes them: the contract's own reading of them, serialized. */
+export declare function serializeReleaseTerms(terms: ReleaseTerms): string;
+export { LIVE_RELEASE_STATES, belongsToRelease, newestReleaseGeneration, outstandingReleaseOperations, releaseAuthority, releaseAuthorityOfTask, releaseCarries, releaseCarryTo, releaseOperation, releaseOperations, releaseSealProblem, type ReleaseAuthority, type ReleaseCarry, type ReleaseOperation, type ReleaseState, } from "./release-authority.js";
+import { type ReleaseCarry, type ReleaseOperation } from "./release-authority.js";
+/**
+ * Open a release's authority for a person's seal of its terms (inside the seal's transaction): the next generation,
+ * superseding the live one. False when it can't (releaseSealProblem), which refuses the seal.
+ */
+export declare function openReleaseAuthority(store: Store, input: {
+    taskId: string;
+    digest: string;
+    terms: ReleaseTerms;
+    by: string;
+    now: Date;
+}): number | null;
+/** Seal the anchor's artifact digest once (the person's seal authorized building that approved commit). */
+export declare function sealAnchorArtifact(store: Store, id: number, digest: string, now: Date): boolean;
+/** Take (or keep) a release's lease. A takeover by another owner raises the epoch, which fences every operation the
+ * old owner reserved. */
+export declare function takeReleaseLease(store: Store, id: number, owner: string, now: Date, ttlMs?: number): {
+    ok: true;
+    epoch: number;
+} | {
+    ok: false;
+    why: string;
+};
+/** Renew a lease this owner still holds at this epoch. */
+export declare function renewReleaseLease(store: Store, id: number, owner: string, epoch: number, now: Date, ttlMs?: number): boolean;
+/**
+ * Reserve a deploy or a merge of the release tip (the freeze happens here, in the store): a deploy moves `open` to
+ * `deploying` (or, already deploying, reserves a new attempt of the same frozen candidate); a merge moves `deploying`
+ * to `merge-reserved`. `epoch` null is a direct deploy by a person: it takes the current epoch, and only while no
+ * coordinator holds a live lease. Refused while any earlier operation is unsettled.
+ */
+export declare function reserveRelease(store: Store, input: {
+    authority: number;
+    kind: "deploy" | "merge";
+    taskId: string;
+    candidate: string;
+    epoch: number | null;
+    operationId: string;
+    now: Date;
+    secret?: string;
+    issuer?: ReleaseIssuer;
+    stage?: string;
+}): {
+    ok: true;
+    operation: ReleaseOperation;
+} | {
+    ok: false;
+    why: string;
+};
+/** The external call's own fence, taken immediately before the call is spawned: `reserved` → `running` (issuing) only
+ * at the epoch that reserved it, while that epoch still holds the lease (a direct deploy's epoch is checked as
+ * reserved) and the release stands, recording the process that issues it. False: the call must not start. */
+export declare function runReleaseOperation(store: Store, id: string, epoch: number, now: Date, issuer?: ReleaseIssuer): boolean;
+/** Settle an operation: `succeeded`, `failed` or `unknown` (reconciled later). A merge that succeeded ends the release
+ * as `merged`; one that failed puts it back to `deploying`. */
+export declare function finishReleaseOperation(store: Store, id: string, outcome: "succeeded" | "failed" | "unknown", facts: {
+    externalRef?: string | null;
+    detail?: string | null;
+}, now: Date, epoch: number): boolean;
+/** Stop carrying later commits: any active approver, any time before the merge starts. */
+export declare function revokeRelease(store: Store, id: number, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/** Write the carry, in the one transaction that re-proves every mutable fact first (release-carry.ts proveCarry). */
+export type CarryWrite = {
+    authority: number;
+    expectRev: number;
+    expectTip: string;
+    to: string;
+    toTree: string;
+    requestId: string;
+    artifactDigest: string;
+    commits: ReleaseCarry["commits"];
+    changedLines: number;
+    files: number;
+    churn: number;
+    runtime: string;
+    taskId: string;
+    title: string;
+};
+/**
+ * THE carry transaction (release-carry.ts proveCarry step 4), one BEGIN IMMEDIATE: every mutable fact is proved again
+ * — the authority's `rev` and tip, its state and expiry and the whole live-release predicate (liveReleaseOf), the
+ * anchor's sealed artifact digest equal to the candidate's, and whatever `recheck` re-reads (the policy, grant and
+ * check access as they are now) — then it writes the carried task and its scope (the anchor's approved terms, profile,
+ * route and acceptance verbatim, with candidate `to`), its seal (basis `carried`, reference `<authority>:<carry>`), the
+ * carry row, the new tip with `rev + 1`, and the ledger row. A carry already written for (authority, `to`) is returned
+ * as it is.
+ */
+export declare function carryReleaseApproval(store: Store, w: CarryWrite, now: Date, recheck: () => string | null): {
+    ok: true;
+    taskId: string;
+    carry: ReleaseCarry;
+} | {
+    ok: false;
+    why: string;
+};
+/** Thrown inside a seal whose release authority can't open: the whole seal rolls back. */
+export declare class ReleaseSealRefused extends Error {
+}
+/**
+ * Whether a deploy run may adopt operation `id` (deploy-browser.mjs --operation): it is this release's running deploy of
+ * this candidate, reserved at the epoch that still holds a live lease, and the run proves the secret only the
+ * reserving coordinator holds (handed over on stdin, never in argv).
+ */
+export declare function adoptReleaseOperation(store: Store, input: {
+    id: string;
+    authority: number;
+    candidate: string;
+    secret: string;
+    now: Date;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/** The nightly check of main is a check only (release-once.md, part 3). */
+export declare const NIGHTLY_CHECK_ONLY = "The nightly check of main is only a check; it is never published or merged.";
+/** Whether a task reference is a nightly check of main. */
+export declare function nightlyTaskRef(store: Store, taskRef: number): boolean;
+/** Whether a publication belongs to a nightly check of main. */
+export declare function nightlyPublication(store: Store, publication: number): boolean;
+/** A release's result merges only through its coordinator: every other merge road refuses it. */
+export declare const RELEASE_MERGES_ONLY = "This result belongs to a release; it merges only through `toolroll release`.";
+/** Whether a task reference is a release's anchor or a carried release task. */
+export declare function releaseTaskRef(store: Store, taskRef: number): boolean;
+/** Whether a publication belongs to a release's task. */
+export declare function releasePublication(store: Store, publication: number): boolean;
+/** The ledger act that records a trusted read of a project's recorded remote main (remote-main.ts). */
+export declare const TRUSTED_MAIN_ACTION = "remote main read";
+/** The identity of a project's recorded remote: its URL and the ledger record that last set it (0: set on admission
+ * with no record). A read of main stands only for the remote identity it was read from (review round 2). */
+export declare function trustedRemoteIdentity(store: Store, repo: string): {
+    url: string;
+    record: number;
+} | null;
+/** Record the commit the project's recorded remote main was at, as Toolroll's own process fetched it just now from
+ * `url`, bound to the remote's identity at this moment. Refused (nothing recorded) when `url` isn't the recorded one. */
+export declare function recordTrustedMain(store: Store, repo: string, sha: string, url: string, now: Date): boolean;
+/** A failed read of the recorded remote: the last read no longer stands. */
+export declare function forgetTrustedMain(store: Store, repo: string, why: string, now: Date): void;
+/**
+ * A pull request check failed after the deploy reservation (Alex, 2026-10-25): the candidate froze at deploy, so the
+ * release stops and asks a person again — even for the same commit, a new person-approved generation continues it.
+ */
+export declare function requireFreshReleaseApproval(store: Store, id: number, reason: string, epoch: number, now: Date): boolean;
+/** The process that reserves or issues a release operation: its pid, its start time, and when it was recorded. */
+export type ReleaseIssuer = {
+    pid: number;
+    started: string;
+    at: string;
+};
+/** This process, as a release operation's issuer. Real time, whatever clock a caller passes for the rest. */
+export declare function currentReleaseIssuer(): ReleaseIssuer;
+/**
+ * Whether an operation's issuer is proven gone (review round 2): no process has its pid, or the process that has it
+ * started after the issuer was recorded (so it is another one). Anything unknown — no issuer recorded, a start time
+ * that can't be read — is not proof, and the operation stays for a person.
+ */
+export declare function releaseIssuerGone(op: ReleaseOperation): boolean;