toolroll 0.9.104 → 0.9.105

package/dist/contracts/store-json.js

@@ -1,39 +1,20 @@
-/**
- * The JSON columns the store reads back (docs/plans/zod-revamp.md, item 18): one schema per `table.column`, read
- * through `readVersioned`. Every writer through 0.9.41 stores the bare value, and writes are unchanged, so a row reads
- * as version 0 and is upgraded in memory only to `{ version: 1, value }`; nothing is rewritten.
- *
- * Existing field contracts describe known shapes, without imposing their write-time limits on old rows.
- * Legacy cast-only readers also accepted null,
- * partial objects and wrong-shaped JSON: LEGACY_JSON_COLUMNS names those compatibility exceptions. Such rows keep
- * their original values and report legacyIssues, rather than newly throwing or taking a different fallback.
- * List readers still filter, coerce, clip and default after parsing. No reader serializes a schema's output back.
- * Contracts owned elsewhere stay there: flow.ts, route.ts, stage-output.ts, flow-send.ts and chat-content.ts
- * (chat-tables.ts only owns DDL). Plan and handoff artifacts are files, not JSON columns in store.ts.
- */
 import { z } from "zod";
 import { decisionOptionSchema } from "./decision.js";
 import { scopeTermsSchema, storedRubricSchema } from "./scope.js";
 import { criterionEvidenceSchema, proofCriterionSchema } from "./proof.js";
 import { sharedActionSchema } from "./chat-actions.js";
 import { readVersioned, versioned } from "./contract.js";
-/** Dynamic tool arguments, event details and operation results have no common field contract. */
 const savedObject = z.looseObject({});
-/** A JSON list; its reader filters, coerces and clips the items after parsing, as before. */
 const savedList = z.array(z.unknown());
-/** An object with a text `label`: a card's source (its reader keeps picking the fields it knows). */
 const cardSource = z.looseObject({ label: z.string() });
-/** A subagent's rule for one tool action, as `subagents.ts` writes it. */
 export const savedToolRuleSchema = z.looseObject({
     use: z.enum(["free", "ask", "never"]),
     limit: z.looseObject({ field: z.string(), over: z.number() }).optional(),
-    /** Another action of the same tool that undoes this one with the same input. */
     undo: z.string().optional(),
 });
 export const savedToolActionSchema = z.looseObject({
     name: z.string(), about: z.string(), input: savedObject.nullable(), readOnly: z.boolean(),
 });
-// Reuse the option's canonical fields, dropping only write-time text bounds on a saved row.
 export const savedDecisionOptionSchema = decisionOptionSchema.extend({
     id: z.string(), label: z.string(), consequence: z.string(),
 }).loose();
@@ -70,7 +51,6 @@ const STORE_COLUMN_VALUES = {
     "flow_card.source_json": cardSource,
     "flow_comment.mentions_json": savedList,
     "task_scope.touches": z.lazy(() => scopeTermsSchema.unwrap().shape.touches.unwrap()),
-    /** Read by the scope contract's `parseAcceptanceCriteria` (`scope.ts`), which owns the criterion's shape. */
     "task_scope.acceptance_json": storedRubricSchema,
     "operating_mode.terms_json": savedModeTermsSchema,
     "approval_policy.protected_paths": savedList,
@@ -79,7 +59,6 @@ const STORE_COLUMN_VALUES = {
     "decision.options": z.array(savedDecisionOptionSchema),
     "tool_seal.tools_json": savedList,
     "run_tool.tools_json": savedToolsSchema,
-    /** `json_extract(tools_json, '$.fence')`: the fence an attempt ran with. */
     "run_tool.tools_json.fence": savedFenceSchema,
     "lead_ask.options_json": z.array(z.string()),
     "lead_config.about_json": savedList,
@@ -91,7 +70,6 @@ const STORE_COLUMN_VALUES = {
     "task_ref.capability_requirements": savedList,
     "coordinator_proposal.payload_json": savedObject,
     "coordinator_proposal.outcome_json": savedObject,
-    // Other proposal kinds have operation-specific fields; the action variant already has a canonical contract.
     "lead_proposal.payload_json": z.union([sharedActionSchema, savedObject]),
     "lead_proposal.outcome_json": savedObject,
     "proof_verdict.matrix_json": z.array(savedMatrixRowSchema),
@@ -101,11 +79,8 @@ const STORE_COLUMN_VALUES = {
     "backend_grant.paths": savedList,
     "backend_grant.mutations": savedList,
 };
-/** Every JSON column the store reads itself, by `table.column`. */
 export const STORE_COLUMNS = Object.keys(STORE_COLUMN_VALUES).filter(column => column !== "run_tool.tools_json.fence");
-/** A SQL projection, not a physical column; replay it separately after its owning column. */
 export const STORE_PROJECTIONS = ["run_tool.tools_json.fence"];
-/** These readers historically only parsed JSON. Shape errors must not change their values or catch boundaries. */
 export const LEGACY_JSON_COLUMNS = [
     "subagent_suggestion.rule_json", "subagent_suggestion.was_json", "subagent_suggestion.evidence_json",
     "subagent_call.input_json", "subagent_tool.actions_json", "subagent_tool.rules_json", "subagent_question.options_json",
@@ -116,17 +91,11 @@ export const LEGACY_JSON_COLUMNS = [
     "coordinator_proposal.payload_json", "coordinator_proposal.outcome_json",
     "lead_proposal.payload_json", "lead_proposal.outcome_json",
 ];
-/** One column's versioned envelope: `{ version: 1, value }`, built in memory around the saved bare value. */
 export function storeColumnSchema(column) {
     return versioned(1, { value: STORE_COLUMN_VALUES[column] });
 }
 const SCHEMAS = new Map([...STORE_COLUMNS, ...STORE_PROJECTIONS].map(column => [column, storeColumnSchema(column)]));
-/** A saved bare value is version 0; its upgrade wraps it. */
 const UPGRADES = { 0: (payload) => ({ version: 1, value: payload["value"] }) };
-/**
- * Read one saved column value (`String(raw)`, as every reader did) through its schema. Never throws: the caller keeps
- * the fallback its reader always had.
- */
 export function readStoreColumn(column, raw) {
     let parsed;
     try {
@@ -139,8 +108,6 @@ export function readStoreColumn(column, raw) {
 }
 function readParsedColumn(column, parsed) {
     const read = readVersioned(SCHEMAS.get(column), { value: parsed }, UPGRADES);
-    // Return the original JSON, including unknown keys, property order and own __proto__ keys. In particular, never
-    // replace old cast-only values with a schema's stripped/defaulted output. A matrix historically accepted any list.
     const legacy = LEGACY_JSON_COLUMNS.includes(column) || (column === "proof_verdict.matrix_json" && Array.isArray(parsed));
     if (read.ok || legacy)
         return {
@@ -149,15 +116,10 @@ function readParsedColumn(column, parsed) {
         };
     return { ok: false, malformed: false, issues: read.issues.map(unwrap) };
 }
-/** `value.label: required` reads as `label: required`: the envelope is the reader's, not the row's. */
 function unwrap(issue) {
     const at = issue.path === "value" ? "payload" : issue.path.startsWith("value.") ? issue.path.slice(6) : issue.path.startsWith("value[") ? `payload${issue.path.slice(5)}` : issue.path;
     return { ...issue, path: at, line: issue.line.startsWith(`${issue.path}:`) ? `${at}${issue.line.slice(issue.path.length)}` : issue.line };
 }
-/**
- * Read one saved column value for a reader that let a bad row throw: unreadable JSON throws the same SyntaxError
- * `JSON.parse` threw. Legacy shape issues are advisory; only a previously enforced shape can throw.
- */
 export function parseStoreColumn(column, raw) {
     const parsed = JSON.parse(String(raw));
     const read = readParsedColumn(column, parsed);
@@ -165,19 +127,16 @@ export function parseStoreColumn(column, raw) {
         throw new Error(`${column}: ${read.issues.map(issue => issue.line).join("; ")}`);
     return read.value;
 }
-/** A list of text, as `readJsonArray` always read one: unreadable or not a list is none; non-text items are dropped. */
 export function readStoreTextList(column, raw) {
     const read = readStoreColumn(column, raw);
     return read.ok && Array.isArray(read.value) ? read.value.filter((one) => typeof one === "string") : [];
 }
-/** A list read with every item as text (`String(item)`), as reasons and unresolved criteria always were; otherwise none. */
 export function readStoreStringifiedList(column, raw) {
     const read = readStoreColumn(column, raw);
     try {
         return read.ok && Array.isArray(read.value) ? read.value.map(one => String(one)) : [];
     }
     catch {
-        // JSON objects can shadow toString with a non-function. The old readers caught failed coercion too.
         return [];
     }
 }

package/dist/contracts/subagent-turn.js

@@ -1,42 +1,19 @@
-/**
- * A subagent's turn (subagents.ts): one schema for the JSON Schema Claude answers in (`--json-schema`) and the reader
- * that takes the answer back. One flat object with every field (a root union is refused by the API); fields a turn
- * does not use are "" (or [] for options).
- *
- * The text limits (TURN_LIMITS, from TEXT_LIMITS) are deliberately not in the schema: the CLI refuses an answer a few
- * characters over one whole, so they are checked after parsing and an answer over one is asked once to shorten
- * (subagent-work.ts), then kept whole. What the zone allows — which actions, which answers, a note for a send-back, a
- * question for an ask, a tool for a tool call — is checked after parsing too (`readTurn`), by path.
- *
- * A turn is kept as the step's decision (`flow_step_run.decision_json`) as it was read, so a saved one is this shape.
- */
 import { z } from "zod";
 import { parseContract, toModelSchema } from "./contract.js";
-/** What a subagent may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick
- * where it goes, ask its person, or say it can't. v94: "use_tool" asks for one tool call. */
 export const TURN_ACTIONS = ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
 export const subagentTurnSchema = z.object({
     action: z.enum(TURN_ACTIONS),
-    /** route: one of the zone's answers, exactly as written. */
     answer: z.string(),
-    /** What the next zones read, or the draft as rewritten. */
     text: z.string(),
-    /** A decision or send-back note. */
     note: z.string(),
-    /** ask: one short question, with up to 4 options to tap. */
     question: z.string(),
     options: z.array(z.string()),
-    /** One plain sentence saying why, for its manager's log. */
     reason: z.string(),
-    /** use_tool: the tool's name, and its input as a JSON object written as text. */
     tool: z.string(),
     input: z.string(),
-    /** v95: one short fact worth keeping for later cards ("": none). */
     remember: z.string(),
 });
-/** What Claude's `--json-schema` is for a turn: the turn schema, exactly. */
 export const TURN_MODEL_SCHEMA = toModelSchema(subagentTurnSchema);
-/** Older and plain-text turns default absent or non-text fields to "", and keep only string options. */
 export function readTurnAnswer(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         const body = { ...value };

package/dist/contracts/task-sizing.js

@@ -1,11 +1,3 @@
-/**
- * The task sizing classifier's answer (task-sizing.ts): one schema for the JSON Schema a Claude sizer is given
- * (`--json-schema`) and the reader that takes an answer back. Jev answers through OpenRouter's Decisions API, which
- * takes questions rather than a JSON Schema; its choice and yes/no are read into this same answer before they count.
- *
- * An answer is never kept as it is (it becomes the task's sizing, phase-routing.ts `TaskSizing`), so it carries no
- * version.
- */
 import { z } from "zod";
 import { TASK_SIZES } from "../phase-routing.js";
 import { TEXT_LIMITS } from "../text-limits.js";
@@ -15,9 +7,7 @@ export const sizeAnswerSchema = z.object({
     risky: z.boolean(),
     reason: limited("reason", "sizingReason").describe(`reason: at most ${TEXT_LIMITS.sizingReason} characters.`),
 });
-/** What a Claude sizer's `--json-schema` is: the answer schema, exactly. */
 export const SIZING_MODEL_SCHEMA = toModelSchema(sizeAnswerSchema);
-/** Keep the old reason defaults and clipping before checking the normalized answer's contract. */
 export function readSizeAnswer(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         const body = value;

package/dist/contracts/teams-callback.js

@@ -1,14 +1,7 @@
-/**
- * A Teams button tap (teams-chat.ts `receiveTeams`): an Adaptive Card `Action.Submit` arrives as a message activity
- * whose `value` is the data Toolroll put on the button, `{ so: <one-time token> }`. The activity is Microsoft's (read
- * by `receiveTeams`); only `value.so` is read, as before, and extra submit keys are ignored. A tap from the paired person whose data can't be read
- * is answered with why (`value.so: must be a Toolroll button token`), and nothing is done.
- */
 import { z } from "zod";
 import { CHAT_BUTTON_TOKEN } from "./chat-content.js";
 import { parseContract } from "./contract.js";
 export const teamsSubmitSchema = z.object({ so: z.string().regex(CHAT_BUTTON_TOKEN, { error: "must be a Toolroll button token" }) });
-/** A submit's one-time token. */
 export function readTeamsSubmit(value) {
     const read = parseContract(z.object({ value: teamsSubmitSchema }), { value });
     return read.ok ? { ok: true, value: read.value.value.so } : read;

package/dist/contracts/telegram-callback.js

@@ -1,11 +1,3 @@
-/**
- * Telegram (telegram.ts): one schema for an update as Telegram sends it — polled, or pushed to /hooks/telegram and kept
- * in the inbox until applied — and one for the data a Toolroll button carries.
- *
- * The update is Telegram's: only the fields Toolroll reads are described, and any others are ignored. A button's data
- * is Toolroll's: one of the forms it mints, within Telegram's 64 bytes. A tap whose data isn't one of them is
- * answered, after the sender and chat are proved, with the line that says why, and nothing is done.
- */
 import { z } from "zod";
 import { lengthIn, TEXT_LIMITS } from "../text-limits.js";
 import { limited, parseContract } from "./contract.js";
@@ -17,8 +9,6 @@ export const telegramMessageSchema = z.object({
     chat: chat.optional(),
     from: sender.optional(),
     reply_to_message: z.object({ message_id: z.int() }).optional(),
-    /** Presence of any of these disqualifies a note: only direct, initial, plain text counts as authored-and-confirmed
-     * by the paired operator. */
     forward_origin: z.unknown().optional(),
     forward_date: z.unknown().optional(),
     via_bot: z.unknown().optional(),
@@ -27,7 +17,6 @@ export const telegramMessageSchema = z.object({
 });
 export const telegramCallbackQuerySchema = z.object({
     id: z.string(),
-    /** Read by `readTelegramButtonData`, after the sender and chat are proved. */
     data: z.string().optional(),
     from: z.object({ id: z.int() }).optional(),
     message: z.object({ message_id: z.int(), chat: z.object({ id: z.int() }).optional(), text: z.string().optional(), entities: z.array(z.unknown()).optional() }).optional(),
@@ -37,11 +26,9 @@ export const telegramUpdateSchema = z.object({
     message: telegramMessageSchema.optional(),
     callback_query: telegramCallbackQuerySchema.optional(),
 });
-/** One update, as Telegram sent it (refused by path: `callback_query.message.chat.id: must be a number`). */
 export function readTelegramUpdate(input) {
     return parseContract(telegramUpdateSchema, input);
 }
-/** An inbox row's saved update: JSON first, then the schema. */
 export function parseTelegramUpdate(raw) {
     let body;
     try {
@@ -52,30 +39,18 @@ export function parseTelegramUpdate(raw) {
     }
     return readTelegramUpdate(body);
 }
-/**
- * Every form of data a Toolroll button carries: a one-time token (16 random bytes as hex) for a proposal, decision,
- * flow, choice or question button; a decide token (chat-decide.ts); a task from /tasks, or back to the lead; and an
- * option of the lead's question to its owner (by index, or `x` for "Something else").
- */
 export const TELEGRAM_BUTTON_DATA = /^(?:[a-f0-9]{32}|d:[a-f0-9]{24}|pick:(?:lead|[1-9][0-9]{0,14})|ask:[1-9][0-9]{0,14}:(?:[0-3]|x))$/;
 export const telegramButtonDataSchema = limited("callback_data", "telegramCallbackDataBytes")
     .regex(TELEGRAM_BUTTON_DATA, { error: "not a Toolroll button" });
-/** A button that calls back (the other kind opens a link). */
 export const telegramCallbackButtonSchema = z.strictObject({ text: z.string(), callback_data: telegramButtonDataSchema });
-/** The byte bound, which counts UTF-8 bytes where the schema counts characters. */
 function withinBytes(data) {
     const limit = TEXT_LIMITS.telegramCallbackDataBytes, bytes = lengthIn(data, "bytes");
     return bytes <= limit ? { ok: true, value: data } : { ok: false, issues: [{ path: "callback_data", kind: "too-long", line: `callback_data: over ${limit} bytes (${bytes})` }] };
 }
-/** A tapped button's data: one Toolroll mints, or the path-named reason it isn't (`callback_data: required`). */
 export function readTelegramButtonData(data) {
     const read = parseContract(z.strictObject({ callback_data: telegramButtonDataSchema }), { callback_data: data });
     return read.ok ? withinBytes(read.value.callback_data) : read;
 }
-/**
- * A button as Toolroll sends it. Data Telegram would refuse (over 64 bytes) or that a tap could not be read back is a
- * fault in the code that made it, so it throws before anything is sent.
- */
 export function telegramButton(text, data) {
     const read = parseContract(telegramCallbackButtonSchema, { text, callback_data: data });
     const bytes = read.ok ? withinBytes(read.value.callback_data) : read;
@@ -83,14 +58,12 @@ export function telegramButton(text, data) {
         throw new Error(`a Telegram button: ${(read.ok ? bytes.ok ? [] : bytes.issues : read.issues).map(issue => issue.line).join("; ")}`);
     return read.value;
 }
-/** A /tasks pick: the task's ref id, or back to the lead (null); null for anything else. */
 export function pickOf(data) {
     if (data === "pick:lead")
         return { ref: null };
     const ref = /^pick:([1-9][0-9]{0,14})$/.exec(data)?.[1];
     return ref === undefined ? null : { ref: Number(ref) };
 }
-/** An option of the lead's question to its owner: its turn and index, or `x` for "Something else"; null for anything else. */
 export function askOf(data) {
     const tap = /^ask:([1-9][0-9]{0,14}):([0-3]|x)$/.exec(data);
     return tap === null ? null : { turn: Number(tap[1]), option: tap[2] === "x" ? "x" : Number(tap[2]) };

package/dist/contracts/trigger-payloads.js

@@ -1,25 +1,9 @@
-/**
- * What a flow trigger reads from outside (flow-triggers.ts): GitHub's issues, pull requests, workflow runs and webhook
- * events, Linear's GraphQL answers and webhook events, a plain webhook's JSON, a mailbox's normalized message and a
- * shared form's fields.
- *
- * These payloads belong to the services that send them, so each schema describes only the fields Toolroll reads and
- * ignores every other key. A field of the wrong type reads as missing (as the hand reader's `text()` and `record()`
- * did), so no delivery or poll is ever refused here: what was accepted before is accepted now, and what a payload
- * lacks is decided after parsing, with the same answer and plain reason as before. Numbers stay as sent (`number`,
- * `webhookTimestamp`) and are coerced with `Number()` after parsing, as they always were; so do the values whose mere
- * presence counts (`pull_request`, `updatedFrom.stateId`).
- */
 import { z } from "zod";
-/** A field read when it has the type Toolroll expects, and read as missing when it has any other. */
 const loose = (schema) => schema.optional().catch(undefined);
 const text = loose(z.string());
 const named = z.object({ name: text }).catch({});
-/** A GitHub issue or pull request, from a poll or inside a webhook event. */
 export const githubIssueSchema = z.object({
-    /** Coerced with `Number()` after parsing; a card needs a safe integer. */
     number: z.unknown().optional(),
-    /** An issue that is a pull request carries this (any value). */
     pull_request: z.unknown().optional(),
     draft: loose(z.boolean()),
     labels: loose(z.array(named)),
@@ -33,7 +17,6 @@ export const githubIssueSchema = z.object({
     created_at: text,
     updated_at: text,
 }).catch({});
-/** A GitHub Actions workflow run. */
 export const githubRunSchema = z.object({
     conclusion: text,
     head_branch: text,
@@ -42,18 +25,13 @@ export const githubRunSchema = z.object({
     display_title: text,
     created_at: text,
     html_url: text,
-    /** Read by tidy's CI observations (task-tidy.md): which run, why it ran, and whose repository its commit is in. */
     id: loose(z.number()),
     event: text,
     head_repository: loose(z.object({ full_name: text })),
 }).catch({});
-/** `repos/:repo/issues` and `repos/:repo/pulls`: a list (anything else reads as an empty one). */
 export const githubIssueListSchema = z.array(githubIssueSchema).catch([]);
-/** `repos/:repo/issues/events`: a list of issue events. */
 export const githubIssueEventListSchema = z.array(z.object({ event: text, label: loose(named), created_at: text, issue: githubIssueSchema.optional() }).catch({})).catch([]);
-/** `repos/:repo/actions/runs`. */
 export const githubRunListSchema = z.object({ workflow_runs: loose(z.array(githubRunSchema)) }).catch({});
-/** A signed GitHub webhook event (`issues`, `pull_request`, `workflow_run`; a `ping` reads as an empty one). */
 export const githubEventSchema = z.object({
     action: text,
     repository: loose(z.object({ full_name: text })),
@@ -62,7 +40,6 @@ export const githubEventSchema = z.object({
     pull_request: githubIssueSchema.optional(),
     workflow_run: githubRunSchema.optional(),
 }).catch({});
-/** A Linear issue, from the GraphQL query (`labels { nodes }`) or a webhook's `data` (`labels` as a list). */
 export const linearIssueSchema = z.object({
     identifier: text,
     title: text,
@@ -73,27 +50,18 @@ export const linearIssueSchema = z.object({
     team: loose(z.object({ key: text })),
     labels: loose(z.union([z.array(named), z.object({ nodes: loose(z.array(named)) })])),
 }).catch({});
-/** Linear's GraphQL answer to LINEAR_QUERY. */
 export const linearAnswerSchema = z.object({
     errors: loose(z.array(z.object({ message: text }).catch({}))),
     data: loose(z.object({ issues: loose(z.object({ nodes: loose(z.array(linearIssueSchema)) })) })),
 }).catch({});
-/** A signed Linear webhook event. */
 export const linearEventSchema = z.object({
     type: text,
     action: text,
-    /** Milliseconds; coerced with `Number()` after parsing. */
     webhookTimestamp: z.unknown().optional(),
-    /** An update that moved the issue's state carries `stateId` (any value). */
     updatedFrom: loose(z.object({ stateId: z.unknown().optional() })),
     data: linearIssueSchema.optional(),
 }).catch({});
-/**
- * A plain webhook's body: any JSON. The trigger's own `titleField` and `bodyField` paths (or title/summary/message and
- * description/body/text) are picked from it after parsing, and a body without one is shown whole, so it is kept as sent.
- */
 export const webhookPayloadSchema = z.unknown();
-/** A message as the mailbox reader hands it on (mailbox.ts normalizes and clips the raw mail before this). */
 export const inboundMailSchema = z.object({
     uid: z.number(),
     messageId: z.string().nullable(),
@@ -105,18 +73,13 @@ export const inboundMailSchema = z.object({
     text: z.string(),
     automatic: z.boolean(),
 });
-/** A shared form's submission: the first value of each field, as URLSearchParams.get reads it (null when absent). */
 export const formSubmissionSchema = z.object({
-    /** When the page was shown, in milliseconds; coerced with `Number()` after parsing. */
     t: z.string().nullable(),
-    /** The trap a person never fills in. */
     website: z.string().nullable(),
-    /** `a0`, `a1`, … one per question. */
     answers: z.array(z.string().nullable()),
 });
 const mailMatchesSchema = true;
 void mailMatchesSchema;
-/** Every field a schema reads; none of these readers refuses (a field of the wrong type reads as missing). */
 export const readGithubIssue = (raw) => githubIssueSchema.parse(raw);
 export const readGithubRun = (raw) => githubRunSchema.parse(raw);
 export const readGithubIssueList = (raw) => githubIssueListSchema.parse(raw);
@@ -127,18 +90,14 @@ export const readLinearIssue = (raw) => linearIssueSchema.parse(raw);
 export const readLinearAnswer = (raw) => linearAnswerSchema.parse(raw);
 export const readLinearEvent = (raw) => linearEventSchema.parse(raw);
 export const readWebhookPayload = (raw) => webhookPayloadSchema.parse(raw);
-/** A Linear issue's label names, from either shape. */
 export function linearLabelNames(issue) {
     const labels = issue.labels;
     return (Array.isArray(labels) ? labels : labels?.nodes ?? []).map(one => one.name ?? "");
 }
-/** A message from the mailbox reader. It is the mailbox's own type, so it always reads; one that somehow didn't is
- * used as it came, as before. */
 export function readInboundMail(mail) {
     const read = inboundMailSchema.safeParse(mail);
     return read.success ? read.data : mail;
 }
-/** A shared form's fields: the first value of each, and one answer per question (`a0` …). Strings always read. */
 export function readFormSubmission(fields, questions) {
     return formSubmissionSchema.parse({
         t: fields.get("t"),

package/dist/contracts/update-journal.js

@@ -1,33 +1,16 @@
-/**
- * The update journals and their small control records (docs/plans/zod-revamp.md, item 19): the desktop app's update
- * (`desktop-update.json` and the retained `receipt.json`) and `toolroll update`'s (`toolroll-update.json`,
- * `.last.json` and the stage's `update.json`), plus the request, stop, cancel and starting marks beside them.
- *
- * Every journal is Toolroll's own and carries `version: 1`, but the reader ignores keys it does not know: a rollback
- * runs an older Toolroll against a journal a newer one wrote, and every field added since 0.8.0 was added under the
- * same version. A newer version is refused plainly. Readers return the saved object itself once it parses, so a
- * journal saved again keeps its keys, their order and anything a newer release added. Paths, ownership, identities
- * and hashes are checked in plain code by the update modules after parsing, with their existing words.
- */
 import { z } from "zod";
 import { readVersioned } from "./contract.js";
 function journalOf(schema, input) {
     const read = readVersioned(schema, input);
-    // Catch values only let legacy-unchecked information pass validation; never apply them to the saved object.
-    // Keep its original values, key order and keys a newer release added.
     return read.ok ? { ok: true, value: input } : read;
 }
-/** A finished run an update waits on (or stopped waiting on). */
 const waitingSchema = z.object({ run: z.number(), on: z.string(), action: z.string().nullable(), since: z.string() });
 const releasedCodingOwnerSchema = z.object({ pid: z.number(), nativePid: z.number().nullable() });
-// ---- the desktop app's update ------------------------------------------------------------------------------------
 export const DESKTOP_UPDATE_PHASES = ["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"];
-/** An app bundle as the journal records it (`readDesktopBundle`'s identity). */
 export const desktopBundleSchema = z.object({
     path: z.string(), hash: z.string(), buildId: z.string(), version: z.string(), bundleId: z.string(),
     schemaVersion: z.number(), development: z.boolean().catch(false), providerBin: z.string(), recoveryProtocol: z.number().exactOptional(),
 });
-/** The keys in the order the old reader checked them, so the first issue picks the same refusal it gave. */
 export const desktopUpdateJournalSchema = z.object({
     version: z.literal(1),
     id: z.string(), stateDir: z.string(), workDir: z.string(), label: z.string(),
@@ -43,33 +26,25 @@ export const desktopUpdateJournalSchema = z.object({
     error: z.string().optional().catch(undefined), checkedAt: z.string().optional().catch(undefined),
     serviceInterrupted: z.boolean().exactOptional(),
     retryableRecovery: z.boolean().exactOptional(),
-    /** The finished run the update is waiting on (or stopped waiting on). Absent while it waits on ordinary work. */
     waiting: waitingSchema.exactOptional(),
-    /** A stale coding owner record this update released after proving those processes gone. */
     codingOwnerReleased: releasedCodingOwnerSchema.exactOptional(),
 });
 export function readDesktopUpdateJournal(input) {
     return journalOf(desktopUpdateJournalSchema, input);
 }
-/** The automatic-recovery guardian's record (`recovery.json`) as Update status reads it: each field is used only when
- * it has its type, as before; the guardian itself owns the full record. */
 export const desktopRecoveryViewSchema = z.object({
     id: z.string().optional().catch(undefined), state: z.string().optional().catch(undefined), detail: z.string().optional().catch(undefined),
     attempts: z.number().optional().catch(undefined), repairs: z.number().optional().catch(undefined), updatedAt: z.string().optional().catch(undefined),
 });
-/** Update status's view of `recovery.json`; anything that is not an object reads as no guardian, as before. */
 export function readDesktopRecoveryView(input) {
     const read = desktopRecoveryViewSchema.safeParse(input);
     return read.success ? read.data : null;
 }
-/** `request.json` (a restore) and `stop-request.json`, as `requestUpdateRestore` and `requestUpdateStop` write them. */
 export const updateRequestSchema = z.object({ id: z.unknown().exactOptional(), action: z.unknown().exactOptional() });
-/** Whether a saved request is `{ id, action }` for this update; anything else is not that request. */
 export function updateRequestIs(input, id, action) {
     const read = updateRequestSchema.safeParse(input);
     return read.success && read.data.id === id && read.data.action === action;
 }
-/** The service supervisor's status file, read for the service's process ids before a stop. */
 export const supervisorPidsSchema = z.object({ supervisorPid: z.unknown().exactOptional(), controllerPid: z.unknown().exactOptional() });
 export function supervisorPidsOf(input) {
     const read = supervisorPidsSchema.safeParse(input);
@@ -77,7 +52,6 @@ export function supervisorPidsOf(input) {
         return [];
     return [read.data.supervisorPid, read.data.controllerPid].filter((pid) => Number.isSafeInteger(pid) && Number(pid) > 1);
 }
-// ---- toolroll update ---------------------------------------------------------------------------------------------
 export const RUNTIME_UPDATE_STEPS = ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
 export const RUNTIME_PHASES = ["scheduled", ...RUNTIME_UPDATE_STEPS, "complete", "rolling-back", "restored", "refused", "cancelled", "needs-attention"];
 const runtimeRefSchema = z.object({ version: z.string(), dist: z.string() });
@@ -95,58 +69,37 @@ export const runtimeUpdateJournalSchema = z.object({
     startedAt: z.string(), updatedAt: z.string(), finishedAt: z.string().optional().catch(undefined),
     package: z.object({ sha512: z.string(), repository: z.string(), workflow: z.string() }).exactOptional(),
     notes: z.array(z.string()).optional().catch(undefined),
-    /** This run's own verified copies of the live database and coding catalog: what a failure restores. */
     backupPath: z.string().exactOptional(), backupHash: z.string().exactOptional(),
     codingBackupPath: z.string().exactOptional(), codingBackupHash: z.string().exactOptional(),
-    /** A rollback installs the update's earlier backups (checked against their recorded hashes). */
     restoreFrom: z.object({ path: z.string(), hash: z.string(), updateId: z.string(), codingPath: z.string().exactOptional(), codingHash: z.string().exactOptional() }).exactOptional(),
     rehearsal: z.object({ tables: z.number(), rows: z.number() }).exactOptional(),
-    /** The background service, recorded before it is stopped: its definition and the processes that must be gone. */
     service: unitSchema.exactOptional(),
-    /** Each repo's watch daemon that runs this version, recorded the same way: switched with the service, and stopped and
-     * restarted with it only when launchd had it loaded before the update (`loaded` absent: 0.8.1 stopped every one). */
     watches: z.array(unitSchema.extend({ loaded: z.boolean().exactOptional() })).exactOptional(),
-    /** Recorded before each change so a resumed or failed run knows what to put back. */
     switched: z.object({
         links: z.array(z.object({ path: z.string(), previous: z.string() })),
         unit: savedFileSchema.nullable(),
         watches: z.array(savedFileSchema).exactOptional(),
         databaseRestored: z.boolean().exactOptional(),
     }).exactOptional(),
-    /** What the live database held when a failed run restored its backup: nothing written is lost. The newest of `kept`. */
     keptAside: z.string().exactOptional(),
-    /** The live database could not be read, so it was moved aside whole rather than copied. */
     keptAsideUnreadable: z.boolean().exactOptional(),
-    /** Every copy kept aside, oldest first: a retried restore adds one and never drops the pointer to an earlier one. */
     kept: z.array(z.object({ path: z.string(), unreadable: z.boolean() })).exactOptional(),
-    /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
-     * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
     restoredDatabase: z.boolean().exactOptional(),
-    /** A stale coding owner record this run released after proving its processes gone. */
     codingOwnerReleased: releasedCodingOwnerSchema.exactOptional(),
     seen: z.boolean().optional().catch(undefined),
-    /** The finished run the update is waiting on (or stopped waiting on): what is in the way and the command that
-     * clears it. Absent while it waits on ordinary running work. */
     waiting: waitingSchema.exactOptional(),
 });
 export function readRuntimeUpdateJournal(input) {
     return journalOf(runtimeUpdateJournalSchema, input);
 }
-/** `updater-starting.json`: a launched or resuming updater on its way to `id`. Only `id` and `at` are read. */
 export const updaterStartingSchema = z.object({ id: z.unknown().exactOptional(), state: z.unknown().exactOptional(), at: z.unknown().exactOptional() });
-/** The mark's update id and start time when it has them; a mark without them is no updater starting, as before. */
 export function updaterStartingOf(input) {
     const read = updaterStartingSchema.safeParse(input);
     if (!read.success)
         return null;
     return { id: read.data.id, at: Date.parse(typeof read.data.at === "string" ? read.data.at : String(read.data.at ?? "")) };
 }
-/** A staged release's `update.json` as pruning reads it: only `startedAt`, from a partial or older file alike. */
 export const stagedReleaseStartSchema = z.object({ startedAt: z.unknown().exactOptional() });
-/**
- * When a staged release started, for pruning: `startedAt` as text (`""` when absent or when the file holds some other
- * JSON value). `null` for JSON `null`, and the folder's mtime stands in, as it does for a file that is not JSON.
- */
 export function stagedStartedAt(input) {
     const read = stagedReleaseStartSchema.safeParse(input);
     if (read.success)