toolroll 0.9.36 → 0.9.37

package/dist/contracts/teams-callback.js

@@ -0,0 +1,14 @@
+/**
+ * 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 { parseContract } from "./contract.js";
+export const teamsSubmitSchema = z.object({ so: z.string().regex(/^[a-f0-9]{32}$/, { 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.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { type ContractResult } from "./contract.js";
+export declare const telegramMessageSchema: z.ZodObject<{
+    message_id: z.ZodInt;
+    text: z.ZodOptional<z.ZodString>;
+    chat: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    from: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        username: z.ZodOptional<z.ZodString>;
+        first_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    reply_to_message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+    }, z.core.$strip>>;
+    forward_origin: z.ZodOptional<z.ZodUnknown>;
+    forward_date: z.ZodOptional<z.ZodUnknown>;
+    via_bot: z.ZodOptional<z.ZodUnknown>;
+    sender_chat: z.ZodOptional<z.ZodUnknown>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const telegramCallbackQuerySchema: z.ZodObject<{
+    id: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+    }, z.core.$strip>>;
+    message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+        chat: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+        }, z.core.$strip>>;
+        text: z.ZodOptional<z.ZodString>;
+        entities: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const telegramUpdateSchema: z.ZodObject<{
+    update_id: z.ZodInt;
+    message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+        text: z.ZodOptional<z.ZodString>;
+        chat: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        from: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+            username: z.ZodOptional<z.ZodString>;
+            first_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        reply_to_message: z.ZodOptional<z.ZodObject<{
+            message_id: z.ZodInt;
+        }, z.core.$strip>>;
+        forward_origin: z.ZodOptional<z.ZodUnknown>;
+        forward_date: z.ZodOptional<z.ZodUnknown>;
+        via_bot: z.ZodOptional<z.ZodUnknown>;
+        sender_chat: z.ZodOptional<z.ZodUnknown>;
+        caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    callback_query: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        data: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+        }, z.core.$strip>>;
+        message: z.ZodOptional<z.ZodObject<{
+            message_id: z.ZodInt;
+            chat: z.ZodOptional<z.ZodObject<{
+                id: z.ZodInt;
+            }, z.core.$strip>>;
+            text: z.ZodOptional<z.ZodString>;
+            entities: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TelegramUpdate = z.infer<typeof telegramUpdateSchema>;
+export type TelegramMessage = z.infer<typeof telegramMessageSchema>;
+/** One update, as Telegram sent it (refused by path: `callback_query.message.chat.id: must be a number`). */
+export declare function readTelegramUpdate(input: unknown): ContractResult<TelegramUpdate>;
+/** An inbox row's saved update: JSON first, then the schema. */
+export declare function parseTelegramUpdate(raw: string): ContractResult<TelegramUpdate>;
+/**
+ * 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 declare const TELEGRAM_BUTTON_DATA: RegExp;
+export declare const telegramButtonDataSchema: z.ZodString;
+/** A button that calls back (the other kind opens a link). */
+export declare const telegramCallbackButtonSchema: z.ZodObject<{
+    text: z.ZodString;
+    callback_data: z.ZodString;
+}, z.core.$strict>;
+export type TelegramCallbackButton = z.infer<typeof telegramCallbackButtonSchema>;
+/** A tapped button's data: one Toolroll mints, or the path-named reason it isn't (`callback_data: required`). */
+export declare function readTelegramButtonData(data: unknown): ContractResult<string>;
+/**
+ * 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 declare function telegramButton(text: string, data: string): TelegramCallbackButton;
+/** A /tasks pick: the task's ref id, or back to the lead (null); null for anything else. */
+export declare function pickOf(data: string): {
+    ref: number | null;
+} | null;
+/** An option of the lead's question to its owner: its turn and index, or `x` for "Something else"; null for anything else. */
+export declare function askOf(data: string): {
+    turn: number;
+    option: number | "x";
+} | null;

package/dist/contracts/telegram-callback.js

@@ -0,0 +1,97 @@
+/**
+ * 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";
+const chat = z.object({ id: z.int(), type: z.string().optional() });
+const sender = z.object({ id: z.int(), username: z.string().optional(), first_name: z.string().optional() });
+export const telegramMessageSchema = z.object({
+    message_id: z.int(),
+    text: z.string().optional(),
+    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(),
+    sender_chat: z.unknown().optional(),
+    caption: z.string().optional(),
+});
+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(),
+});
+export const telegramUpdateSchema = z.object({
+    update_id: z.int().min(1),
+    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 {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    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;
+    if (!read.ok || !bytes.ok)
+        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/decision.d.ts

@@ -14,18 +14,11 @@
  * caps also keep one screen one screen: an option list that needs scrolling
  * has already failed the milestone sentence.
  */
-export type ParsedOption = {
-    id: string;
-    label: string;
-    consequence: string;
-    reversible: boolean;
-};
-export type ParsedDecision = {
-    urgency: "blocking";
-    recap: string;
-    question: string;
-    options: ParsedOption[];
-    recommendation: string;
+import { type DecisionOption, type DecisionPayload } from "./contracts/decision.js";
+/** One option as a decision keeps it (src/contracts/decision.ts). */
+export type ParsedOption = DecisionOption;
+/** A decision as read: the payload's fields, its text trimmed, and the optional ones present or null. */
+export type ParsedDecision = Omit<DecisionPayload, "assignee" | "deadline"> & {
     assignee: string | null;
     /** Normalized to toISOString(), like every timestamp in the store. */
     deadline: string | null;
@@ -41,17 +34,10 @@ export type ParseResult = {
     ok: false;
     problems: Problem[];
 };
-/** One screen's worth, enforced rather than hoped for. */
+/** One screen's worth, enforced rather than hoped for. The payload's fields are bounded by its schema (src/contracts/decision.ts, from TEXT_LIMITS). */
 export declare const LIMITS: {
     /** Bytes, before parsing. Applied by the reader too; this is the backstop. */
     readonly payload: number;
-    readonly recap: 2000;
-    readonly question: 2000;
-    readonly consequence: 500;
-    readonly label: 120;
-    readonly optionId: 40;
-    readonly assignee: 120;
-    readonly options: 6;
     /** UTF-16 code units (TEXT_LIMITS.note: revise feedback, steering and decision notes); the byte backstop lives in validateNote. */
     readonly note: 4000;
 };
@@ -79,6 +65,11 @@ export declare function hasForbiddenControls(text: string): boolean;
  * backwards is not a title, it is a costume.
  */
 export declare function hasDisguisedText(text: string): boolean;
+/**
+ * A parked decision, read against its contract (src/contracts/decision.ts): fail closed, every problem at once, each
+ * naming its path (`options[1].reversible: required`) under the reason code the repair turn, incidents and tests have
+ * always used (`missing-reversible`). A decision written without `version` reads as it always did.
+ */
 export declare function parseDecision(raw: string): ParseResult;
 /**
  * The terminal handoff: how every non-parking attempt says how it ended.

package/dist/decision.js

@@ -14,18 +14,12 @@
  * caps also keep one screen one screen: an option list that needs scrolling
  * has already failed the milestone sentence.
  */
+import { readDecisionPayload } from "./contracts/decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
-/** One screen's worth, enforced rather than hoped for. */
+/** One screen's worth, enforced rather than hoped for. The payload's fields are bounded by its schema (src/contracts/decision.ts, from TEXT_LIMITS). */
 export const LIMITS = {
     /** Bytes, before parsing. Applied by the reader too; this is the backstop. */
     payload: 64 * 1024,
-    recap: 2_000,
-    question: 2_000,
-    consequence: 500,
-    label: 120,
-    optionId: 40,
-    assignee: 120,
-    options: 6,
     /** UTF-16 code units (TEXT_LIMITS.note: revise feedback, steering and decision notes); the byte backstop lives in validateNote. */
     note: TEXT_LIMITS.note,
 };
@@ -58,8 +52,6 @@ export function validateNote(raw) {
     }
     return { ok: true, note };
 }
-/** Option ids travel in URLs, CLI arguments, and CAS updates — they are identifiers, not prose. */
-const OPTION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 /**
  * Multi-line prose may contain newlines and tabs; nothing anywhere in a
  * decision may contain the rest of C0/C1 — those are how text stops being
@@ -82,9 +74,14 @@ export function hasForbiddenControls(text) {
 export function hasDisguisedText(text) {
     return FORBIDDEN_MULTILINE.test(text) || FORBIDDEN_INVISIBLES.test(text);
 }
+/**
+ * A parked decision, read against its contract (src/contracts/decision.ts): fail closed, every problem at once, each
+ * naming its path (`options[1].reversible: required`) under the reason code the repair turn, incidents and tests have
+ * always used (`missing-reversible`). A decision written without `version` reads as it always did.
+ */
 export function parseDecision(raw) {
     if (Buffer.byteLength(raw, "utf8") > LIMITS.payload) {
-        return refuse("too-large", `the payload is over ${LIMITS.payload} bytes — one screen does not need that`);
+        return refuse("too-large", `payload: over ${LIMITS.payload} bytes — one screen does not need that`);
     }
     let parsed;
     try {
@@ -94,187 +91,109 @@ export function parseDecision(raw) {
         return refuse("not-json", `the payload is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return refuse("not-an-object", "the payload must be one JSON object");
+        return refuse("not-an-object", "payload: must be one JSON object");
     }
+    const read = readDecisionPayload(parsed);
+    const contract = read.ok ? [] : read.issues.map(decisionProblemOf);
     const body = parsed;
-    const problems = [];
-    // Urgency is required rather than defaulted: an agent that did not say
-    // whether the loop can continue has not composed a decision. Only
-    // 'blocking' exists in M3 — advisory needs a commit-and-complete lifecycle
-    // this park-before-commit path does not have.
-    if (body["urgency"] !== "blocking") {
-        problems.push({
-            reason: "bad-urgency",
-            message: `urgency must be the string "blocking" (got ${describe(body["urgency"])})`,
-        });
-    }
-    const recap = prose(body["recap"], "recap", LIMITS.recap, problems);
-    const question = prose(body["question"], "question", LIMITS.question, problems);
-    const options = parseOptions(body["options"], problems);
-    let recommendation = null;
-    if (typeof body["recommendation"] !== "string" || body["recommendation"] === "") {
-        problems.push({
-            reason: "missing-recommendation",
-            message: "recommendation is required and must be an option id — a decision without one is a shrug",
-        });
-    }
-    else if (options !== null && !options.some(option => option.id === body["recommendation"])) {
-        problems.push({
-            reason: "bad-recommendation",
-            message: `recommendation "${truncate(String(body["recommendation"]), 60)}" does not match any option id`,
-        });
-    }
-    else {
-        recommendation = body["recommendation"];
-    }
-    let assignee = null;
-    if (body["assignee"] !== undefined && body["assignee"] !== null) {
-        const line = singleLine(body["assignee"], "assignee", LIMITS.assignee, problems);
-        if (line !== null)
-            assignee = line;
-    }
-    let deadline = null;
-    if (body["deadline"] !== undefined && body["deadline"] !== null) {
-        const stamp = typeof body["deadline"] === "string" ? Date.parse(body["deadline"]) : NaN;
-        if (Number.isNaN(stamp)) {
-            problems.push({
-                reason: "bad-deadline",
-                message: `deadline must be an ISO 8601 timestamp (got ${describe(body["deadline"])})`,
-            });
-        }
-        else {
-            // Normalized so the store's lexicographic-comparison invariant holds.
-            deadline = new Date(stamp).toISOString();
-        }
-    }
-    if (problems.length > 0)
+    const problems = [...contract, ...decisionRuleProblems(body, contract)];
+    if (!read.ok || problems.length > 0)
         return { ok: false, problems };
+    const payload = read.value;
     return {
         ok: true,
         decision: {
-            urgency: "blocking",
-            recap: recap,
-            question: question,
-            options: options,
-            recommendation: recommendation,
-            assignee,
-            deadline,
+            urgency: payload.urgency,
+            recap: payload.recap.trim(),
+            question: payload.question.trim(),
+            options: payload.options.map(option => ({ id: option.id, label: option.label.trim(), consequence: option.consequence.trim(), reversible: option.reversible })),
+            recommendation: recommendedId(payload.recommendation),
+            assignee: payload.assignee === undefined || payload.assignee === null ? null : payload.assignee.trim(),
+            // Normalized so the store's lexicographic-comparison invariant holds.
+            deadline: payload.deadline === undefined || payload.deadline === null ? null : new Date(Date.parse(payload.deadline)).toISOString(),
         },
     };
 }
-function parseOptions(value, problems) {
-    if (!Array.isArray(value)) {
-        problems.push({ reason: "no-options", message: "options must be an array" });
-        return null;
+/** The reason code a contract issue has always had: `missing-recap`, `too-few-options`, `bad-option-id`. */
+function decisionReasonOf(issue) {
+    const at = issue.path;
+    const text = (field) => (issue.kind === "too-long" ? `${field}-too-long` : `missing-${field}`);
+    switch (at) {
+        case "urgency": return "bad-urgency";
+        case "options": return issue.kind === "too-few" ? "too-few-options" : issue.kind === "too-many" ? "too-many-options" : "no-options";
+        case "recommendation": return issue.kind === "too-long" ? "bad-recommendation" : "missing-recommendation";
+        case "deadline": return "bad-deadline";
     }
-    if (value.length < 2) {
-        // One option is not a decision, it is a notification wearing one's
-        // clothes — and the operator's real alternative ("do neither") deserves
-        // to be an option with a stated consequence, not an implied one.
-        problems.push({ reason: "too-few-options", message: "a decision needs at least 2 options" });
-        return null;
-    }
-    if (value.length > LIMITS.options) {
-        problems.push({
-            reason: "too-many-options",
-            message: `at most ${LIMITS.options} options fit on one screen (got ${value.length})`,
-        });
-        return null;
+    const option = /^options\[(\d+)\](?:\.(\w+))?$/.exec(at);
+    if (option !== null) {
+        const [, index, field] = option;
+        if (field === undefined)
+            return "bad-option";
+        if (field === "id")
+            return "bad-option-id";
+        if (field === "reversible")
+            return "missing-reversible";
+        return text(`option-${index}-${field}`);
     }
-    const options = [];
-    const seen = new Set();
-    let sound = true;
-    value.forEach((entry, index) => {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            problems.push({ reason: "bad-option", message: `option ${index} must be an object` });
-            sound = false;
+    return text(at);
+}
+const decisionProblemOf = (issue) => ({ reason: decisionReasonOf(issue), message: issue.line });
+/** True when `problems` name `field` or anything under it. */
+const touched = (problems, field) => problems.some(problem => problem.message.startsWith(`${field}:`) || problem.message.startsWith(`${field}[`) || problem.message.startsWith(`${field}.`));
+/**
+ * The rules JSON Schema cannot state, in plain code with named errors: text not blank once trimmed and free of control
+ * characters (a label or assignee on one line), unique option ids, a recommendation naming one of them, and a deadline
+ * that is a timestamp. Fields the contract already refused are skipped, so every problem is reported once and all at
+ * once.
+ */
+function decisionRuleProblems(body, contract) {
+    const problems = [];
+    const text = (value, path, slug, oneLine) => {
+        if (typeof value !== "string" || touched(contract, path))
             return;
+        if (value.trim() === "")
+            problems.push({ reason: `missing-${slug}`, message: `${path}: must not be blank` });
+        else if ((oneLine ? FORBIDDEN_SINGLE_LINE : FORBIDDEN_MULTILINE).test(value)) {
+            problems.push({ reason: `${slug}-control-characters`, message: `${path}: ${oneLine ? "must be one line with no control characters" : "contains control characters — text only"}` });
         }
+    };
+    text(body["recap"], "recap", "recap", false);
+    text(body["question"], "question", "question", false);
+    const options = Array.isArray(body["options"]) ? body["options"] : [];
+    const seen = new Set();
+    options.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return;
         const option = entry;
         const id = option["id"];
-        if (typeof id !== "string" || !OPTION_ID.test(id) || id.length > LIMITS.optionId) {
-            problems.push({
-                reason: "bad-option-id",
-                message: `option ${index} needs an id of 1-${LIMITS.optionId} letters, digits, - or _ (got ${describe(id)})`,
-            });
-            sound = false;
-        }
-        else if (seen.has(id)) {
-            problems.push({ reason: "duplicate-option-id", message: `option id "${id}" appears twice` });
-            sound = false;
-        }
-        else {
+        if (typeof id === "string" && !touched(contract, `options[${index}].id`)) {
+            if (seen.has(id))
+                problems.push({ reason: "duplicate-option-id", message: `options[${index}].id: "${id}" appears twice` });
             seen.add(id);
         }
-        const label = singleLine(option["label"], `option ${index} label`, LIMITS.label, problems);
-        const consequence = prose(option["consequence"], `option ${index} consequence`, LIMITS.consequence, problems);
-        // Absent is invalid, never defaulted: a defaulted reversibility is a
-        // guess wearing a schema, and reversible=false is the field the
-        // scheduler's refusal to auto-apply rests on.
-        if (typeof option["reversible"] !== "boolean") {
-            problems.push({
-                reason: "missing-reversible",
-                message: `option ${index} must say reversible: true or false — unstated is not reversible, it is unstated`,
-            });
-            sound = false;
-        }
-        if (label === null || consequence === null) {
-            sound = false;
-            return;
-        }
-        if (sound) {
-            options.push({
-                id: id,
-                label,
-                consequence,
-                reversible: option["reversible"],
-            });
-        }
+        text(option["label"], `options[${index}].label`, `option-${index}-label`, true);
+        text(option["consequence"], `options[${index}].consequence`, `option-${index}-consequence`, false);
     });
-    return sound && options.length === value.length ? options : null;
-}
-function prose(value, field, cap, problems) {
-    if (typeof value !== "string" || value.trim() === "") {
-        problems.push({ reason: `missing-${slug(field)}`, message: `${field} is required` });
-        return null;
+    const recommendation = body["recommendation"];
+    if (typeof recommendation === "string" && !touched(contract, "recommendation") && !touched(contract, "options") && !options.some(option => typeof option === "object" && option !== null && option["id"] === recommendedId(recommendation))) {
+        problems.push({ reason: "bad-recommendation", message: `recommendation: "${truncate(recommendation, 60)}" does not match any option id` });
     }
-    if (value.length > cap) {
-        problems.push({ reason: `${slug(field)}-too-long`, message: `${field} is over ${cap} characters` });
-        return null;
-    }
-    if (FORBIDDEN_MULTILINE.test(value)) {
-        problems.push({
-            reason: `${slug(field)}-control-characters`,
-            message: `${field} contains control characters — text only`,
-        });
-        return null;
+    if (body["assignee"] !== null)
+        text(body["assignee"], "assignee", "assignee", true);
+    const deadline = body["deadline"];
+    if (typeof deadline === "string" && !touched(contract, "deadline") && Number.isNaN(Date.parse(deadline))) {
+        problems.push({ reason: "bad-deadline", message: `deadline: must be an ISO 8601 timestamp (got ${describe(deadline)})` });
     }
-    return value.trim();
+    return problems;
 }
-function singleLine(value, field, cap, problems) {
-    if (typeof value !== "string" || value.trim() === "") {
-        problems.push({ reason: `missing-${slug(field)}`, message: `${field} is required` });
-        return null;
-    }
-    if (value.length > cap) {
-        problems.push({ reason: `${slug(field)}-too-long`, message: `${field} is over ${cap} characters` });
-        return null;
-    }
-    if (FORBIDDEN_SINGLE_LINE.test(value)) {
-        problems.push({
-            reason: `${slug(field)}-control-characters`,
-            message: `${field} must be one line with no control characters`,
-        });
-        return null;
-    }
-    return value.trim();
+/** The option id a recommendation names: a bare id, or the id before the first ":" in "<id>: why". */
+function recommendedId(recommendation) {
+    const colon = recommendation.indexOf(":");
+    return (colon === -1 ? recommendation : recommendation.slice(0, colon)).trim();
 }
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
 }
-function slug(field) {
-    return field.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
-}
 function describe(value) {
     if (value === undefined)
         return "nothing";

package/dist/desktop-update.d.ts

@@ -125,20 +125,20 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {