toolroll 0.9.57 → 0.9.59

package/dist/store.d.ts

@@ -7,7 +7,7 @@ import { type SavedToolAction, type SavedToolRule } from "./contracts/store-json
 import type { FlowCardChange, FlowCardFields } from "./contracts/flow-card.js";
 import { type Actor } from "./actor.js";
 import { type LiveActivityKind } from "./live.js";
-import { type TokenPurpose } from "./api-tokens.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 ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RouteOverride } from "./phase-routing.js";
@@ -152,13 +152,24 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 117;
+export declare const SCHEMA_VERSION = 119;
+/** 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>>;
+/**
+ * v118 (D7): one credential table for every machine credential. `id` is the canonical identity every reference holds;
+ * `public_id` is the id the secret presents (so_<id>_…, lt_<id>_…) or a coordinator's cid, unique per kind. They are
+ * equal unless the merge found two kinds sharing an id. `account` is the person a token acts as (a lead's owner; for
+ * a coordinator, who minted it); `projects_json` the project limit (a coordinator's projects); `generation` which
+ * issue it is (1, then one more per rotation, per lead token for the same owner, per coordinator of the same name).
+ * Lead tokens never expire; a coordinator made before v101 has no expiry.
+ */
+export declare const CREDENTIAL_TABLE = "\nCREATE TABLE IF NOT EXISTS credential (\n  id            TEXT PRIMARY KEY,\n  kind          TEXT NOT NULL CHECK (kind IN ('person','lead','coordinator')),\n  public_id     TEXT NOT NULL,\n  account       TEXT NOT NULL,\n  name          TEXT NOT NULL,\n  secret_hash   TEXT NOT NULL,\n  access        TEXT NOT NULL CHECK (access IN ('read','act')),\n  projects_json TEXT,\n  per_hour      INTEGER,\n  purpose       TEXT NOT NULL DEFAULT 'api' CHECK (purpose IN ('api','mcp')),\n  generation    INTEGER NOT NULL DEFAULT 1 CHECK (generation >= 1),\n  created_at    TEXT NOT NULL,\n  created_by    TEXT NOT NULL,\n  expires_at    TEXT,\n  last_used_at  TEXT,\n  revoked_at    TEXT,\n  revoked_by    TEXT,\n  replaces      TEXT,\n  replaced_by   TEXT,\n  overlap_until TEXT,\n  UNIQUE (kind, public_id)\n);\n";
 /** v117: each table renamed, by its old name. Rows, ids, foreign keys and indexes go with it (renameForV117). */
 export declare const V117_RENAMED_TABLES: Readonly<Record<string, string>>;
 /** v117: the columns renamed with them (by the table's new name): a subagent's rows name it `subagent`. */
 export declare const V117_RENAMED_COLUMNS: readonly (readonly [table: string, from: string, to: string])[];
-/** A row `PRAGMA foreign_key_check` reports, by today's table names: a row already pointing nowhere before v117 is the
- * same row after it, though RENAME now reports it (and what it points at) under the new names. */
+/** A row `PRAGMA foreign_key_check` reports, by today's table names: a row already pointing nowhere before v117 (or
+ * v118) is the same row after it, though RENAME (or the credential merge) now reports what it points at by the new names. */
 export declare function orphanKey(row: Record<string, unknown>): string;
 /** v115: the tables migrateToV115 drops. */
 export declare const V115_DROPPED_TABLES: readonly string[];
@@ -194,9 +205,18 @@ export declare const V115_DROPPED_TABLES: readonly string[];
  * transaction that checks each count before the old tables are dropped; the
  * rehearsal checks each moved table's rows arrived (HISTORY_RULES). v117 renames the mate's tables to the lead's and the
  * teammates' to its subagents' (SQLite's RENAME, every row, id and link carried), renames their teammate column, and rewrites four internal kinds from 'teammate' to 'subagent' in place; the rehearsal checks
- * each renamed table's rows arrived under its new name.
+ * each renamed table's rows arrived under its new name. v118 (D7) is checked the same way: every row of api_token,
+ * coordinator_credential and lead_credential moves into credential under its kind in one transaction that counts them
+ * before the old tables drop, and the references that named them name credential in place, their rows untouched. v119 only adds four columns
+ * (planning_generation on task_ref, run and plan_revision, defaulting to 0, and decision.superseded_reason, null);
+ * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns).
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
+/** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
+export declare const V119_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
 export type OAuthClientRow = {
@@ -317,6 +337,9 @@ export type TaskRef = {
     plan: "requested" | "drafted" | null;
     /** Planning failures, counted apart from build strikes by design. */
     planStrikes: number;
+    /** v119: which planning context is active. A rewritten scope advances it; plans, revisions and answers from an
+     * earlier generation stay as history, never as the next planner's context. */
+    planningGeneration: number;
     /** What comes back (v34): a branch to publish, or a report to read.
      * Set at filing and never rewritten — a scout's strikes are the task's. */
     deliverable: "branch" | "report";
@@ -1037,6 +1060,8 @@ export type Run = {
     taskRef: number;
     leaseId: string;
     runner: string;
+    /** v119: the task's planning generation when this run opened (0 for every run before it). */
+    planningGeneration: number;
     /** Explicit watch ownership for claimless review runs; null on cron/legacy reviews. */
     watchIncarnation?: string | null;
     /** v50: a ROOT reviewer's attempt ordinal for its source run (1..3);
@@ -1181,7 +1206,12 @@ export type Decision = {
     answeredVia: "cli" | "web" | "telegram" | "slack" | "discord" | "teams" | null;
     choice: string | null;
     note: string | null;
+    /** v119: closed without an answer (state 'answered', no choice) because its task's scope changed or the task was
+     * cancelled. null is every real answer and every question still waiting. */
+    supersededReason: DecisionClosure | null;
 };
+/** Why a question closed without an answer (v119). */
+export type DecisionClosure = "scope-changed" | "cancelled";
 /** Evidence, by reference. `key` is relative to the evidence root, never absolute. */
 export type Artifact = {
     id: number;
@@ -2358,7 +2388,16 @@ export declare class Store {
     };
     /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
     endRotatedApiTokens(now: Date): number;
-    /** A token by id with its kept hash (for the check), or null. */
+    /**
+     * D7: the one check every machine credential takes. The credential a presented secret is (its kind and id), when
+     * its kept hash matches in constant time; null otherwise. Whether it is live, and what its kind may do, stays with
+     * each caller's own policy (a person's API token, a lead token, a coordinator).
+     */
+    presentedCredential(presented: string): {
+        kind: CredentialKind;
+        id: string;
+    } | null;
+    /** A person's API token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id: string): {
         row: ApiTokenRow;
         secretHash: string;
@@ -3424,6 +3463,24 @@ export declare class Store {
         ok: false;
         reason: "live-claim";
     };
+    /**
+     * A rewritten scope starts planning again (v119), in one transaction: the task's planning generation advances, a
+     * requested or drafted plan becomes requested with no strikes, and what the old goal produced leaves the active
+     * planning context — its open questions close (typed 'scope-changed', never a fake answer, their holds and pages
+     * with them) and a revision still waiting for a person is rejected with its hold. The old runs, plans, revisions,
+     * answers and ledger rows all stay: generation-bound reads simply stop offering them to the next planner. Only a
+     * task already planning restarts; false (nothing changed) for any other.
+     */
+    restartPlanning(taskRef: number, now: Date): boolean;
+    /**
+     * Close a task's open and expired questions without answering them (v119): typed with why, no choice, their
+     * holds lifted and their pages resolved, so they leave every decision queue. Answered questions are never touched.
+     * `belowGeneration` limits it to questions asked in earlier planning generations. Caller holds the transaction.
+     */
+    private closeQuestionsLocked;
+    /** The number the next plan revision of a task takes: one past every revision it ever had, in any planning
+     * generation, so a restarted plan's revisions never collide with the history they follow. */
+    nextPlanRevisionNumber(taskRef: number): number;
     /** Move the planning state; null clears it. Caller owns the transaction story. */
     setPlanState(taskRef: number, state: "requested" | "drafted" | null): void;
     addPlanStrike(taskRef: number): number;
@@ -4453,7 +4510,8 @@ export declare class Store {
      * reads in the order the questions arrived. "unanswered" is open + expired:
      * expiry makes a decision louder, never gone.
      */
-    /** The newest planner run's plan document for a task, when one exists. */
+    /** The newest planner run's plan document for a task, when one exists in its current planning generation (v119:
+     * a plan drafted for a scope since rewritten is history, read by its artifact id). */
     latestPlanArtifact(taskRef: number): Artifact | null;
     /** The newest plan-contract INGESTION record on one of this task's
      * planner runs (contract handoff, task 1): what the draft proposed
@@ -4486,8 +4544,9 @@ export declare class Store {
         changedFields: readonly string[];
         status: PlanRevisionStatus;
     }, now: Date): number;
-    /** Every revision for a task, newest first — the immutable history a
-     * reader can show without a second table. */
+    /** Every revision for a task in its current planning generation, newest
+     * first — the immutable history a reader can show without a second table
+     * (v119: an earlier generation's rows stay, read by id). */
     listPlanRevisions(taskRef: number): PlanRevision[];
     /** The current plan revision: the newest row an operator (or an
      * auto-applied plan-only proposal) has actually put in force. Null for
@@ -4544,7 +4603,8 @@ export declare class Store {
     checkpointHistory(run: number): RunCheckpoint[];
     /** The newest scout run's report for a task (v34), when one exists. */
     latestReportArtifact(taskRef: number): Artifact | null;
-    /** Answered questions for one task, newest first — the planner's memory. */
+    /** Answered questions for one task, newest first — the planner's memory. Only real answers from its current
+     * planning generation (v119): a question closed unanswered, or asked about a scope since rewritten, is history. */
     answeredDecisionsFor(taskId: string, limit?: number): {
         question: string;
         choice: string | null;
@@ -4646,7 +4706,7 @@ export declare class Store {
         duplicate?: boolean;
     } | {
         ok: false;
-        reason: "unknown-decision" | "bad-option" | "already-answered" | "bad-note";
+        reason: "unknown-decision" | "bad-option" | "already-answered" | "closed" | "bad-note";
     };
     /**
      * The answer's body, for callers already holding the transaction — the
@@ -4667,7 +4727,7 @@ export declare class Store {
         duplicate?: boolean;
     } | {
         ok: false;
-        reason: "unknown-decision" | "bad-option" | "already-answered" | "bad-note";
+        reason: "unknown-decision" | "bad-option" | "already-answered" | "closed" | "bad-note";
     };
     saveArtifact(artifact: {
         run: number;