toolroll 0.9.103 → 0.9.105

package/dist/flow-unattended-words.js

@@ -1,11 +1,6 @@
-/** The words a "runs on its own" grant signs (flow-unattended.ts), kept free of server imports so the flow page's
- * signing form says each limit exactly as the signature will. */
 export const dollarWords = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
-/** The most runs a day a grant may allow. */
 export const UNATTENDED_MAX_RUNS = 50;
-/** The largest per-attempt budget a grant may name: $100. */
 export const UNATTENDED_MAX_BUDGET_MICROUSD = 100_000_000;
-/** A per-attempt budget as typed ("5", "$7.50", "" for no cap), the one way the server and the flow page read it. */
 export function unattendedBudgetOf(typed) {
     const text = typed.trim().replace(/^\$/, "");
     if (text === "")
@@ -15,7 +10,6 @@ export function unattendedBudgetOf(typed) {
         return { ok: false, message: `Give the budget in dollars, up to ${dollarWords(UNATTENDED_MAX_BUDGET_MICROUSD)}, or leave it empty.` };
     return { ok: true, value: Math.round(value * 1_000_000) };
 }
-/** Runs a day as typed ("3", "" for no limit), the one way the server and the flow page read it. */
 export function unattendedRunsOf(typed) {
     const text = typed.trim();
     if (text === "")
@@ -25,11 +19,8 @@ export function unattendedRunsOf(typed) {
         return { ok: false, message: `Give runs a day as 1 to ${UNATTENDED_MAX_RUNS}, or leave it empty.` };
     return { ok: true, value };
 }
-/** "Oct 19": the end's day, where space is short (the exact time goes beside it, on hover). */
 export const untilDayWords = (iso) => new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso));
-/** "Oct 19, 14:05 UTC": the expiry as every surface says it. */
 export const untilWords = (iso) => `${new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso))}, ${iso.slice(11, 16)} UTC`;
-/** Who approves, with what permissions and against which criteria. */
 export function unattendedHeadWords(owner, acceptance) {
     return [
         `Cards this flow's own schedule adds file their work approved by ${owner}, without waiting in Needs you.`,
@@ -38,7 +29,6 @@ export function unattendedHeadWords(owner, acceptance) {
         `Research is checked against: “${acceptance.report.map(one => one.statement).join("”; “")}”.`,
     ];
 }
-/** "daily at 09:00" from a stored schedule ("daily:09:00@Europe/London"), kept here so every surface says it alike. */
 export function scheduleWords(stored) {
     const days = ["Sundays", "Mondays", "Tuesdays", "Wednesdays", "Thursdays", "Fridays", "Saturdays"];
     const [when, zone] = stored.split("@");
@@ -54,16 +44,13 @@ export function scheduleWords(stored) {
         return `${days[Number(parts[1])] ?? "weekly"} at ${parts[2]}:${parts[3]}${tz}`;
     return stored;
 }
-/** Which schedules the grant covers, by name and time. */
 export const unattendedCoverWords = (triggers) => `It covers ${triggers.length === 1 ? "this schedule" : "these schedules"} when ${triggers.length === 1 ? "it fires" : "they fire"} on time: ${triggers.map(one => one.words).join("; ")}. Run now, and schedules added or changed later, wait for you.`;
-/** The optional limits. */
 export function unattendedLimitWords(budgetMicrousd, dailyRunCap) {
     return [
         budgetMicrousd === null ? "No dollar cap per attempt." : `Each attempt may spend up to ${dollarWords(budgetMicrousd)}.`,
         dailyRunCap === null ? "No daily limit on runs." : `At most ${dailyRunCap} run${dailyRunCap === 1 ? "" : "s"} a day (UTC); after that, cards wait for you.`,
     ];
 }
-/** What it never covers, and what ends it. */
 export const UNATTENDED_RULE_WORDS = [
     "Plans are approved only when they keep the filed request exactly. Questions and plan changes still wait for you.",
     "Never covered: Person decides steps, pull request merges, publish or deploy scripts, and anything it sends. Cards people add and other triggers wait as usual.",

package/dist/flow-unattended.js

@@ -1,29 +1,3 @@
-/**
- * "Runs on its own": a per-flow, password-signed, expiring grant that lets the
- * cards a flow's OWN SCHEDULE adds file work that is approved without a person
- * reading each one. The flow's owner signs it (the mode ceremony and expiry
- * rules: at most MODE_MAX_DAYS); any approver revokes it with one click.
- *
- * What it covers is deliberately narrow: the build and research tasks those
- * cards file, sealed with safe permissions, the flow's fixed acceptance
- * criteria and the signed budget and daily run cap; their plans approve only
- * when unchanged (plan-auto.ts). Everything outward stays a person's: Person
- * decides zones, pull request merges, publish and deploy scripts, and sends.
- * Protected projects and paths are never covered. The grant names the very
- * schedules it covers (each one's settings digested into the signature), and
- * only their on-time firings count: Run now, a card a person moved, a schedule
- * added, changed, paused or removed, editing the flow, changing its owner, the
- * owner losing access and protecting the project all end or fall outside it. A script schedule also pins the script's
- * code (its version and content digest), the bytes of any project file it runs and, for a Node file, of every project
- * file it statically imports (the module graph Node resolves from it; an import that doesn't resolve can't be signed).
- * Imports computed at run time aren't knowable and are outside the claim. Saving the script ends the grant, and a file
- * that changed or can't be read ends it after asynchronous refresh, when the next card is sealed or its work is authorized. Each on-time firing
- * pins the code just before and just after it runs and records what it ran: its cards are covered only when that was
- * the code signed, so swapping a file for one run and restoring it before filing leaves the cards to a person.
- *
- * This module owns the terms, digest, words and transactions; the flow engine
- * asks for coverage inside its filing transaction, and plan-auto.ts seals.
- */
 import { inReadOnlyRequest } from "./read-only-request.js";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -35,7 +9,6 @@ import { dollarWords as dollars, scheduleWords, unattendedBudgetOf, unattendedRu
 import { MODE_MAX_DAYS } from "./modes.js";
 import { accountReachesSql } from "./project-access.js";
 import { canonicalJson } from "./canonical-json.js";
-/** Grant history, run reservations and the last prepared script snapshots shared by UI/worker processes. Additive only. */
 export const FLOW_UNATTENDED_SCHEMA = `
 CREATE TABLE IF NOT EXISTS flow_script_provenance (
   repo TEXT NOT NULL, name TEXT NOT NULL, snapshot TEXT, PRIMARY KEY (repo, name)
@@ -65,15 +38,12 @@ CREATE TABLE IF NOT EXISTS flow_unattended_run (
 );
 CREATE INDEX IF NOT EXISTS flow_unattended_run_day ON flow_unattended_run (grant_id, day);
 `;
-/** The fixed acceptance criteria a flow's work zones file with: the same for every card, so a grant can freeze them. */
 export const FLOW_ACCEPTANCE = {
     report: [{ id: "c1", statement: "The report answers the request, citing where in the repository each point comes from", how: null, evidence: ["manual-review"] }],
     task: [{ id: "c1", statement: "The requested change is made and the project's existing checks still pass", how: null, evidence: ["manual-review"] }],
 };
-/** The limits a grant may name, and their one parser, live with its words (the flow page validates with them too). */
 export { UNATTENDED_MAX_BUDGET_MICROUSD, UNATTENDED_MAX_RUNS } from "./flow-unattended-words.js";
 export const unattendedTermsJson = (terms) => canonicalJson(terms);
-/** sha256 over a domain-separated canonical encoding, 32 hex like the mode digest. */
 export function unattendedDigestOf(terms) {
     return createHash("sha256").update(`standing-orders:flow-unattended:${unattendedTermsJson(terms)}`, "utf8").digest("hex").slice(0, 32);
 }
@@ -93,7 +63,6 @@ function criteria(value) {
     return out;
 }
 const hex32 = (v) => typeof v === "string" && /^[0-9a-f]{32}$/.test(v);
-/** Earlier script shapes become inactive at upgrade: the owner must sign the stricter provenance terms again. */
 function signedScript(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -126,7 +95,6 @@ function coveredTriggers(value) {
         if (!(typeof t["id"] === "number" && Number.isSafeInteger(t["id"]) && t["id"] > 0) || !(t["kind"] === "schedule" || t["kind"] === "script" || t["kind"] === "plane-review") ||
             !hex32(t["digest"]) || typeof t["words"] !== "string")
             return null;
-        // A script schedule signed without its code (or anything else carrying one) is unreadable, never a guess.
         if (t["kind"] !== "script") {
             if (t["script"] !== undefined)
                 return null;
@@ -140,7 +108,6 @@ function coveredTriggers(value) {
     }
     return out;
 }
-/** Strict rehydration: anything unexpected is null, never a guess. */
 export function unattendedTermsFromJson(json) {
     if (json === null)
         return null;
@@ -168,17 +135,11 @@ export function unattendedTermsFromJson(json) {
         perAttemptBudgetMicrousd: budget, dailyRunCap: cap, absoluteExpiry: t["absoluteExpiry"] };
 }
 export { untilWords };
-/** Every term in words: what the ceremony shows and the password signs. */
 export function unattendedWords(terms) {
     return [...unattendedHeadWords(terms.owner, terms.acceptance), unattendedCoverWords(terms.triggers), ...unattendedLimitWords(terms.perAttemptBudgetMicrousd, terms.dailyRunCap), ...UNATTENDED_RULE_WORDS, unattendedEndWords(terms.absoluteExpiry)];
 }
-/** SQL: whether neither project's approval rules protect anything (flow work names no paths, so any protected path
- * could be reached). An unreadable path list counts as protected. */
 const unprotectedSql = (repos) => `NOT EXISTS (SELECT 1 FROM approval_policy ug_rules WHERE ug_rules.repo IN (${repos})
                  AND (ug_rules.protect_project = 1 OR NOT json_valid(ug_rules.protected_paths) OR json_array_length(ug_rules.protected_paths) > 0))`;
-/** SQL: whether the grant whose digest is `digest` still stands at `now` for work in `repo` — live, unexpired, its
- * signer an active approver who can still reach the flow's project and this one, still the owner of the very flow
- * revision signed, and neither project protected. Shared by every dispatch belt. */
 export const grantStandsSql = (digest, now, repo) => `EXISTS (SELECT 1 FROM flow_unattended_grant ug
             JOIN approver ug_signer ON ug_signer.name = ug.signed_by
             JOIN flow ug_flow ON ug_flow.id = ug.flow
@@ -193,7 +154,6 @@ function readGrant(row) {
         return null;
     return { id: Number(row["id"]), flow: Number(row["flow"]), repo: String(row["repo"]), terms, digest: String(row["digest"]), signedBy: String(row["signed_by"]), signedAt: String(row["signed_at"]), absoluteExpiry: String(row["absolute_expiry"]) };
 }
-/** Close a grant: the row, its ledger line, and the undispatched work it sealed or pre-authorized falls back to a person. */
 function closeGrant(store, row, by, reason, now) {
     store.handle.prepare("UPDATE flow_unattended_grant SET revoked_at = ?, revoked_by = ?, revoke_reason = ? WHERE id = ? AND revoked_at IS NULL").run(now.toISOString(), by, reason, Number(row["id"]));
     if (reason !== "renewed") {
@@ -202,43 +162,30 @@ function closeGrant(store, row, by, reason, now) {
     }
     store.withdrawGrantApprovals(String(row["digest"]), now);
 }
-/**
- * The one road for what ends grants from outside this module (store.ts calls it): a flow's schedule added, paused,
- * resumed or removed; a project's approval rules protecting work; an account's access or standing changing. Every live
- * grant the filter names ends now, durably, with its ledger line, and its queued approvals are withdrawn. Call inside
- * the mutation's transaction. Returns how many ended.
- */
 export function endUnattendedGrants(store, filter, by, reason, now) {
     const rows = "flow" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE flow = ? AND revoked_at IS NULL").all(filter.flow)
         : "signer" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE signed_by = ? AND revoked_at IS NULL").all(filter.signer)
-            // A script saved or removed: the grants in its project that signed a schedule running it, or whose flow has a step
-            // that runs it (pre-authorized work would run the new code unseen); an unreadable one too, to be safe.
             : "script" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE repo = ? AND revoked_at IS NULL").all(filter.script.repo).filter(row => {
                 const terms = unattendedTermsFromJson(String(row["terms_json"]));
                 return terms === null || terms.triggers.some(one => one.script?.name === filter.script.name) || flowStepRunsScript(store, Number(row["flow"]), filter.script.name);
             })
-                // A project's rules reach the flows in it and the flows whose build zones work in it.
                 : store.handle.prepare(`SELECT ug.* FROM flow_unattended_grant ug JOIN flow f ON f.id = ug.flow WHERE ug.revoked_at IS NULL
         AND (ug.repo = ? OR (json_valid(f.definition_json) AND EXISTS (SELECT 1 FROM json_each(f.definition_json, '$.stages') s WHERE json_extract(s.value, '$.repo') = ?)))`).all(filter.repo, filter.repo);
     for (const row of rows)
         closeGrant(store, row, by, reason, now);
     return rows.length;
 }
-/** The live grant for a flow, or null. One past its expiry is closed here, durably (like activeMode). A grant whose
- * signer is no longer an active approver, or whose flow moved on, covers nothing. */
 export function activeUnattendedGrant(store, flowId, now) {
     const row = store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE flow = ? AND revoked_at IS NULL").get(flowId);
     if (row === undefined)
         return null;
     if (Date.parse(String(row["absolute_expiry"])) <= now.getTime()) {
-        // A page visit only reads (docs/plans/get-side-effects.md): the background pass or the next path that acts closes it.
         if (!inReadOnlyRequest())
             store.transact(() => closeGrant(store, row, "the-clock", "expired", now));
         return null;
     }
     return readGrant(row);
 }
-/** Close every grant past its expiry (the console's background pass). Returns how many ended. */
 export function closeExpiredUnattendedGrants(store, now) {
     const rows = store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE revoked_at IS NULL").all()
         .filter(row => Date.parse(String(row["absolute_expiry"])) <= now.getTime());
@@ -246,7 +193,6 @@ export function closeExpiredUnattendedGrants(store, now) {
         store.transact(() => closeGrant(store, row, "the-clock", "expired", now));
     return rows.length;
 }
-/** Why the grant can't cover this flow right now (the same checks signing makes), or null. */
 function coverageProblem(store, flow, owner, workRepos) {
     if (flow.state !== "active")
         return "This flow is archived.";
@@ -259,13 +205,11 @@ function coverageProblem(store, flow, owner, workRepos) {
         if (!store.accountCanAccess(owner, repo))
             return `${owner} can't approve work in ${repo}.`;
         const rules = store.approvalRules(repo);
-        // Flow work declares no paths, so any protected path could be reached: protected work is always a person's.
         if (isProtectedWork(rules, []))
             return rules.protectProject ? "This project is protected: a person approves its work." : "This project protects some paths, and flow work could reach them: a person approves it.";
     }
     return null;
 }
-/** The projects a flow's work zones file in (a build zone may name another). */
 export function workReposOf(flow) {
     try {
         const drawn = JSON.parse(flow.definitionJson);
@@ -275,7 +219,6 @@ export function workReposOf(flow) {
         return [];
     }
 }
-/** sha256 over a trigger's identity and canonical settings: what a grant freezes for each schedule it covers. */
 export function triggerDigestOf(trigger) {
     let config;
     try {
@@ -287,14 +230,10 @@ export function triggerDigestOf(trigger) {
     return createHash("sha256").update(`standing-orders:flow-unattended-trigger:${trigger.id}:${trigger.flow}:${trigger.kind}:${canonicalJson(config)}`, "utf8").digest("hex").slice(0, 32);
 }
 const bytesDigest = (bytes) => createHash("sha256").update("standing-orders:flow-unattended-file:").update(bytes).digest("hex").slice(0, 32);
-/** The most project files one script's code may span; a bigger module graph can't be signed. */
 const MAX_SCRIPT_FILES = 500;
-/** Files whose static imports are read: JavaScript and TypeScript sources. Others (JSON, addons) are pinned as bytes. */
 const SOURCE_FILE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
 let compiler = null;
 const typescript = () => compiler ??= createRequire(import.meta.url)("typescript-parser");
-/** Resolves [specifier, importing file] pairs as the Node that runs scripts does, without loading either: as `import`
- * and as `require` (a .js file's mode can depend on its syntax). Each answer is a path, "builtin", or null. */
 const NODE_RESOLVER = `import { createRequire, isBuiltin } from "node:module";
 import { readFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -353,7 +292,6 @@ function lastScript(store, repo, name) {
     }
 }
 const inside = (base, full) => { const path = relative(base, full); return path !== "" && path !== ".." && !path.startsWith("../") && !isAbsolute(path) ? path : null; };
-/** Resolve only literal dependencies, without evaluating the script. Computed imports remain outside the claim. */
 async function nodeModuleGraphOf(base, entry, fresh) {
     const cached = graphCache.get(entry);
     if (!fresh && cached && (await Promise.all([...cached.watched].map(async ([path, identity]) => await pathIdentity(path) === identity))).every(Boolean))
@@ -411,7 +349,6 @@ async function nodeModuleGraphOf(base, entry, fresh) {
         const next = new Set();
         for (const [index, { esm, cjs }] of answers.entries()) {
             const [spec, from] = pairs[index];
-            // Node may have already canonicalized a relative symlink. Check its lexical target too.
             if (spec.startsWith(".")) {
                 const lexical = resolve(dirname(from), spec);
                 await watchResolution(lexical);
@@ -419,7 +356,7 @@ async function nodeModuleGraphOf(base, entry, fresh) {
                     if (inside(base, lexical) !== null && inside(base, await realpath(lexical)) === null)
                         return null;
                 }
-                catch { /* resolver below decides */ }
+                catch { }
             }
             let found = false;
             for (const one of new Set([esm, cjs])) {
@@ -440,7 +377,6 @@ async function nodeModuleGraphOf(base, entry, fresh) {
                     continue;
                 }
                 found = true;
-                // A project dependency that escapes through a symlink is unsafe, never silently omitted.
                 if (inside(base, full) === null) {
                     if (inside(base, one) !== null)
                         return null;
@@ -463,7 +399,6 @@ async function nodeModuleGraphOf(base, entry, fresh) {
         graphCache.delete(graphCache.keys().next().value);
     return files;
 }
-/** Asynchronous preparation, never called from filing transactions or page rendering. */
 export async function scriptProvenanceOf(store, repo, name, fresh = true) {
     const script = store.flowScript(repo, name);
     let result = null;
@@ -499,18 +434,15 @@ export async function prepareUnattendedCandidates(store, flowId) {
             if (typeof config.script === "string")
                 await scriptProvenanceOf(store, flow.repo, config.script, false);
         }
-        catch { /* invalid schedule isn't offered */ }
+        catch { }
     }
 }
-/** What an on-time script firing ran, as its firing records it: a digest of the code pinned just before and just after
- * the run, when both were the same and were the script row that ran; else null (it can't have run the code signed). */
 export function scriptRanDigestOf(before, after, ran) {
     if (before === null || after === null || canonicalJson(before) !== canonicalJson(after) || before.version !== ran.version || before.digest !== ran.digest)
         return null;
     return ranDigestOf(before);
 }
 const ranDigestOf = (script) => createHash("sha256").update(`standing-orders:flow-unattended-script-ran:${canonicalJson(script)}`, "utf8").digest("hex").slice(0, 32);
-/** Whether `flowId`'s live grant signed `triggerId`'s script: only then does a firing pin the code it runs. */
 export function grantSignsScriptOf(store, flowId, triggerId, now) {
     const trigger = store.getFlowTrigger(triggerId), flow = store.getFlow(flowId);
     const grant = activeUnattendedGrant(store, flowId, now);
@@ -518,12 +450,10 @@ export function grantSignsScriptOf(store, flowId, triggerId, now) {
         flow.revision === grant.terms.flowRevision && coverageProblem(store, flow, grant.signedBy, [flow.repo]) === null &&
         grant.terms.triggers.some(one => one.id === triggerId && one.kind === "script" && one.digest === triggerDigestOf(trigger));
 }
-/** Whether each script schedule the grant signed would still run the very code signed. */
 function scriptsUnchanged(store, terms) {
     return terms.triggers.every(one => one.kind !== "script" ||
         (one.script !== undefined && canonicalJson(lastScript(store, terms.repo, one.script.name)) === canonicalJson(one.script)));
 }
-/** A grant whose script or project file drifted ends now, durably, and its queued approvals are withdrawn. True when it did. */
 function endIfScriptsChanged(store, grant, now) {
     if (scriptsUnchanged(store, grant.terms))
         return false;
@@ -534,12 +464,6 @@ function endIfScriptsChanged(store, grant, now) {
     });
     return true;
 }
-/**
- * The flow's active schedules a grant could cover. A plain schedule makes its own card from its own words, so it is
- * covered by default. A script's items and a plane review's problems are outside content (issues, mail, what a run
- * saw), so they are covered only when the owner picks them. A standing order files under its own signed terms, and a
- * paused or unreadable schedule, or a script whose code can't be read safely, is never offered.
- */
 export function unattendedCandidates(store, flowId) {
     const out = [];
     const flowRepo = store.getFlow(flowId)?.repo;
@@ -564,7 +488,6 @@ export function unattendedCandidates(store, flowId) {
         else if (config["kind"] !== "schedule")
             continue;
         else if (typeof config["script"] === "string") {
-            // Its code is signed with it; one whose code can't be read safely is never offered.
             const script = lastScript(store, flowRepo, config["script"]);
             if (script !== null)
                 out.push({ id: trigger.id, kind: "script", digest, words: `the ${config["script"]} script, ${when}`, script, optional: "Its cards come from what the script prints, which can be outside text, and wait for you unless it ran the code you signed. Files it loads by a computed name aren't checked." });
@@ -574,7 +497,6 @@ export function unattendedCandidates(store, flowId) {
     }
     return out;
 }
-/** The flow's active script schedules not offered because their code can't be read safely. */
 function unreadableScriptSchedules(store, flowId) {
     const offered = new Set(unattendedCandidates(store, flowId).map(one => one.id));
     return store.flowTriggers(flowId).filter(one => {
@@ -589,16 +511,13 @@ function unreadableScriptSchedules(store, flowId) {
     }).map(one => one.id);
 }
 const UNREADABLE_SCRIPT = "can't be read safely (it's missing, waiting for approval, or a project file it runs or imports can't be read)";
-/** A digest of the schedules the page offered, so a signature never covers one the person didn't read. */
 export const candidatesDigestOf = (candidates) => createHash("sha256").update(`standing-orders:flow-unattended-candidates:${canonicalJson(candidates)}`, "utf8").digest("hex").slice(0, 32);
-/** Why `signer` can't let this flow run on its own, or null: what the flow page shows instead of the form. */
 export function unattendedSignProblem(store, flow, signer) {
     if (unattendedCandidates(store, flow.id).length === 0)
         return unreadableScriptSchedules(store, flow.id).length > 0
             ? `This flow's script ${UNREADABLE_SCRIPT}, so nothing would run on its own.` : "This flow has no schedule, so nothing would run on its own.";
     return coverageProblem(store, flow, signer, workReposOf(flow));
 }
-/** Read what a person typed: whole days 1–MODE_MAX_DAYS, an optional dollar budget, an optional runs-a-day cap. */
 export function parseUnattendedAsk(input) {
     const text = (v) => typeof v === "string" ? v.trim() : typeof v === "number" ? String(v) : "";
     const days = Number(text(input.days));
@@ -617,15 +536,11 @@ export function parseUnattendedAsk(input) {
         return { ok: false, message: "Name the schedules to include by their trigger ids, like 12,14." };
     return { ok: true, ask: { days, budgetMicrousd, dailyRunCap, ...(include.length === 0 ? {} : { include: [...new Set(include)] }) } };
 }
-/** The exact terms a signature would cover now, for these schedules. */
 export function unattendedTermsFor(flow, owner, ask, triggers, now) {
     return { flow: flow.id, flowRevision: flow.revision, repo: flow.repo, owner, triggers: triggers.map(({ id, kind, digest, words, script }) => ({ id, kind, digest, words, ...(kind === "script" && script !== undefined ? { script: structuredClone(script) } : {}) })), permissions: "safe",
         acceptance: structuredClone(FLOW_ACCEPTANCE), perAttemptBudgetMicrousd: ask.budgetMicrousd, dailyRunCap: ask.dailyRunCap,
         absoluteExpiry: new Date(now.getTime() + ask.days * 24 * 60 * 60_000).toISOString() };
 }
-/** Sign (or renew) the grant. The caller has already checked the signer's password; every predicate is proved again
- * here against the flow as it now stands: files asynchronously first, then database facts inside the transaction. `sawRevision` and `sawSchedules` (candidatesDigestOf),
- * when given, are the flow and the schedules the person read. Renewing ends the old grant and withdraws what it sealed. */
 export async function signUnattended(store, input, now) {
     const revision = store.getFlow(input.flow)?.revision;
     const schedules = canonicalJson(store.flowTriggers(input.flow));
@@ -633,12 +548,6 @@ export async function signUnattended(store, input, now) {
     const prepared = candidatesDigestOf(unattendedCandidates(store, input.flow));
     return sealUnattended(store, input, now, { revision, schedules, prepared });
 }
-/**
- * The signature itself, in one transaction. `before` is what signUnattended read around its file pass. Chat's door is
- * synchronous, so it signs without one, over the script snapshots the worker's pass keeps (prepareUnattendedCandidates)
- * and the schedules its card showed (`sawSchedules`). A snapshot older than the files fails closed: a firing runs a
- * signed script only if it is still the very code signed.
- */
 export function sealUnattended(store, input, now, before) {
     return store.transact(() => {
         const flow = store.getFlow(input.flow);
@@ -675,7 +584,6 @@ export function sealUnattended(store, input, now, before) {
         return { ok: true, grant: { id, flow: flow.id, repo: flow.repo, terms, digest, signedBy: input.signer, signedAt: now.toISOString(), absoluteExpiry: terms.absoluteExpiry } };
     });
 }
-/** One click for any approver on the project: lowering authority needs no password. False when there was none. */
 export function revokeUnattended(store, flowId, by, now) {
     return store.transact(() => {
         const row = store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE flow = ? AND revoked_at IS NULL").get(flowId);
@@ -686,13 +594,6 @@ export function revokeUnattended(store, flowId, by, now) {
         return !expired;
     });
 }
-/**
- * Whether a card came from one of the schedules this grant signed for, fired on time after it was signed: the firing
- * names the card and was the clock's (never Run now), its trigger is still active with the very settings signed, and no
- * person has moved the card or sent it back since. Anything else is a person's card, or one the grant never read.
- * A script schedule's firing must have run the very code signed (scriptRanDigestOf), and it must still be that code;
- * when it isn't, the grant ends here (unattendedCoverageFor).
- */
 export function cardFromSignedSchedule(store, grant, cardId, requireScript = true) {
     const fired = store.handle.prepare(`SELECT t.id, t.flow, t.kind, t.state, t.config_json, e.at, e.ran_script FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger
     WHERE e.card = ? AND t.flow = ? AND e.on_time = 1`).all(cardId, grant.flow);
@@ -704,18 +605,15 @@ export function cardFromSignedSchedule(store, grant, cardId, requireScript = tru
     return store.handle.prepare(`SELECT 1 AS hit FROM flow_event WHERE card = ? AND ((outcome = 'moved' AND actor <> 'flow') OR outcome = 'sent-back') LIMIT 1`).get(cardId) === undefined;
 }
 const utcDay = (now) => now.toISOString().slice(0, 10);
-/** How many runs a grant has filed on `now`'s UTC day. */
 export function unattendedRunsToday(store, grantId, now) {
     return Number(store.handle.prepare("SELECT COUNT(*) AS n FROM flow_unattended_run WHERE grant_id = ? AND day = ?").get(grantId, utcDay(now))?.["n"] ?? 0);
 }
-/** Whether the grant covers this card's next filing (in `repo`) now; call inside the filing transaction. */
 export function unattendedCoverageFor(store, flow, card, repo, now) {
     const grant = activeUnattendedGrant(store, flow.id, now);
     if (grant === null || grant.terms.flow !== flow.id || grant.terms.flowRevision !== flow.revision || grant.terms.repo !== flow.repo || grant.terms.owner !== grant.signedBy)
         return null;
     if (coverageProblem(store, flow, grant.signedBy, [repo]) !== null)
         return null;
-    // A script that drifted ends the grant whichever card is filing; one restored since a firing leaves just that card out.
     if (!cardFromSignedSchedule(store, grant, card.id, false))
         return null;
     if (endIfScriptsChanged(store, grant, now))
@@ -726,21 +624,15 @@ export function unattendedCoverageFor(store, flow, card, repo, now) {
         return null;
     return grant;
 }
-/** Count one run against the grant's day, in one statement that admits it only under the cap (so two filings racing
- * on two connections can't both take the last run). False when the day is full; then nothing is sealed. */
 export function reserveUnattendedRun(store, grant, taskId, now) {
     const { changes } = store.handle.prepare(`INSERT OR IGNORE INTO flow_unattended_run (grant_id, day, task_id, at)
     SELECT ?, ?, ?, ? WHERE ? IS NULL OR (SELECT COUNT(*) FROM flow_unattended_run WHERE grant_id = ? AND day = ?) < ?`)
         .run(grant.id, utcDay(now), taskId, now.toISOString(), grant.terms.dailyRunCap, grant.id, utcDay(now), grant.terms.dailyRunCap);
     return Number(changes) === 1;
 }
-/** Give back a run reserved for a filing that then couldn't be sealed. */
 export function releaseUnattendedRun(store, grant, taskId) {
     store.handle.prepare("DELETE FROM flow_unattended_run WHERE grant_id = ? AND task_id = ?").run(grant.id, taskId);
 }
-/** The grant that sealed (or pre-authorized) a task still stands for it: the same live digest, the flow unchanged and
- * still owned by the signer, the signer able to approve in the task's project, its scripts' code unchanged (else it
- * ends here), and the work not protected. */
 export function unattendedGrantStands(store, digest, signer, taskRepo, touches, now) {
     const row = store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE digest = ? AND revoked_at IS NULL").get(digest);
     if (row === undefined || taskRepo === null)
@@ -757,7 +649,6 @@ export function unattendedGrantStands(store, digest, signer, taskRepo, touches,
 }
 export function unattendedViewOf(store, flow, viewer, now) {
     const grant = activeUnattendedGrant(store, flow.id, now);
-    // A grant whose flow moved on covers nothing: say so by not showing it as running.
     const live = grant !== null && grant.terms.flowRevision === flow.revision && grant.signedBy === flow.owner ? grant : null;
     const problem = viewer.approver ? unattendedSignProblem(store, flow, viewer.name) : "Only an approver can change this.";
     const candidates = unattendedCandidates(store, flow.id);
@@ -774,7 +665,6 @@ export function unattendedViewOf(store, flow, viewer, now) {
         ended: live === null ? unattendedEndedOf(store, flow.id, now) : null,
     };
 }
-/** Why the flow's latest grant ended early, in words, when a change ended it while it would still have run. */
 const ENDED_WORDS = {
     "flow changed": "the flow changed", "script changed": "a script it runs changed", "schedule changed": "a schedule changed",
     "project protected": "the project's approval rules changed", "access changed": "its signer's access changed",
@@ -786,8 +676,6 @@ function unattendedEndedOf(store, flowId, now) {
     const why = ENDED_WORDS[String(row["revoke_reason"])];
     return why === undefined || Date.parse(String(row["absolute_expiry"])) <= now.getTime() ? null : { why, at: String(row["revoked_at"]) };
 }
-/** Whether one of the flow's "Run a script" steps runs this script. A drawing that isn't readable and well formed counts,
- * to be safe. */
 function flowStepRunsScript(store, flowId, name) {
     const flow = store.getFlow(flowId);
     if (flow === null)
@@ -799,7 +687,6 @@ function flowStepRunsScript(store, flowId, name) {
     catch {
         return true;
     }
-    // Anything but a well-formed drawing (an object whose stages are a list of objects) fails closed: the grant ends.
     const stages = drawn !== null && typeof drawn === "object" && !Array.isArray(drawn) ? drawn.stages : undefined;
     if (!Array.isArray(stages) || !stages.every(stage => stage !== null && typeof stage === "object" && !Array.isArray(stage)))
         return true;