toolroll 0.9.104 → 0.9.105

package/dist/chat-voice.js

@@ -1,27 +1,13 @@
-/** How chat sounds: a teammate talking. One or two short sentences, outcome
- * first, plain words, one action at most. Every chat (Telegram, Slack,
- * Discord, Teams) takes its titles and its finished-work lines from here, so a
- * task id, a "— revision" suffix or a person's own act never reaches a chat.
- * The console keeps every exact name and fact. */
 import { leadOnIt } from "./task-status.js";
 import { publicChatText as phoneText } from "./chat-display.js";
-/** The bot's display name in every chat app. */
 export const BOT_NAME = "Toolroll";
-/** Updates for one person landing within this window become one message, edited in place as it grows. */
 export const BATCH_MS = 2 * 60_000;
 export const SHORT_TITLE_MAX = 60;
-/** A token that could be an id: letters and digits joined by `-` or `_`, or with a digit in it (`release-099b`,
- * `t42`). Words such as `node-20` and `utf-8` look the same, so a token goes only when it names a real task. */
 const ID_SHAPED = /\(?(?<![\p{L}\p{N}._/-])[\p{L}\p{N}]+(?:[-_.][\p{L}\p{N}]+)*(?![\p{L}\p{N}_/-]|\.[\p{L}\p{N}])\)?/gu;
-/** An id that could be mistaken for nothing else (`release-099b`, `fix_tax`, `t42`). A one-word id such as `tidy`
- * is also a word, and prose keeps its words. */
 const idLike = (id) => /[-_\d]/.test(id);
 const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/** A short human summary of a task's title, at most 60 characters: no "— revision", and no task ids. Only the
- * task's own id and tokens `isTaskId` names as real tasks are dropped; `node-20` and `utf-8` stay. */
 export function shortTitle(title, taskId, isTaskId) {
     let text = phoneText(title ?? "", 400);
-    // "— revision", "- revision 2", "(revision)": a revision is the same work to a person.
     text = text.replace(/(?:(?:\s*[—–]+|\s+-+)\s*revision\b(?:\s*#?\d+)?|\s*[([]\s*revision(?:\s*#?\d+)?\s*[)\]])/giu, "");
     text = text.replace(ID_SHAPED, token => {
         const bare = token.replace(/^\(|\)$/g, "");
@@ -29,7 +15,6 @@ export function shortTitle(title, taskId, isTaskId) {
     });
     text = text.replace(/\(\s*\)/g, " ").replace(/\s+/g, " ").replace(/^[\s·:,;—–-]+|[\s·:,;—–-]+$/gu, "").trim();
     if (text === "") {
-        // A task filed with only its id as a title: the words, never the slug.
         const words = (taskId ?? "").replace(/[-_]+/g, " ").trim();
         return words === "" ? "A task" : shortTitle(words[0].toUpperCase() + words.slice(1));
     }
@@ -39,27 +24,21 @@ export function shortTitle(title, taskId, isTaskId) {
     const space = cut.lastIndexOf(" ");
     return `${(space > 20 ? cut.slice(0, space) : cut).replace(/[\s·:,;—–-]+$/u, "")}…`;
 }
-/** A task's title as every chat says it: short, with its own id and any other real task's id dropped. */
 export function chatTitle(store, taskId) {
     return shortTitle(store.getTask(taskId)?.title, taskId, token => token !== taskId && store.getTask(token) !== null);
 }
-/** A title inside a sentence or list: "faster tests", but "API keys" and "iOS" keep their capitals. */
 export function inSentence(summary) {
     return /^\p{Lu}\p{Ll}/u.test(summary) ? summary[0].toLowerCase() + summary.slice(1) : summary;
 }
-/** The two buttons under a result ready for a person: the real next step, then a look first. */
 export const READY_ACTIONS = { merge: "Merge", complete: "Accept", look: "Look first" };
-/** Whether this line asks for the result's next step, so it carries [Merge] or [Accept and finish] and [Look first]. */
 export function asksToFinish(fact) {
     return fact.update == null && fact.headline === "Ready for review" && !fact.report;
 }
-/** One update, said plainly: what happened, then what happens next. The lead says "I" for what it did. */
 export function finishedLine(fact) {
     if (fact.update != null)
         return fact.update.words;
     const name = fact.summary, lower = inSentence(fact.summary);
     const ready = fact.lead === true ? `I finished ${lower}` : `${name} is ready`;
-    // What waited on the person and the lead has taken on (Needs you reads Waiting then).
     if (fact.leadOnIt === true && (fact.headline === "Needs you" || fact.headline === "Waiting" || fact.headline === "Stopped"))
         return `${name}: ${leadOnIt(fact.leadName)}`;
     switch (fact.headline) {
@@ -93,7 +72,6 @@ export function finishedLine(fact) {
             return `${name}: ${fact.headline.toLowerCase()}.`;
     }
 }
-/** One task in a list of updates: "faster tests is ready", "cleanup failed". */
 function phraseOf(fact) {
     const name = inSentence(fact.summary);
     if (fact.update != null)
@@ -106,8 +84,6 @@ function phraseOf(fact) {
         default: return `${name}: ${fact.headline.toLowerCase()}`;
     }
 }
-/** Several updates in one message: "4 tasks finished: faster tests, cleanup, …" (or "3 updates: …" when not all of
- * them are finished work), then what broke and what happens next. */
 export function batchLine(facts) {
     if (facts.length === 1)
         return finishedLine(facts[0]);
@@ -115,8 +91,6 @@ export function batchLine(facts) {
     const names = finishedOnly ? facts.map(one => inSentence(one.summary)) : facts.map(phraseOf);
     const shown = names.slice(0, 3).join(", ");
     const first = `${facts.length} ${finishedOnly ? "tasks finished" : "updates"}: ${shown}${names.length > 3 ? ", …" : "."}`;
-    // What happens next: anything that broke or needs a decision waits for the person.
-    // What the lead is on waits for nobody.
     const failed = facts.filter(one => one.headline === "Failed" && one.leadOnIt !== true);
     const needs = facts.filter(one => one.headline === "Needs you" && one.leadOnIt !== true).length;
     const broke = failed.length !== 1 ? `${failed.length} failed`
@@ -130,13 +104,7 @@ export function batchLine(facts) {
     const said = waits.join(", and ");
     return `${first}\n${said[0].toUpperCase()}${said.slice(1)}; ${failed.length + needs === 1 ? "it waits" : "they wait"} for you.`;
 }
-/** The old product name a bot may still wear from before the rename. */
 const OLD_NAME = /standing\s*-?\s*orders/i;
-/**
- * Name the Telegram bot Toolroll. On pairing it always becomes Toolroll; on upgrade only a bot still called
- * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
- * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
- */
 export async function nameTelegramBot(transport, when, signal) {
     try {
         const current = await transport("getMyName", {}, signal);
@@ -155,9 +123,6 @@ export async function nameTelegramBot(transport, when, signal) {
         return false;
     }
 }
-/** The last word on any pushed chat text: a task's own id (bare or in brackets), a "— revision" suffix and a
- * "Replaced by <id>" never reach a chat, whatever words the fact was recorded with. A bare id reads as the
- * task's short title when one is given, else "this task". */
 export function chatText(text, tasks = []) {
     let out = text.replace(/(?:(?:[ \t]*[—–]+|[ \t]+-+)[ \t]*revision\b(?:[ \t]*#?\d+)?|[ \t]*[([][ \t]*revision(?:[ \t]*#?\d+)?[ \t]*[)\]])/giu, "");
     out = out.replace(/\bReplaced by (?!a newer task)[^\s.,;:!?)]+/gu, "Replaced by a newer task");
@@ -170,8 +135,6 @@ export function chatText(text, tasks = []) {
     }
     return out;
 }
-/** The one button a plain fact may carry: its label names where its machine-minted console path goes; nothing in
- * it comes from the fact's text. */
 export function factLinkLabel(path) {
     if (/^\/review\?result=[^&]+&run=\d+&tab=checks$/.test(path))
         return "Inspect result";
@@ -185,7 +148,6 @@ export function factLinkLabel(path) {
         return "Open decision";
     return "Open console";
 }
-/** Whether the words already name this title as a whole phrase (so it need not be said twice). */
 export function mentions(text, title) {
     return new RegExp(`(?<![\\p{L}\\p{N}_-])${escape(title)}(?![\\p{L}\\p{N}_-])`, "u").test(text);
 }

package/dist/chat-warmth.js

@@ -1,7 +1,5 @@
 export const WARM_EMOJI = "👍";
-/** Telegram and Teams show typing for about five seconds, Discord for ten: refreshed inside the shorter window. */
 export const TYPING_REFRESH_MS = 4_000;
-/** The turn's progress listener: on the first tool step, react once and keep typing shown until `stop`. */
 export function warmTurn(hooks, options = {}) {
     let started = false;
     let stopped = false;
@@ -12,7 +10,7 @@ export function warmTurn(hooks, options = {}) {
         try {
             void call().catch(() => undefined);
         }
-        catch { /* skipped silently */ }
+        catch { }
     };
     return {
         onProgress: event => {

package/dist/check-access.js

@@ -1,41 +1,25 @@
-/**
- * Check access (v132, docs/plans/check-access.md): how far a project's setup and check commands reach beyond the
- * plane's check fence. `sandboxed` (the default) is the fence as it is; `sign-ins` also reads the exact sign-in files
- * of Claude, Codex and gh, under the project's network fence; `unsandboxed` runs them with no OS fence, trusted by the
- * whole instance, for a project whose checks must create sandboxes themselves (Toolroll's own). Widening is an instance
- * operator's act with a password typed now; any approver for the project may narrow it back.
- */
 import { PROVIDER_HOSTS } from "./egress.js";
 export const CHECK_ACCESS_LEVELS = ["sandboxed", "sign-ins", "unsandboxed"];
 export const CHECK_ACCESS_DEFAULT = "sandboxed";
 export const isCheckAccess = (value) => typeof value === "string" && CHECK_ACCESS_LEVELS.includes(value);
-/** A stored or sealed value as a level: anything missing or unreadable is the narrowest, never a wider one. */
 export const checkAccessOf = (value) => isCheckAccess(value) ? value : CHECK_ACCESS_DEFAULT;
 const RANK = { sandboxed: 0, "sign-ins": 1, unsandboxed: 2 };
 export const widerThan = (a, b) => RANK[a] > RANK[b];
-/** The narrowest of several levels (none given: the default). */
 export const narrowestAccess = (levels) => levels.reduce((low, one) => RANK[one] < RANK[low] ? one : low, levels.length === 0 ? CHECK_ACCESS_DEFAULT : "unsandboxed");
-/** The level as a person reads it, in a sentence's middle ("Checks: …"). */
 export function checkAccessWords(level) {
     return level === "sandboxed" ? "sandboxed" : level === "sign-ins" ? "sandboxed, with model and GitHub sign-ins" : "not sandboxed";
 }
-/** What each wider level means, said before anyone chooses it. */
 export const CHECK_ACCESS_WARNINGS = {
     "sign-ins": "This project's checks can read your Claude, Codex and GitHub sign-ins, even where the project hides your home folder's files from builds. Its tests could use or send those credentials anywhere its network setting allows. Only choose this for projects you trust.",
     unsandboxed: "This project's checks get your full access to this machine and to Toolroll itself, including its database and every sign-in. Only for a project whose checks must create sandboxes themselves, such as Toolroll's own.",
 };
-/** The services whose sign-ins a `sign-ins` check reads: Claude's and Codex's own hosts (egress.ts), and GitHub's. */
 export const SIGN_IN_HOSTS = [...PROVIDER_HOSTS["claude"], ...PROVIDER_HOSTS["codex"], "github.com", "api.github.com"];
-/** Which of those a project's network doesn't allow (an open network allows all). The check's network is never widened
- * for them: the operator adds them, as a network change of its own. */
 export function signInHostsMissing(network) {
     if (network.mode === "open")
         return [];
     const covered = (host) => network.hosts.some(one => one === host || (one.startsWith("*.") && host.endsWith(one.slice(1))));
     return SIGN_IN_HOSTS.filter(host => !covered(host));
 }
-/** The narrower of two networks: every host both allow (a wildcard allows what it covers), local services only if both
- * do, open only if both are. A check never reaches what either its sealed network or the project's current one refuses. */
 export function narrowestNetwork(a, b) {
     const loopback = a.loopback === "any" && b.loopback === "any" ? "any" : "proxy-only";
     if (a.mode === "open" && b.mode === "open")
@@ -48,33 +32,19 @@ export function narrowestNetwork(a, b) {
     const hosts = [...new Set([...a.hosts.filter(host => covers(b.hosts, host)), ...b.hosts.filter(host => covers(a.hosts, host))])].sort();
     return { version: 1, mode: "allowlist", hosts, loopback };
 }
-/** A build's checks' own network: what its approval sealed, less its agent's provider hosts (those are the agent's, never
- * its checks'); narrower if a project host happens to be one of them. */
 export function checkNetworkOf(sealed, provider, project) {
     if (sealed.mode === "open")
         return sealed;
-    // A provider host the project itself lists (an operator added it, for its sign-ins, say) is the checks' too.
     const agent = new Set((PROVIDER_HOSTS[provider] ?? []).filter(host => !project.hosts.includes(host)));
     return { ...sealed, hosts: sealed.hosts.filter(host => !agent.has(host)) };
 }
-/** On (0.9.70, sandbox parity C10): a `sign-ins` check reads its sign-in files itself, through its sandbox, by name
- * (agent-fence.ts signInGrants). Nothing privileged reads or copies one, so the race that kept sign-ins off (a folder
- * swapped between a privileged check and its read) has nothing to race; a link planted at a sign-in name leads, inside
- * the sandbox's own view, to a denied path. Every platform with an OS fence. */
 export const SIGN_INS_READY = true;
 export const signInsAvailable = (_platform = process.platform) => SIGN_INS_READY;
-/** Why sign-ins can't be chosen here, said plainly (null: they can). */
 export const signInsUnavailableWords = (platform = process.platform) => signInsAvailable(platform) ? null
     : "Not available yet: sign-ins can't be shared with checks safely. Choose Sandboxed or Not sandboxed.";
-/** The level checks actually get on this platform: `sign-ins` where it isn't available is `sandboxed` (narrower, never
- * wider). Everything that seals, launches or stamps a check's level goes through this. */
 export const checkAccessHere = (level, platform = process.platform) => level === "sign-ins" && !signInsAvailable(platform) ? CHECK_ACCESS_DEFAULT : level;
-/** How a project's checks actually run here, as the settings page and `project check-access` say it: with no OS fence
- * on this machine and unconfined running allowed by an operator, without a sandbox whatever is saved (never said to be
- * sandboxed); otherwise the saved level as this platform can give it. */
 export function checkAccessRunsAs(level, here) {
     const runs = !here.fenced && here.unconfinedAllowed ? "unsandboxed" : checkAccessHere(level, here.platform);
     return here.localMode === true ? localModeCap(runs) : runs;
 }
-/** Easy-start C5: while local mode is on, a project's checks reach at most its sign-ins, never unsandboxed. */
 export const localModeCap = (level) => level === "unsandboxed" ? "sign-ins" : level;

package/dist/check-facts.js

@@ -1,26 +1,3 @@
-/**
- * Check facts (docs/plans/learning-loops.md, "Foundation: check facts"): what each settled check ran under and what it
- * reported, recorded at disposition, never trusted for authority. The only writer of `check_fact` and `check_result`
- * (the v149 migration aside); release-auto's learning scan (eval-hooks.ts learningWriteProblem) needs a person for
- * SQL that writes them from anywhere else. A policy path (release-auto.ts EVAL_POLICY): any change needs a person.
- *
- * - Conditions are captured when the check's command starts (captureCheckConditions, called from the builder's
- *   runVerification), held in memory and passed here: the commit's tree read through verified objects (never the
- *   checkout), the approved command's digest, the check's access, the harness digest and lockfile, and the values of
- *   every environment variable the check inherits (the setup allowlist), hashed with checkContextOf's fields as
- *   `conditions_digest`. Not re-read later.
- * - Results are tagged by source: `receipt` (the plane's own whole-check result: trusted for "the check passed or
- *   failed", nothing finer), `report` (the candidate-written report's lines), `log` (Vitest's FAIL lines in the sealed
- *   log, failures only, file level) and `learn` (the advisory learning line). Every failure is recorded; the check's
- *   blocking failure is the check's and is never changed here.
- * - Explicit execution evidence is a `report` or `learn` line naming an identity. No line is no evidence: never
- *   skipped, removed or passed.
- * - Fail closed: an unreadable tree, or conditions never captured (the command never started), records the fact row
- *   with no conditions and no results at all.
- *
- * Nothing here changes a check's outcome, a verdict, an approval or a rerun: every reader of a check's outcome reads
- * the receipt and run_check, which this module never writes.
- */
 import { createHash } from "node:crypto";
 import { failingTestsOf } from "./gate-failure.js";
 import { checkContextOf, projectGitDir, treeFactsOf } from "./check-report.js";
@@ -29,24 +6,13 @@ import { recordObservations } from "./flaky.js";
 import { considerLessonNote, markTalliesPartial, revisedFailures, tallyCheck } from "./lesson-notes.js";
 import { CHECK_REPORT_PREFIX, isExactCase, learnLineSchema, learnRequest, LEARN_MAX_BYTES, LEARN_PREFIX } from "./contracts/release-check.js";
 import { nightlyTaskRef, releaseTaskRef } from "./store.js";
-/** The sources a result can come from, and the states it can have. */
 export const CHECK_RESULT_SOURCES = Object.freeze(["receipt", "report", "log", "learn"]);
-/** The receipt's whole-check identity, and the one a failed check with nothing else named records. */
 export const WHOLE_CHECK = "check";
 export const UNEXPLAINED = "unexplained";
-/** How many result rows one check records at most (a report's own bounds are far above any real check). */
 export const MAX_RESULTS_PER_CHECK = 20_000;
-/** How old a tracked observation may be and still be asked about (docs/plans/learning-loops.md, 90-day window). */
 export const OBSERVATION_WATCH_MS = 90 * 24 * 60 * 60 * 1000;
-/** How long per-identity results are kept (docs/plans/learning-loops.md, "Per table"). */
 const RESULT_RETAIN_MS = 180 * 24 * 60 * 60 * 1000;
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
-/**
- * The conditions a check's command starts under: its commit's verified tree facts, the approved command's digest, its
- * access, and the values of `envNames` (the variables the check inherits, builder.ts SETUP_ENV_ALLOWLIST) as this
- * process holds them now — what the command is given. Hashed with checkContextOf's fields; the class reads
- * `<platform>-<arch>-node<major>`. Values are hashed, never stored.
- */
 export function captureCheckConditions(input) {
     const none = (problem) => ({ head: input.head, tree: null, commandDigest: input.command.digest, access: input.access, harnessDigest: null, lockfile: null, conditionsDigest: null, conditionsClass: null, problem });
     if (input.repo === null)
@@ -55,7 +21,6 @@ export function captureCheckConditions(input) {
     if (gitDir === null)
         return none("the project's Git directory can't be read");
     let read;
-    // Advisory: whatever happens reading the tree, the check itself is never stopped by it.
     try {
         read = treeFactsOf(gitDir, input.head);
     }
@@ -72,7 +37,6 @@ export function captureCheckConditions(input) {
     return { head: input.head, tree: read.facts.tree, commandDigest: input.command.digest, access: input.access, harnessDigest: read.facts.harnessDigest, lockfile: read.facts.lockfile,
         conditionsDigest: digest, conditionsClass: `${context.platform}-${context.arch}-node${major}`, problem: null };
 }
-/** Why the task's check ran: a release's or the nightly's purpose, read from the plane's own records. */
 export function checkPurposeOf(store, taskRef) {
     if (nightlyTaskRef(store, taskRef))
         return "nightly";
@@ -81,9 +45,6 @@ export function checkPurposeOf(store, taskRef) {
     const terms = store.handle.prepare(`SELECT s.release_terms_json, s.release_check_json FROM task_scope s JOIN task_ref r ON r.external_id = s.task_id AND r.backend = 'built-in' WHERE r.id = ?`).get(taskRef);
     return terms !== undefined && (terms["release_terms_json"] != null || terms["release_check_json"] != null) ? "release" : "ordinary";
 }
-/** The advisory learning line of a check's output, read strictly: exactly one line carrying this run's nonce, at most
- * 64 KiB, before the report, matching its contract, naming only requested exact cases, each once. Anything else is
- * not recorded, with why; that loses learning evidence only. */
 export function learningLinesOf(stdout, nonce, asked) {
     const lines = stdout.split("\n");
     let reportAt = -1;
@@ -139,7 +100,6 @@ export function learningLinesOf(stdout, nonce, asked) {
     return { ok: true, results: read.data.results };
 }
 const RANK = { passed: 0, skipped: 1, "passed-on-retry": 2, failed: 3 };
-/** The report's lines as results: every case it names; a file, group, version or part only when it didn't simply pass. */
 export function reportResults(report) {
     const rows = [];
     const add = (identity, state) => rows.push({ identity, state, source: "report" });
@@ -170,7 +130,6 @@ export function reportResults(report) {
             add(`part:${part.part}`, "failed");
     return rows;
 }
-/** The sealed log's FAIL lines (Vitest), failures only, file level; nothing when the log's own count disagrees. */
 function logResults(store, root, runId) {
     const logs = store.artifactsFor(runId).filter(one => one.kind === "check-log");
     if (logs.length !== 1)
@@ -181,11 +140,6 @@ function logResults(store, root, runId) {
     const failing = failingTestsOf(read.content.toString("utf8")) ?? [];
     return failing.filter(one => /^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[^\u0000-\u001f\\]{1,512}$/.test(one.file)).map(one => ({ identity: `file:${one.file}`, state: "failed", source: "log" }));
 }
-/**
- * Record what a settled check ran under and reported, once (first write wins), in one transaction: its fact row and
- * every result row. Called at disposition by the builder right after it records the check's own outcome. Advisory:
- * nothing reads these for a verdict, a rerun or an approval.
- */
 export function recordCheckFacts(store, root, input) {
     const conditions = input.conditions;
     const comparable = conditions !== null && conditions.tree !== null && conditions.conditionsDigest !== null;
@@ -218,7 +172,6 @@ export function recordCheckFacts(store, root, input) {
     }
     if (comparable && input.receipt.status === "failed" && !rows.some(one => one.source !== "receipt" && one.state === "failed"))
         rows.push({ identity: UNEXPLAINED, state: "failed", source: "receipt" });
-    // One row per (identity, source), its worst state; bounded.
     const kept = new Map();
     for (const row of rows) {
         if (row.identity.length < 1 || row.identity.length > 2600)
@@ -240,8 +193,6 @@ export function recordCheckFacts(store, root, input) {
             const insert = store.handle.prepare("INSERT INTO check_result (run, identity, state, source, recorded_at) VALUES (?, ?, ?, ?, ?)");
             for (const row of [...kept.values()].slice(0, MAX_RESULTS_PER_CHECK))
                 insert.run(input.runId, row.identity, row.state, row.source, at);
-            // In the same transaction: what this check adds to the flaky-test list and to accepted notes' tallies, advisory like
-            // everything here.
             const observations = recordObservations(store, input.runId, input.now);
             if (input.repo !== null)
                 tallyCheck(store, input.runId, input.repo, observations, input.now);
@@ -249,24 +200,21 @@ export function recordCheckFacts(store, root, input) {
         });
     }
     catch (error) {
-        // Not every check was counted this month: its tallies say so.
         if (input.repo !== null) {
             try {
                 markTalliesPartial(store, input.repo, input.now);
             }
-            catch { /* the note reads as it was */ }
+            catch { }
         }
         throw error;
     }
-    // A person's lesson note, when this check is what passed a revision. Advisory: nothing here reaches the check.
     if (recorded) {
         try {
             considerLessonNote(store, root, input.runId, input.now);
         }
-        catch { /* no note */ }
+        catch { }
     }
 }
-/** The storage sweep's own step: results older than the retention window go; their fact rows stay. */
 export function pruneCheckResults(store, now) {
     const cut = new Date(now.getTime() - RESULT_RETAIN_MS).toISOString();
     return Number(store.handle.prepare("DELETE FROM check_result WHERE recorded_at < ?").run(cut).changes);
@@ -280,20 +228,13 @@ export function checkFactOf(store, runId) {
         harnessDigest: text("harness_digest"), lockfile: text("lockfile"), conditionsDigest: text("conditions_digest"), conditionsClass: text("conditions_class"),
         purpose: String(row["purpose"]), learnState: String(row["learn_state"]), learnWhy: text("learn_why"), recordedAt: String(row["recorded_at"]) };
 }
-/** A check's recorded results, by source then identity. */
 export function checkResultsOf(store, runId) {
     return store.handle.prepare("SELECT identity, state, source FROM check_result WHERE run = ? ORDER BY source, identity").all(runId)
         .map(row => ({ identity: String(row["identity"]), state: String(row["state"]), source: String(row["source"]) }));
 }
-/**
- * What a project's Full checks are asked about for learning (`learn`): its tracked identities (learning_watch) — an
- * accepted note's until it ends, an observation's for 90 days — exact cases only, the most recently tracked first, at
- * most 200. Those left out are counted (`leftOut`): a coverage gap, said, never hidden.
- */
 export function learnRequestFor(store, repo, now, runId) {
     const since = new Date(now.getTime() - OBSERVATION_WATCH_MS).toISOString();
     let tracked;
-    // Advisory: a read that fails asks about nothing, and the check runs as it would have.
     try {
         tracked = store.handle.prepare(`SELECT identity, MAX(since) AS latest FROM learning_watch
       WHERE repo = ? AND ((reason = 'note' AND until IS NULL) OR (reason = 'observation' AND since >= ?))
@@ -302,7 +243,6 @@ export function learnRequestFor(store, repo, now, runId) {
     catch {
         return { learn: [], leftOut: 0 };
     }
-    // First, the failed cases of the check this run revises (lesson-notes.ts rule 4).
     let revised = [];
     if (runId !== undefined) {
         try {