toolroll 0.9.103 → 0.9.105

package/dist/route-store.js

@@ -1,15 +1,3 @@
-/**
- * The only writer of the results-routing rows (docs/plans/results-routing.md, Protection item 1): run_cohort,
- * route_record, models_generation, route_rule, route_exposure*, route_trial_reservation, run.exec_class and
- * task_ref.revision_origin. Release-auto's routing scan (route-hooks.ts) needs a person for any SQL that writes them
- * from anywhere else (the migration and the Models row writers in store.ts aside).
- *
- * Each writer enforces its own invariants, so a new caller can't skip a guard that lives in its caller: a class or
- * an origin outside its list refuses, a first write is never overwritten, a cohort is written only for a code-writing
- * run that exists, and a record is saved only in a state/reason pair the contract names.
- *
- * A policy path (release-auto.ts EVAL_POLICY).
- */
 import { isProtectedWork } from "./approval-policy.js";
 import { trialSealStandsSql } from "./approval-authority.js";
 import { currentLocalOwner, localOwnerInFlight, localOwnerStandsNow } from "./local-owner.js";
@@ -17,25 +5,18 @@ import { passwordlessOn } from "./passwordless.js";
 import { machineActing } from "./scope.js";
 import { NOT_COUNTED_REASONS, RECORD_STATES, REJECT_REASONS, REVISION_ORIGINS } from "./contracts/route-results.js";
 import { BUILT_IN, nightlyTaskRef, releaseTaskRef } from "./store.js";
-// ---- execution class --------------------------------------------------------------------------------------------
-/** A failed run's raw reason, by whose account it failed. Anything not listed counts as the model's (conservative: a
- * missing or unknown class counts against the cheaper model, never for it). */
 export const EXEC_CLASS_OF_REASON = Object.freeze({
     timeout: "model", agent: "model", "agent-reported": "model", "no-op": "model", "no-handoff": "model",
     "moved-head": "model", "moved-branch": "model", "commit-failure": "model",
     git: "infrastructure", setup: "infrastructure", "provider-init": "infrastructure", "provider-unattested": "infrastructure",
     "provider-protocol": "infrastructure", stopped: "infrastructure",
 });
-/** The gateway's terminal classes that say the provider, not the model, ended the attempt. */
 export const INFRASTRUCTURE_TERMINALS = new Set(["auth-expired", "usage-exhausted", "credits-depleted", "transient-throttle"]);
-/** The class a failed run's raw reason (before the tick's normalization) and its terminal class give. */
 export function execClassOf(reason, terminalClass) {
     if (terminalClass !== null && INFRASTRUCTURE_TERMINALS.has(terminalClass))
         return "infrastructure";
     return Object.prototype.hasOwnProperty.call(EXEC_CLASS_OF_REASON, reason) ? EXEC_CLASS_OF_REASON[reason] : "model";
 }
-/** The sealed facts a code-writing run's eligibility is decided from, conservatively: anything unreadable or not
- * sealed is not eligible. Pure reads of the store, in the admission transaction. */
 export function cohortOf(store, input) {
     const base = {
         run: input.run, taskRef: input.taskRef, rootRef: input.taskRef, repo: null, role: input.role, size: null, risky: null, qualityMode: input.qualityMode,
@@ -48,8 +29,6 @@ export function cohortOf(store, input) {
         return ineligible(base, "not-built-in");
     const taskId = String(ref["external_id"]);
     const repo = ref["repo"] === null ? null : String(ref["repo"]);
-    // The family's root, so the record pass finds the family without walking it: a lineage that can't be proved is
-    // its own root (and its record says so).
     const family = store.taskFamilyOf(taskId, null, true);
     const rootRef = family !== null && family.problem === null ? family.root.refId : input.taskRef;
     const sealed = store.sealedRouteOf(taskId);
@@ -69,7 +48,6 @@ export function cohortOf(store, input) {
         evidenceDemands: route.evidence.some(kind => kind === "screenshot" || kind === "manual-review"),
         publication: route.publication, release, protected: isProtected, selection,
     };
-    // Every reason is a sealed fact or a project rule read now; the first that applies is kept.
     if (row.release)
         return ineligible(row, "release");
     if (row.protected)
@@ -88,8 +66,6 @@ export function cohortOf(store, input) {
         return ineligible(row, "large");
     return { ...row, cohortSize: row.size, ineligible: null };
 }
-/** Keep a failed run's execution class from its raw reason, before the tick normalizes it (dispose.ts). First write
- * wins: a later ending of the same run never rewrites the class it was kept with. */
 export function recordExecClass(store, runId, reason) {
     if (!Number.isSafeInteger(runId) || runId < 1 || typeof reason !== "string")
         throw new Error("an execution class names a run and its raw reason");
@@ -97,19 +73,12 @@ export function recordExecClass(store, runId, reason) {
     const kept = execClassOf(reason, terminal == null ? null : String(terminal));
     store.handle.prepare("UPDATE run SET exec_class = ? WHERE id = ? AND exec_class IS NULL").run(kept, runId);
 }
-/** Who a revision came from, written once with the revision's seal; never on a task that revises nothing. */
 export function recordRevisionOrigin(store, taskId, origin) {
     if (!REVISION_ORIGINS.includes(origin))
         throw new Error(`unknown revision origin: ${String(origin)}`);
     store.handle.prepare("UPDATE task_ref SET revision_origin = ? WHERE backend = 'built-in' AND external_id = ? AND revision_of IS NOT NULL AND revision_origin IS NULL")
         .run(origin, taskId);
 }
-/**
- * A code-writing run's cohort snapshot, in its admission transaction (store.ts admitRun), written once and never
- * updated. A snapshot that can't be computed is never a refused admission: the run is recorded as not eligible, and a
- * write that fails leaves no row (its record then reads "started before results were recorded"), so a cheaper model
- * never gains from either.
- */
 export function writeRunCohort(store, input) {
     if (input.role !== "builder" && input.role !== "repair")
         return;
@@ -127,17 +96,13 @@ export function writeRunCohort(store, input) {
       ON CONFLICT (run) DO NOTHING`)
             .run(row.run, row.taskRef, row.rootRef, row.repo, row.role, row.size, row.risky === null ? null : row.risky ? 1 : 0, row.qualityMode, row.evidenceDemands ? 1 : 0, row.publication, row.release ? 1 : 0, row.protected ? 1 : 0, JSON.stringify(row.selection), row.routeDigest, row.provider, row.model, row.cohortSize, row.ineligible, row.startedAt, row.run);
     }
-    catch { /* no snapshot: not counted, never counted as good */ }
+    catch { }
 }
 function fallbackCohort(input) {
     return { run: input.run, taskRef: input.taskRef, rootRef: input.taskRef, repo: null, role: input.role, size: null, risky: null, qualityMode: input.qualityMode,
         evidenceDemands: false, publication: "none", release: false, protected: false, selection: { kind: "configured" },
         routeDigest: input.routeDigest, provider: input.provider, model: input.model, cohortSize: null, startedAt: input.startedAt };
 }
-/** Save a family's record as evaluated now. A decision time is kept while the state stays the same. Once a verdict
- * is final (settled) it never moves — state, reason, result run, acceptance and decision time stay as decided — but
- * the family's spending and counts keep being updated from later revision and repair runs until the record closes
- * (route-results.ts ACCUMULATE_FOR_MS); a closed record is never written again. */
 export function saveResultRecord(store, value, now) {
     if (!RECORD_STATES.includes(value.state))
         throw new Error(`unknown record state: ${value.state}`);
@@ -170,16 +135,9 @@ export function saveResultRecord(store, value, now) {
     WHERE route_record.closed = 0`)
         .run(value.taskRef, value.repo, value.cohortSize, value.provider, value.model, value.state, value.reason, value.resultRun, value.firstStartedAt, value.acceptedAt, value.decidedAt, value.modelFailures, value.infraFailures, Math.max(0, Math.round(value.apiMicrousd)), value.subscriptionRuns, value.subscriptionTokens, value.unknownRuns, value.remediationRuns, value.personRevisions, value.firstCheckPassed === null ? null : value.firstCheckPassed ? 1 : 0, value.agentTurns, value.turnsUnknownRuns, JSON.stringify(value.selections), value.settled ? 1 : 0, value.settled && value.accumulationEnded ? 1 : 0, now.toISOString());
 }
-/** The generation of one (scope, phase) Models row set: 0 before anything changed it. */
 export function modelsGenerationOf(store, scope, phase) {
     return Number(store.handle.prepare("SELECT generation FROM models_generation WHERE scope = ? AND phase = ?").get(scope, phase)?.["generation"] ?? 0);
 }
-/**
- * Move a (scope, phase) generation: called by every Models row writer (store.ts), inside the writer's own
- * transaction, whenever a row actually changed. Rules that depend on a generation that moved are paused in the same
- * transaction (pauseDependentRules), so a configuration change can never leave a rule running on terms it no longer
- * has.
- */
 export function bumpModelsGeneration(store, scope, phase, now) {
     if (typeof scope !== "string" || scope === "" || typeof phase !== "string" || phase === "")
         throw new Error("a generation names its scope and phase");
@@ -188,9 +146,6 @@ export function bumpModelsGeneration(store, scope, phase, now) {
     pauseDependentRules(store, now);
     return modelsGenerationOf(store, scope, phase);
 }
-/** Pause every running rule or trial whose recorded dependency generations no longer match: a compare-and-swap on
- * the rule's own generation, so a rule another writer already moved is left to that writer. An unreadable
- * dependency list pauses too. */
 export function pauseDependentRules(store, now) {
     let paused = 0;
     for (const rule of store.handle.prepare("SELECT id, generation, depends_json FROM route_rule WHERE state IN ('active','trialling')").all()) {
@@ -212,8 +167,6 @@ export function pauseDependentRules(store, now) {
     }
     return paused;
 }
-/** A deleted project's results-routing rows (project-delete.ts, through store.ts forgetProjectModels): its rules,
- * their exposures and trial places, its records and its runs' cohort snapshots. How many rows went. */
 export function forgetProjectRoutes(store, repo) {
     const db = store.handle;
     const rules = "SELECT id FROM route_rule WHERE repo = ?";
@@ -227,8 +180,6 @@ export function forgetProjectRoutes(store, repo) {
     rows += Number(db.prepare(`DELETE FROM run_cohort WHERE repo = ? OR task_ref IN (${refs}) OR root_ref IN (${refs})`).run(repo, repo, repo).changes);
     return rows;
 }
-/** The acts and the door each takes (docs/plans/results-routing.md, Authority). Raising acts take a person with a
- * step-up; lowering acts take a person, or a local owner whose in-flight act is exactly the one named here. */
 export const RULE_ACTS = Object.freeze({
     accept: { raising: true, localAct: null },
     keep: { raising: true, localAct: null },
@@ -236,21 +187,11 @@ export const RULE_ACTS = Object.freeze({
     "turn-off": { raising: false, localAct: "routing-turn-off" },
     dismiss: { raising: false, localAct: "dismiss-suggestion" },
     "suggest-off": { raising: false, localAct: "dismiss-suggestion" },
-    // Slice 3: starting a trial raises (a person's step-up); stopping one only lowers.
     "trial-start": { raising: true, localAct: null },
     "trial-stop": { raising: false, localAct: "trial-stop" },
 });
 const provedDoors = new WeakSet();
-/** Proofs a raising act accepts: a password or identity provider now, or (only while Passwordless is on) a session
- * or remembered CLI login. A lowering act also accepts a signed-in session: it only takes authority away. */
 const RAISING_PROOFS = new Set(["password-now", "sso-now", "fresh-password", "fresh-sso", "session", "cli-login"]);
-/**
- * The rule doors' one proof, run inside the write's transaction: a lead token or a remote API token never acts
- * (`lead-refused`); a person is re-proved — the same account, still active, still an instance operator who can open
- * the project, at the credential generation the proof was made under, by a proof that still stands (model-choices.ts
- * applyModelChoices' re-proof); a local owner only for a lowering act, only while it still stands, and only when its
- * in-flight act is exactly that act's.
- */
 export function proveRuleDoor(store, door, act, repo) {
     if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined)
         return { ok: false, reason: "lead-refused" };
@@ -283,8 +224,6 @@ function spend(door, act) {
         throw new Error("a rule write needs a door proved for exactly this act");
     provedDoors.delete(door);
 }
-/** Insert an accepted earned rule, live. The winner index makes a second live rule for the same project and size
- * refuse (null); nothing else is written. */
 export function insertEarnedRule(store, door, rule, now) {
     spend(door, "accept");
     if (rule.provider !== "claude" || (rule.cohortSize !== "small" && rule.cohortSize !== "medium"))
@@ -302,8 +241,6 @@ export function insertEarnedRule(store, door, rule, now) {
         throw error;
     }
 }
-/** A person's or local owner's end of a live rule — turned off, or a paused one dropped — by compare-and-swap on its
- * generation. False when the rule moved since (or isn't live). */
 export function endRuleByDoor(store, door, ruleId, generation, now) {
     spend(door, "turn-off");
     const row = store.handle.prepare("SELECT state FROM route_rule WHERE id = ?").get(ruleId);
@@ -311,15 +248,11 @@ export function endRuleByDoor(store, door, ruleId, generation, now) {
     return Number(store.handle.prepare(`UPDATE route_rule SET state = ?, generation = generation + 1, ended_at = ?, ended_by = ?, end_reason = ?
     WHERE id = ? AND generation = ? AND state IN ('active','trialling','paused')`).run(state, now.toISOString(), door.actor, state === "dropped" ? "dropped" : "turned-off", ruleId, generation).changes) === 1;
 }
-/** Keep a paused rule: live again, on the configuration generations it depends on now. Its sealed grant (terms,
- * cutoff, expiry) never changes. */
 export function keepPausedRule(store, door, ruleId, generation, depends) {
     spend(door, "keep");
     return Number(store.handle.prepare(`UPDATE route_rule SET state = 'active', generation = generation + 1, depends_json = ?, ended_at = NULL, ended_by = NULL, end_reason = NULL
     WHERE id = ? AND generation = ? AND state = 'paused'`).run(JSON.stringify(depends), ruleId, generation).changes) === 1;
 }
-/** "Not now" on one suggestion: kept as an ended offer (state dropped, reason not-now) so the same suggestion stays
- * quiet for its 30 days; it never blocks a rule. */
 export function recordNotNow(store, door, offer, now) {
     spend(door, "dismiss");
     store.handle.prepare(`INSERT INTO route_rule (repo, cohort_size, kind, provider, model, configured_provider, configured_model, state, generation,
@@ -327,23 +260,15 @@ export function recordNotNow(store, door, offer, now) {
     VALUES (?, ?, 'rule', ?, ?, ?, ?, 'dropped', 1, '{"notNow":true}', ?, '{}', NULL, ?, ?, ?, ?, 'not-now')`)
         .run(offer.repo, offer.cohortSize, offer.provider, offer.model, offer.configuredProvider, offer.configuredModel, JSON.stringify(offer.prices), door.actor, now.toISOString(), now.toISOString(), door.actor);
 }
-/** A project's "Suggest cheaper models" switch. False when the project isn't saved here. */
 export function writeSuggestModels(store, door, repo, on) {
     spend(door, on ? "suggest-on" : "suggest-off");
     return Number(store.handle.prepare("UPDATE project SET suggest_models = ? WHERE path = ?").run(on ? 1 : 0, repo).changes) === 1;
 }
-/** The plane's own end of a rule (no person): switched off by its sealed trigger, paused (a configuration or grant
- * change), or expired. A compare-and-swap on the rule's generation and a live state: false when it moved since. */
 export function endRuleByPlane(store, ruleId, generation, to, reason, now) {
     const from = to === "expired" ? "('active','trialling','paused')" : "('active','trialling')";
     return Number(store.handle.prepare(`UPDATE route_rule SET state = ?, generation = generation + 1, ended_at = ?, ended_by = NULL, end_reason = ?
     WHERE id = ? AND generation = ? AND state IN ${from}`).run(to, now.toISOString(), reason.slice(0, 200), ruleId, generation).changes) === 1;
 }
-// ---- exposure: one row per task and rule, events append-only -----------------------------------------------------
-/** The exposure rows a filing writes (store.ts saveScope): a build leg sealed under a rule opens the task's exposure
- * to it (`proposed`) or, filed again, adds `refiled`; a filing that no longer selects a rule the task was exposed to
- * adds `refiled` to that open exposure, which its approval then closes as approved with another model. Re-filing
- * never adds a row. */
 export function noteExposureFiled(store, taskRef, selection, now) {
     const at = now.toISOString();
     const open = store.handle.prepare("SELECT id, rule FROM route_exposure WHERE task_ref = ? AND closed_at IS NULL").all(taskRef);
@@ -352,13 +277,10 @@ export function noteExposureFiled(store, taskRef, selection, now) {
         appendExposureEvent(store, Number(one["id"]), "refiled", null, at);
     if (rule === null || open.some(one => Number(one["rule"]) === rule))
         return;
-    // Exposed once per task and rule: a closed exposure to the same rule is never reopened.
     const made = store.handle.prepare("INSERT INTO route_exposure (task_ref, rule, created_at) VALUES (?, ?, ?) ON CONFLICT (task_ref, rule) DO NOTHING").run(taskRef, rule, at);
     if (Number(made.changes) === 1)
         appendExposureEvent(store, Number(made.lastInsertRowid), "proposed", null, at);
 }
-/** An approval closes the task's open exposures: as proposed when it sealed that very rule, otherwise approved with
- * the model it sealed. */
 export function noteExposureSealed(store, taskRef, sealed, now) {
     const at = now.toISOString();
     for (const one of store.handle.prepare("SELECT id, rule FROM route_exposure WHERE task_ref = ? AND closed_at IS NULL").all(taskRef)) {
@@ -366,15 +288,12 @@ export function noteExposureSealed(store, taskRef, sealed, now) {
         appendExposureEvent(store, Number(one["id"]), same ? "approved-as-proposed" : "approved-with-other", same ? null : sealed.model, at);
     }
 }
-/** A cancel closes the task's open exposures. */
 export function noteExposureCancelled(store, taskRef, now) {
     for (const one of store.handle.prepare("SELECT id FROM route_exposure WHERE task_ref = ? AND closed_at IS NULL").all(taskRef)) {
         appendExposureEvent(store, Number(one["id"]), "cancelled", null, now.toISOString());
     }
 }
 const EXPOSURE_CLOSERS = new Set(["approved-as-proposed", "approved-with-other", "cancelled"]);
-/** Append one event, in order: `proposed` first and only once, nothing after a closing event, and a closing event
- * closes the exposure in the same write. Anything out of order refuses. */
 function appendExposureEvent(store, exposure, kind, model, at) {
     const events = store.handle.prepare("SELECT kind FROM route_exposure_event WHERE exposure = ? ORDER BY id").all(exposure).map(one => String(one["kind"]));
     if (kind === "proposed" ? events.length !== 0 : events[0] !== "proposed" || events.some(one => EXPOSURE_CLOSERS.has(one)))
@@ -385,9 +304,6 @@ function appendExposureEvent(store, exposure, kind, model, at) {
     if (EXPOSURE_CLOSERS.has(kind))
         store.handle.prepare("UPDATE route_exposure SET closed_at = ? WHERE id = ? AND closed_at IS NULL").run(at, exposure);
 }
-// ---- reads routing makes at filing and admission ------------------------------------------------------------------
-/** A project's live earned rules, as routing reads them (phase-routing.ts EarnedRule): kind rule, state active, a
- * Claude model. A row that doesn't read is left out (it can only ever not apply). */
 export function liveEarnedRules(store, repo) {
     if (repo === null)
         return [];
@@ -399,9 +315,6 @@ export function liveEarnedRules(store, repo) {
                 configured: { provider: String(row["configured_provider"]), model: row["configured_model"] == null ? null : String(row["configured_model"]) } }];
     });
 }
-/** Why a build of this task must not start under the rule its route sealed, or null: the rule switched itself off
- * after the approval and the task hasn't started (docs/plans/results-routing.md, "When a rule ends"). A rule turned off
- * by a person, or expired, keeps the sealed model; a started task's later attempts finish under it. */
 export function ruleHoldOf(store, taskId) {
     const sealed = store.sealedRouteOf(taskId);
     if (!sealed.ok)
@@ -416,8 +329,6 @@ export function ruleHoldOf(store, taskId) {
     WHERE task_ref.backend = ? AND task_ref.external_id = ? AND run.role IN ('builder','repair') LIMIT 1`).get(BUILT_IN, taskId);
     return started === undefined ? { rule: selection.rule, model: String(rule["model"]) } : null;
 }
-/** Start a trial, live (state trialling) with its number of places. The winner index makes a second live rule or
- * trial for the same project and size refuse (null); nothing else is written. */
 export function insertTrial(store, door, trial, now) {
     spend(door, "trial-start");
     if ((trial.cohortSize !== "small" && trial.cohortSize !== "medium") || !Number.isSafeInteger(trial.limit) || trial.limit < 1 || trial.limit > 50)
@@ -435,12 +346,6 @@ export function insertTrial(store, door, trial, now) {
         throw error;
     }
 }
-/**
- * A person's or local owner's stop of a live or paused trial, by compare-and-swap on its generation, in the same
- * transaction as releasing the places of tasks not approved on them (those plans are re-filed by the rule pass). A
- * place a task was approved on stays reserved: that task keeps the model a person approved (as a rule turned off
- * does). False when the trial moved since.
- */
 export function endTrialByDoor(store, door, trialId, generation, now) {
     spend(door, "trial-stop");
     const ended = Number(store.handle.prepare(`UPDATE route_rule SET state = 'turned-off', generation = generation + 1, ended_at = ?, ended_by = ?, end_reason = 'stopped'
@@ -453,8 +358,6 @@ export function endTrialByDoor(store, door, trialId, generation, now) {
     }
     return ended;
 }
-/** A project's live trial for one size, as routing reads it (without this filing's place): state trialling, a Claude
- * model. Null when none, or when its row doesn't read (it can only ever not apply). */
 export function liveTrialFor(store, repo, size) {
     if (repo === null || (size !== "small" && size !== "medium"))
         return null;
@@ -464,13 +367,6 @@ export function liveTrialFor(store, repo, size) {
     return { id: Number(row["id"]), generation: Number(row["generation"]), cohortSize: size, provider: "claude", model: String(row["model"]), limit: Number(row["trial_limit"]),
         configured: { provider: String(row["configured_provider"]), model: row["configured_model"] == null ? null : String(row["configured_model"]) } };
 }
-/**
- * This task's place in a trial, in the filing's own write transaction (store.ts saveScope, serialized by
- * beginWriteWithin): a place it already holds (reserved, or consumed by its own earlier attempt) is reused, so
- * repeated saves never take a second one; a place it gave up is never taken back; otherwise a new one only while
- * reserved + consumed is under the trial's limit and the trial is live. Its digest is bound by settleTrialPlaces in
- * the same transaction. Null: no place.
- */
 export function reserveTrialPlace(store, trialId, taskRef, now) {
     const own = store.handle.prepare("SELECT id, state FROM route_trial_reservation WHERE rule = ? AND task_ref = ?").get(trialId, taskRef);
     if (own !== undefined)
@@ -481,12 +377,6 @@ export function reserveTrialPlace(store, trialId, taskRef, now) {
         .run(trialId, taskRef, now.toISOString(), now.toISOString(), trialId);
     return Number(inserted.changes) === 1 ? Number(inserted.lastInsertRowid) : null;
 }
-/**
- * After a filing, in its transaction: the place its route seals (if any) is bound to the scope digest it was filed
- * under (a compare-and-swap on `reserved`; a place this task's own attempt already consumed stays as it is), and every
- * other place this task holds unconsumed is released. A selection that names a place this task doesn't hold throws:
- * nothing files on it.
- */
 export function settleTrialPlaces(store, taskRef, selection, digest, now) {
     let kept = -1;
     if (selection?.kind === "trial") {
@@ -502,24 +392,15 @@ export function settleTrialPlaces(store, taskRef, selection, digest, now) {
     }
     store.handle.prepare("UPDATE route_trial_reservation SET state = 'released', updated_at = ? WHERE task_ref = ? AND state = 'reserved' AND id != ?").run(now.toISOString(), taskRef, kept);
 }
-/** A cancel gives up every place the task holds unconsumed (store.ts applyCancellationLocked). A consumed place is
- * never released. How many went. */
 export function releaseTrialPlaces(store, taskRef, now) {
     return Number(store.handle.prepare("UPDATE route_trial_reservation SET state = 'released', updated_at = ? WHERE task_ref = ? AND state = 'reserved'").run(now.toISOString(), taskRef).changes);
 }
-/** Whether this place still stands for this task's approval at `digest`: reserved and bound to exactly that digest,
- * or consumed by this task's own earlier attempt. */
 function placeStands(store, selection, taskRef, digest) {
     const row = store.handle.prepare("SELECT rule, task_ref, state, scope_digest FROM route_trial_reservation WHERE id = ?").get(selection.reservation);
     if (row === undefined || Number(row["rule"]) !== selection.rule || Number(row["task_ref"]) !== taskRef)
         return false;
     return row["state"] === "consumed" || (row["state"] === "reserved" && digest !== "" && row["scope_digest"] === digest);
 }
-/**
- * Why a seal of this route must not stand, or null (store.ts sealScopeApproval): a trial task is approved only by a
- * person — their own ceremony (no basis; not a machine acting, not an AI approver's name) or their paired-chat tap —
- * never a mode, a grant, a schedule, a carry, an automatic seal or the lead; and only while its place stands.
- */
 export function trialSealProblem(store, input) {
     if (input.selection?.kind !== "trial")
         return null;
@@ -533,13 +414,6 @@ export function trialSealProblem(store, input) {
         return "this task's trial place is no longer held — re-file it";
     return null;
 }
-/**
- * A code-writing run's trial check, in its admission transaction after the run row exists (store.ts admitRun): for a
- * route sealed on a trial, the approval must be a person's own (approval-authority.ts trialSealStandsSql), and the
- * sealed place is consumed exactly once — a compare-and-swap on `reserved` and the sealed scope digest. A retry or
- * repair of the same task whose place that task already consumed is admitted without consuming again. The words, or
- * null to admit; the caller refuses (rolling the row back) on words.
- */
 export function admitTrialRun(store, input) {
     if (input.role !== "builder" && input.role !== "repair")
         return null;
@@ -562,20 +436,17 @@ export function admitTrialRun(store, input) {
         return "trial-reservation: the trial place this task was approved on was given up — re-file it";
     if (!consumeTrialPlace(store, selection.reservation, String(scope["digest"]), input.run, input.now))
         return "trial-reservation: the trial place doesn't match this approval — re-file it";
-    // Every place used: the trial is finished, and its cohort is free for a suggestion again.
     store.handle.prepare(`UPDATE route_rule SET state = 'finished', generation = generation + 1, ended_at = ?, end_reason = 'all-places-used'
     WHERE id = ? AND kind = 'trial' AND state IN ('trialling','paused')
       AND (SELECT COUNT(*) FROM route_trial_reservation p WHERE p.rule = route_rule.id AND p.state = 'consumed') >= trial_limit`).run(input.now.toISOString(), selection.rule);
     return null;
 }
-/** Consume one reserved place for this run: only with the sealed scope digest it was bound to. */
 export function consumeTrialPlace(store, reservation, sealedDigest, run, now) {
     if (typeof sealedDigest !== "string" || sealedDigest === "" || !Number.isSafeInteger(run) || run < 1)
         throw new Error("a trial place is consumed only against the sealed scope digest, by a run");
     return Number(store.handle.prepare(`UPDATE route_trial_reservation SET state = 'consumed', consumed_run = ?, updated_at = ?
     WHERE id = ? AND state = 'reserved' AND scope_digest = ?`).run(run, now.toISOString(), reservation, sealedDigest).changes) === 1;
 }
-/** A trial's places: its limit, how many are reserved (waiting) and consumed (started). */
 export function trialPlacesOf(store, trialId) {
     const row = store.handle.prepare(`SELECT r.trial_limit AS lim,
       (SELECT COUNT(*) FROM route_trial_reservation p WHERE p.rule = r.id AND p.state = 'reserved') AS reserved,
@@ -583,14 +454,11 @@ export function trialPlacesOf(store, trialId) {
     FROM route_rule r WHERE r.id = ? AND r.kind = 'trial'`).get(trialId);
     return { limit: Number(row?.["lim"] ?? 0), reserved: Number(row?.["reserved"] ?? 0), consumed: Number(row?.["consumed"] ?? 0) };
 }
-/** Which place in its trial this one is (1-based, counting places held or used, in order), or null. */
 export function trialOrdinalOf(store, reservation) {
     const row = store.handle.prepare(`SELECT p.rule, p.state, (SELECT COUNT(*) FROM route_trial_reservation o WHERE o.rule = p.rule AND o.id <= p.id AND o.state IN ('reserved','consumed')) AS ordinal
     FROM route_trial_reservation p WHERE p.id = ?`).get(reservation);
     return row === undefined ? null : { trial: Number(row["rule"]), ordinal: Number(row["ordinal"]), state: String(row["state"]) };
 }
-/** Whether a proposal's trial place still stands for re-use by its next approval: the trial is live and the place is
- * held reserved by that task (the rule pass re-files a proposal whose place doesn't). */
 export function trialPlaceLive(store, selection, taskRef) {
     const row = store.handle.prepare(`SELECT 1 FROM route_trial_reservation p JOIN route_rule r ON r.id = p.rule
     WHERE p.id = ? AND p.rule = ? AND p.task_ref = ? AND p.state IN ('reserved','consumed') AND r.state = 'trialling'`).get(selection.reservation, selection.rule, taskRef);

package/dist/run-closeout.js

@@ -1,37 +1,17 @@
-/**
- * Closing out what a run started. When a run ends, whatever its outcome, anything still running in its process
- * groups — the provider's own group and every process or group the run was seen to start — is stopped: SIGTERM, then
- * SIGKILL for whatever is still there after 10 s. Completing or cancelling a task does the same for what Toolroll left
- * running from its checkout: what a finished run started (descends from one of its processes) or an orphan (its parent
- * gone), never one with a live parent Toolroll did not start (a deploy, a person's agent or shell). Each stop is in
- * the ledger, naming what was stopped.
- *
- * Never the live service: this process, its ancestors and their process groups are never targets.
- *
- * A pid saved in the database is never signalled on its word alone (the OS reuses pids): a target must be alive in a
- * fresh process listing and born no later than the run saw it. A group counts when its leader is that same process,
- * or when the leader is gone and the group still has members (the OS never hands a live group's id to a new
- * process). The worker's pass runs this (operate.ts reconcile), so every road a run ends by is covered.
- */
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
 import { basename, sep } from "node:path";
 import { ownedProcessCount, runOwnerTag } from "./exec.js";
 import { localWitnessSql } from "./store.js";
 import { sleep as defaultSleep } from "./sleep.js";
-/** How long a process has after SIGTERM before SIGKILL. */
 export const STOP_GRACE_MS = 10_000;
-/** `ps` reports age in whole seconds: a process born this close after the run saw its pid is still that process. */
 const BIRTH_SLACK_MS = 2_000;
-/** Every process now: ids, when it was born (from its age) and its program's name — never its arguments, which can
- * carry private provider inputs. */
 export function processCensus(now = Date.now()) {
     if (process.platform === "win32")
         return [];
     const text = execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid=,etime=,tty=,comm="], { encoding: "utf8", timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
     return parseCensus(text, now);
 }
-/** `ps -o pid=,ppid=,pgid=,etime=,tty=,comm=` rows; etime is [[dd-]hh:]mm:ss, tty `??` or `?` for none. Unreadable rows are left out. */
 export function parseCensus(text, now) {
     const rows = [];
     for (const line of text.split("\n")) {
@@ -44,7 +24,6 @@ export function parseCensus(text, now) {
     }
     return rows;
 }
-/** This process, its ancestors, pid 1 and their process groups: the live service, never stopped. */
 export function protectedProcesses(census, self = process.pid) {
     const byPid = new Map(census.map(row => [row.pid, row]));
     const pids = new Set([1, self, process.ppid]);
@@ -61,11 +40,6 @@ export function protectedProcesses(census, self = process.pid) {
     }
     return { pids, groups };
 }
-/**
- * What of a run is still running: each witnessed process that is still the same process (born no later than the run
- * saw it), and every member of each witnessed group whose leader is that same process or gone. Never anything
- * protected.
- */
 export function closeoutTargets(census, witnesses, guard) {
     const byPid = new Map(census.map(row => [row.pid, row]));
     const groups = new Set();
@@ -80,7 +54,6 @@ export function closeoutTargets(census, witnesses, guard) {
     }
     return census.filter(row => (pids.has(row.pid) || groups.has(row.pgid)) && !guard.pids.has(row.pid) && !guard.groups.has(row.pgid));
 }
-/** SIGTERM each target, wait up to the grace for them to go, then SIGKILL what is still the same process. */
 export async function stopProcesses(targets, options = {}) {
     if (targets.length === 0)
         return { stopped: [], killed: [] };
@@ -99,7 +72,6 @@ export async function stopProcesses(targets, options = {}) {
             }
         }
     };
-    // Still there: the same pid, born at the same time (a reused pid is somebody else).
     const remaining = () => {
         let rows;
         try {
@@ -122,18 +94,12 @@ export async function stopProcesses(targets, options = {}) {
         send(left, "SIGKILL");
     return { stopped: [...targets], killed: left };
 }
-/** "node (4123), serve (4130); 1 needed SIGKILL after 10 s" — for the ledger. */
 export function stoppedWords(done, graceMs = STOP_GRACE_MS) {
     const names = done.stopped.map(one => `${one.name} (${one.pid})`).join(", ");
     const groups = new Set(done.stopped.map(one => one.pgid)).size;
     const killed = done.killed.length === 0 ? "" : `; ${done.killed.length} needed SIGKILL after ${Number((graceMs / 1000).toFixed(1))} s`;
     return `${done.stopped.length} process${done.stopped.length === 1 ? "" : "es"} in ${groups} group${groups === 1 ? "" : "s"}: ${names}${killed}`;
 }
-/**
- * The worker's pass: every finished run of this host that still has a process witness open is closed out. A run
- * whose transport here still holds a live child is left to that road.
- * Returns what each run had stopped.
- */
 export async function closeOutRuns(store, clock, options = {}) {
     if (process.platform === "win32")
         return [];
@@ -178,7 +144,6 @@ export async function closeOutRuns(store, clock, options = {}) {
     store.settleQuiescentStops(clock());
     return out;
 }
-/** Which processes run from inside each of `paths` (their working directory is there): lsof on macOS, /proc on Linux. */
 export function processesIn(paths) {
     const found = new Map();
     if (paths.length === 0 || process.platform === "win32")
@@ -186,7 +151,7 @@ export function processesIn(paths) {
     const roots = paths.map(path => { let real = path; try {
         real = realpathSync(path);
     }
-    catch { /* gone */ } return { path, real }; });
+    catch { } return { path, real }; });
     const note = (pid, cwd) => {
         for (const one of roots) {
             if ([one.path, one.real].some(root => cwd === root || cwd.startsWith(root + sep)))
@@ -200,7 +165,7 @@ export function processesIn(paths) {
             try {
                 note(Number(name), readlinkSync(`/proc/${name}/cwd`));
             }
-            catch { /* gone, or not ours */ }
+            catch { }
         }
         return found;
     }
@@ -220,12 +185,6 @@ export function processesIn(paths) {
     }
     return found;
 }
-/**
- * Of the processes running from a finished checkout (`inside`), the ones Toolroll left there: each descends from a
- * process a finished run started (`roots`), or is an orphan (its parent is pid 1), or is the child of one that goes.
- * Never one with a live parent Toolroll didn't start — a deploy the lead runs from the checkout, a person's agent or
- * its tools — nor anything at a terminal or protected.
- */
 export function checkoutTargets(census, inside, roots, guard) {
     const byPid = new Map(census.map(row => [row.pid, row]));
     const fromRun = (row) => {
@@ -249,7 +208,6 @@ export function checkoutTargets(census, inside, roots, guard) {
     };
     return census.filter(left);
 }
-/** The processes finished runs on this host started that are still the same process: what a leftover may descend from. */
 function finishedRunProcesses(store, census) {
     const byPid = new Map(census.map(row => [row.pid, row]));
     const roots = new Set();
@@ -264,13 +222,7 @@ function finishedRunProcesses(store, census) {
     }
     return roots;
 }
-/** Checkouts this process already closed out since their task finished (path and when). */
 const closed = new Set();
-/**
- * Completing or cancelling a task closes out its checkout: what Toolroll left running from it (`checkoutTargets`) is
- * stopped (SIGTERM, then SIGKILL after the grace), in the ledger. `finished` lists the checkouts whose task is
- * complete or cancelled, with when it finished; each is looked at once per finish.
- */
 export async function closeOutCheckouts(store, clock, finished, options = {}) {
     const fresh = finished.filter(one => !closed.has(`${one.row.path}\u0000${one.finishedAt}`) && existsSync(one.row.path) && one.row.runner === null);
     const out = [];