things-api 0.17.0 → 0.19.0

package/dist/write/param-schema.js

@@ -0,0 +1,747 @@
+/**
+ * The ONE per-operation PARAMETER schema registry — the structural contract every
+ * untyped entry point (batch JSONL, MCP `run_operation`/`batch`, a JavaScript
+ * caller handing over parsed JSON) is held to BEFORE anything is dispatched.
+ *
+ * Why it exists (#580): the engine used to duck-test its own params — `todo.add`
+ * asked whether `params.project` LOOKED like a container (`.uuid`/`.title`
+ * present) and, when a bare uuid STRING was supplied instead, concluded the field
+ * was ABSENT. No `list-id` compiled, no destination assertion was emitted, the
+ * to-do landed in the Inbox, verification passed against the (empty) delta, and
+ * the batch reported success. Malformed input degraded silently into a different,
+ * plausible-looking mutation. The same genus lurks anywhere a shape is inferred
+ * rather than asserted, so the fix is structural: ONE registry, checked at the
+ * two choke points (the batch's static preflight and the mutation pipeline), and
+ * duck tests downgraded to belt-and-braces throws.
+ *
+ * Doctrine (decisions.md 2026-08-17, #491 RRF1 — the exhaustive-map law): the
+ * registry is EXHAUSTIVE on both axes. `PARAM_SCHEMAS` is a
+ * `{ [K in OperationKind]: … }`, so a new operation breaks compilation until it
+ * declares a schema; each op's schema is a `{ [F in keyof Params]-?: FieldSpec }`,
+ * so a new parameter breaks compilation until its shape is consciously named.
+ * Neither axis can be satisfied by an out-of-date literal.
+ *
+ * Hand-written, zero-dependency validation in the style of
+ * [repeat-rule.ts](./repeat-rule.ts) — NO zod. zod is a consumer-surface
+ * dependency confined to `src/mcp/server.ts` (the CLI guest bundle ships neither
+ * it nor the MCP SDK; see the lazy loader in `src/index.ts`).
+ *
+ * The contract:
+ *  - a REQUIRED field must be present and the right shape; absent or `null` is a
+ *    structural error;
+ *  - an OPTIONAL field may be absent, explicitly `null`, or the right shape —
+ *    any other type is a structural error (never a silent "treat as absent");
+ *  - UNKNOWN keys are refused by name (a typo is never silently dropped);
+ *  - a container reference is an OBJECT (`{"uuid": …}` / `{"title": …}`) — a bare
+ *    string is refused with steering copy rather than normalized. One canonical
+ *    shape (ALPHA-CONTRACT: no shorthand alias machinery pre-1.0).
+ *
+ * The check is purely STRUCTURAL. It says nothing about whether a uuid exists,
+ * whether two fields contradict each other (that stays with each command's
+ * `preRead`), or whether a `"$name"` batch temp-reference is declared (that stays
+ * with the batch's own `staticRefError`) — so `$`-prefixed strings pass every
+ * plain-string field and every container `uuid`, as they must.
+ */
+import { OPERATION_KINDS, WEEKDAYS, } from "./operations.js";
+import { assertEndsBound, assertMonthlyAnchor } from "./repeat-rule.js";
+const str = (describe = "a non-empty string") => ({
+    kind: "string",
+    optional: false,
+    nonEmpty: true,
+    describe,
+});
+/** A string field that legitimately accepts "" (free text: notes). */
+const text = (describe = "a string") => ({ kind: "string", optional: false, describe });
+const bool = (describe = "true or false") => ({
+    kind: "boolean",
+    optional: false,
+    describe,
+});
+const int = (min, max, describe) => ({
+    kind: "number",
+    optional: false,
+    integer: true,
+    min,
+    max,
+    describe: describe ?? `a whole number ${min}–${max}`,
+});
+const strArray = (describe = "an array of non-empty strings") => ({
+    kind: "stringArray",
+    optional: false,
+    describe,
+});
+const enumOf = (values) => ({
+    kind: "enum",
+    optional: false,
+    values,
+    describe: `one of ${values.join(" | ")}`,
+});
+const container = () => ({
+    kind: "container",
+    optional: false,
+    describe: 'a container reference object — {"uuid": "…"} or {"title": "…"}',
+});
+const custom = (describe, validate) => ({
+    kind: "custom",
+    optional: false,
+    describe,
+    validate,
+});
+/** Mark a spec optional (absent or `null` accepted). */
+const opt = (spec) => ({ ...spec, optional: true });
+// --------------------------------------------------------------- type naming
+/** The received-type half of a refusal, in the words a caller reading JSON uses. */
+export function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    switch (typeof value) {
+        case "string":
+            return "a string";
+        case "number":
+            return "a number";
+        case "boolean":
+            return "a boolean";
+        case "object":
+            return "an object";
+        default:
+            return typeof value;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// --------------------------------------------------------- shared field specs
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2})?)?$/;
+const REMINDER_RE = /^\d{1,2}:\d{2}$/;
+const WHEN_KEYWORDS = ["today", "evening", "anytime", "someday"];
+/**
+ * A scheduling value: a list keyword or a concrete `YYYY-MM-DD`. The wording
+ * matches `whenAssertions` (update-fields.ts) verbatim — the two check the same
+ * grammar at different depths and must not speak with two voices.
+ */
+const WHEN_EXPECTED = "today | evening | anytime | someday | YYYY-MM-DD";
+const whenValue = () => custom(WHEN_EXPECTED, (value, path) => {
+    if (typeof value !== "string") {
+        return `${path}: expected ${WHEN_EXPECTED} — received ${describeType(value)}`;
+    }
+    if (WHEN_KEYWORDS.includes(value) || ISO_DATE_RE.test(value))
+        return null;
+    return value.includes("@")
+        ? `${path}: a reminder time is a separate parameter (reminder: "HH:mm"; CLI --reminder), not an @ suffix — received "${value}"`
+        : `${path}: expected ${WHEN_EXPECTED} — received "${value}"`;
+});
+const isoDate = () => custom("a date (YYYY-MM-DD)", (value, path) => typeof value === "string" && ISO_DATE_RE.test(value)
+    ? null
+    : `${path}: expected a date (YYYY-MM-DD) — received ${typeof value === "string" ? `"${value}"` : describeType(value)}`);
+const timestamp = () => custom("a date (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:mm)", (value, path) => typeof value === "string" && TIMESTAMP_RE.test(value)
+    ? null
+    : `${path}: expected a date (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:mm) — received ${typeof value === "string" ? `"${value}"` : describeType(value)}`);
+const reminderTime = () => custom("a time of day (HH:mm, 24-hour)", (value, path) => typeof value === "string" && REMINDER_RE.test(value)
+    ? null
+    : `${path}: expected a time of day (HH:mm, 24-hour) — received ${typeof value === "string" ? `"${value}"` : describeType(value)}`);
+/** An array of distinct weekday names (weekly rules). */
+const weekdayArray = () => custom(`an array of weekday names (${WEEKDAYS.join(" | ")})`, (value, path) => {
+    if (!Array.isArray(value)) {
+        return `${path}: expected an array of weekday names — received ${describeType(value)}`;
+    }
+    for (let i = 0; i < value.length; i++) {
+        const day = value[i];
+        if (typeof day !== "string" || !WEEKDAYS.includes(day)) {
+            return `${path}[${i}]: expected one of ${WEEKDAYS.join(" | ")} — received ${typeof day === "string" ? `"${day}"` : describeType(day)}`;
+        }
+    }
+    return null;
+});
+/** Wrap a throwing engine validator (repeat-rule.ts) as a schema `custom`. */
+function wrapThrowing(fn, path) {
+    try {
+        fn();
+        return null;
+    }
+    catch (err) {
+        return `${path}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/** Refuse keys outside a CLOSED nested bag. */
+function unknownNestedKey(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (value[key] === undefined)
+            continue;
+        if (!allowed.includes(key)) {
+            return `${path}.${key}: not a recognized field here — accepted fields are ${allowed.join(", ")}`;
+        }
+    }
+    return null;
+}
+/** MONTHLY anchor: a day-of-month OR an nth-weekday, never a bag holding both. */
+const monthlyAnchor = () => custom('a day-of-month anchor {"day": 1–31 | "last"} or an nth-weekday anchor {"weekday": …, "ordinal": 1–5 | "last"}', (value, path) => {
+    if (!isRecord(value)) {
+        return `${path}: expected a day-of-month or nth-weekday anchor object — received ${describeType(value)}`;
+    }
+    const unknown = unknownNestedKey(value, ["day", "weekday", "ordinal"], path);
+    if (unknown !== null)
+        return unknown;
+    return wrapThrowing(() => assertMonthlyAnchor(value, "the anchor"), path);
+});
+/** YEARLY anchor: a month plus the monthly-style day anchor. */
+const yearlyAnchor = () => custom('a month plus a day anchor — {"month": 1–12, "day": …} or {"month": 1–12, "weekday": …, "ordinal": …}', (value, path) => {
+    if (!isRecord(value)) {
+        return `${path}: expected a month plus a day anchor object — received ${describeType(value)}`;
+    }
+    const unknown = unknownNestedKey(value, ["month", "day", "weekday", "ordinal"], path);
+    if (unknown !== null)
+        return unknown;
+    const month = value["month"];
+    if (!Number.isInteger(month) || month < 1 || month > 12) {
+        return `${path}.month: expected a whole number 1–12 — received ${describeType(month)}`;
+    }
+    return wrapThrowing(() => assertMonthlyAnchor(value, "the anchor"), path);
+});
+/** The "Ends" bound: a discriminated {kind} bag. */
+const endsBound = () => custom('{"kind": "never"} | {"kind": "on-date", "date": "YYYY-MM-DD"} | {"kind": "after", "count": 1–999}', (value, path) => {
+    if (!isRecord(value)) {
+        return `${path}: expected an end-bound object — received ${describeType(value)}`;
+    }
+    const kind = value["kind"];
+    if (kind !== "never" && kind !== "on-date" && kind !== "after") {
+        return `${path}.kind: expected one of never | on-date | after — received ${typeof kind === "string" ? `"${kind}"` : describeType(kind)}`;
+    }
+    const allowed = kind === "on-date" ? ["kind", "date"] : kind === "after" ? ["kind", "count"] : ["kind"];
+    const unknown = unknownNestedKey(value, allowed, path);
+    if (unknown !== null)
+        return unknown;
+    if (kind === "on-date" && typeof value["date"] !== "string") {
+        return `${path}.date: expected a date (YYYY-MM-DD) — received ${describeType(value["date"])}`;
+    }
+    if (kind === "after" && typeof value["count"] !== "number") {
+        return `${path}.count: expected a whole number 1–999 — received ${describeType(value["count"])}`;
+    }
+    return wrapThrowing(() => assertEndsBound(value), path);
+});
+/** Heading placement: exactly one of a position keyword, a `before`, or an `after` anchor. */
+const headingPlacement = () => custom('{"position": "first" | "last"} | {"before": "<heading>"} | {"after": "<heading>"}', (value, path) => {
+    if (!isRecord(value)) {
+        return `${path}: expected a placement object — received ${describeType(value)}`;
+    }
+    const unknown = unknownNestedKey(value, ["position", "before", "after"], path);
+    if (unknown !== null)
+        return unknown;
+    const forms = ["position", "before", "after"].filter((k) => value[k] !== undefined && value[k] !== null);
+    if (forms.length !== 1) {
+        return forms.length === 0
+            ? `${path}: expected exactly one of position, before, after — received an object naming none of them`
+            : `${path}: expected exactly one of position, before, after — received an object naming ${forms.join(" and ")}`;
+    }
+    const only = forms[0];
+    const v = value[only];
+    if (only === "position") {
+        if (v !== "first" && v !== "last") {
+            return `${path}.position: expected first | last — received ${typeof v === "string" ? `"${v}"` : describeType(v)}`;
+        }
+        return null;
+    }
+    if (typeof v !== "string" || v.length === 0) {
+        return `${path}.${only}: expected a non-empty string naming a heading — received ${describeType(v)}`;
+    }
+    return null;
+});
+/** `todo.replace-checklist` items: plain titles, or `{title, completed?}` bags. */
+const checklistItems = () => custom('an array of titles, or {"title": "…", "completed": true|false} objects', (value, path) => {
+    if (!Array.isArray(value)) {
+        return `${path}: expected an array of checklist items — received ${describeType(value)}`;
+    }
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        const at = `${path}[${i}]`;
+        if (typeof item === "string") {
+            if (item.length === 0)
+                return `${at}: expected a non-empty title — received an empty string`;
+            continue;
+        }
+        if (!isRecord(item)) {
+            return `${at}: expected a title string or a {"title": "…"} object — received ${describeType(item)}`;
+        }
+        const unknown = unknownNestedKey(item, ["title", "completed"], at);
+        if (unknown !== null)
+            return unknown;
+        if (typeof item["title"] !== "string" || item["title"].length === 0) {
+            return `${at}.title: expected a non-empty string — received ${describeType(item["title"])}`;
+        }
+        if (item["completed"] !== undefined && typeof item["completed"] !== "boolean") {
+            return `${at}.completed: expected true or false — received ${describeType(item["completed"])}`;
+        }
+    }
+    return null;
+});
+/** `project.add` structured items: ordered `to-do` / `heading` nodes. */
+const projectItems = () => custom('an ordered array of {"kind": "to-do" | "heading", "title": "…"} nodes', (value, path) => {
+    if (!Array.isArray(value)) {
+        return `${path}: expected an array of project items — received ${describeType(value)}`;
+    }
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        const at = `${path}[${i}]`;
+        if (!isRecord(item)) {
+            return `${at}: expected a {"kind": "to-do" | "heading", "title": "…"} object — received ${describeType(item)}`;
+        }
+        const kind = item["kind"];
+        if (kind !== "to-do" && kind !== "heading") {
+            return `${at}.kind: expected to-do | heading — received ${typeof kind === "string" ? `"${kind}"` : describeType(kind)}`;
+        }
+        const allowed = kind === "heading"
+            ? ["kind", "title"]
+            : ["kind", "title", "notes", "when", "deadline", "tags", "checklistItems"];
+        const unknown = unknownNestedKey(item, allowed, at);
+        if (unknown !== null)
+            return unknown;
+        if (typeof item["title"] !== "string" || item["title"].length === 0) {
+            return `${at}.title: expected a non-empty string — received ${describeType(item["title"])}`;
+        }
+        if (kind === "heading")
+            continue;
+        const childSpecs = {
+            notes: opt(text()),
+            when: opt(whenValue()),
+            deadline: opt(isoDate()),
+            tags: opt(strArray()),
+            checklistItems: opt(strArray()),
+        };
+        for (const [key, spec] of Object.entries(childSpecs)) {
+            const error = checkField(spec, item[key], `${at}.${key}`);
+            if (error !== null)
+                return error;
+        }
+    }
+    return null;
+});
+// ------------------------------------------------------------- the value check
+/** Validate ONE field value against its spec; null when well-shaped. */
+function checkField(spec, value, path) {
+    if (value === undefined || value === null) {
+        if (spec.optional)
+            return null;
+        return `${path}: required — expected ${spec.describe}, but the field is ${value === null ? "null" : "missing"}`;
+    }
+    switch (spec.kind) {
+        case "unvalidated":
+            return null;
+        case "string": {
+            if (typeof value !== "string") {
+                return `${path}: expected ${spec.describe} — received ${describeType(value)}`;
+            }
+            if (spec.nonEmpty === true && value.length === 0) {
+                return `${path}: expected ${spec.describe} — received an empty string`;
+            }
+            return null;
+        }
+        case "boolean":
+            return typeof value === "boolean"
+                ? null
+                : `${path}: expected ${spec.describe} — received ${describeType(value)}`;
+        case "number": {
+            if (typeof value !== "number" || Number.isNaN(value)) {
+                return `${path}: expected ${spec.describe} — received ${describeType(value)}`;
+            }
+            if (spec.integer === true && !Number.isInteger(value)) {
+                return `${path}: expected ${spec.describe} — received ${value}`;
+            }
+            if ((spec.min !== undefined && value < spec.min) ||
+                (spec.max !== undefined && value > spec.max)) {
+                return `${path}: expected ${spec.describe} — received ${value}`;
+            }
+            return null;
+        }
+        case "stringArray": {
+            if (!Array.isArray(value)) {
+                return `${path}: expected ${spec.describe} — received ${describeType(value)}`;
+            }
+            for (let i = 0; i < value.length; i++) {
+                const el = value[i];
+                if (typeof el !== "string") {
+                    return `${path}[${i}]: expected a non-empty string — received ${describeType(el)}`;
+                }
+                if (el.length === 0) {
+                    return `${path}[${i}]: expected a non-empty string — received an empty string`;
+                }
+            }
+            return null;
+        }
+        case "enum": {
+            const values = spec.values ?? [];
+            if (typeof value !== "string" || !values.includes(value)) {
+                return `${path}: expected ${spec.describe} — received ${typeof value === "string" ? `"${value}"` : describeType(value)}`;
+            }
+            return null;
+        }
+        case "container":
+            return checkContainer(value, path);
+        case "custom":
+            return spec.validate?.(value, path) ?? null;
+        default: {
+            const exhaustive = spec.kind;
+            return `${path}: unhandled field kind ${String(exhaustive)}`;
+        }
+    }
+}
+/**
+ * A container reference is an OBJECT. A bare string — the #580 shape — is refused
+ * with the object spelling it should have used; it is NOT normalized, because one
+ * canonical shape is the whole point (a shorthand alias would put the silent
+ * degradation back, just one layer up).
+ */
+function checkContainer(value, path) {
+    const expected = 'a container reference object — {"uuid": "…"} or {"title": "…"}';
+    if (typeof value === "string") {
+        return (`${path}: expected ${expected} — received a string; to reference it by uuid ` +
+            `(or by a batch $ref), use {"uuid": ${JSON.stringify(value)}}`);
+    }
+    if (!isRecord(value)) {
+        return `${path}: expected ${expected} — received ${describeType(value)}`;
+    }
+    const unknown = unknownNestedKey(value, ["uuid", "title"], path);
+    if (unknown !== null)
+        return unknown;
+    const uuid = value["uuid"];
+    const title = value["title"];
+    if (uuid === undefined && title === undefined) {
+        return `${path}: expected ${expected} — received an object naming neither`;
+    }
+    for (const [key, v] of [
+        ["uuid", uuid],
+        ["title", title],
+    ]) {
+        if (v === undefined)
+            continue;
+        if (typeof v !== "string") {
+            return `${path}.${key}: expected a non-empty string — received ${describeType(v)}`;
+        }
+        if (v.length === 0) {
+            return `${path}.${key}: expected a non-empty string — received an empty string`;
+        }
+    }
+    // A `$name` temp-ref is a legal uuid VALUE here; whether it is DECLARED is the
+    // batch preflight's question (staticRefError), not this one's.
+    return null;
+}
+/** `{ uuid }` — the shape most verbs take. */
+const UUID_ONLY = { uuid: str("an item uuid") };
+/** The update vocabulary shared by `todo.update` and `project.update`. */
+const UPDATE_FIELDS = {
+    title: opt(str()),
+    notes: opt(text()),
+    appendNotes: opt(text()),
+    prependNotes: opt(text()),
+    when: opt(whenValue()),
+    reminder: opt(reminderTime()),
+    deadline: opt(isoDate()),
+};
+/** The calendar-anchor rule vocabulary carried inline by the add-repeating composites. */
+const ADD_REPEATING_RULE = {
+    frequency: enumOf(["daily", "weekly", "monthly", "yearly"]),
+    interval: int(1, 99, "a whole number 1–99"),
+    afterCompletion: opt(bool()),
+    weekdays: opt(weekdayArray()),
+    monthly: opt(monthlyAnchor()),
+    yearly: opt(yearlyAnchor()),
+    ends: opt(endsBound()),
+};
+const REPEAT_RULE = {
+    uuid: str("an item uuid"),
+    ...ADD_REPEATING_RULE,
+    reminder: opt(reminderTime()),
+    deadline: opt(bool("true or false (deadline the spawned occurrences)")),
+    startDaysEarlier: opt(int(0, 366, "a whole number of days ≥ 0")),
+    next: opt(isoDate()),
+};
+const SET_DATES = {
+    uuid: str("an item uuid"),
+    completedAt: opt(timestamp()),
+    createdAt: opt(timestamp()),
+};
+const NAME_OR_UUID = { target: str("a uuid or a unique title") };
+const CLONE = {
+    uuid: str("an item uuid"),
+    title: opt(str()),
+    preserveCreated: opt(bool()),
+};
+const SET_TAGS = {
+    uuid: str("an item uuid"),
+    tags: strArray("an array of tag titles (an empty array clears all tags)"),
+};
+/** No parameters at all — any key is unknown. */
+const NO_PARAMS = {};
+const REORDER_SCOPES = [
+    "today",
+    "evening",
+    "project",
+    "area",
+    "inbox",
+    "someday",
+    "projects",
+    "heading",
+    "area-someday",
+    "anytime",
+    "container-day",
+    "day",
+    "heading-someday",
+    "tomorrow",
+    "upcoming",
+];
+/**
+ * The registry. EXHAUSTIVE on both axes by construction: a new
+ * {@link OperationKind} breaks compilation here, and a new parameter on any
+ * operation breaks compilation in that operation's entry.
+ */
+export const PARAM_SCHEMAS = {
+    "todo.add": {
+        title: str(),
+        notes: opt(text()),
+        when: opt(whenValue()),
+        reminder: opt(reminderTime()),
+        deadline: opt(isoDate()),
+        tags: opt(strArray("an array of tag titles")),
+        checklistItems: opt(strArray("an array of checklist item titles")),
+        project: opt(container()),
+        area: opt(container()),
+        heading: opt(str("a heading title inside the destination project")),
+        createdAt: opt(timestamp()),
+        completedAt: opt(timestamp()),
+    },
+    "todo.update": { uuid: str("an item uuid"), ...UPDATE_FIELDS },
+    "todo.complete": UUID_ONLY,
+    "todo.cancel": UUID_ONLY,
+    "todo.reopen": UUID_ONLY,
+    "todo.move": {
+        uuid: str("an item uuid"),
+        project: opt(container()),
+        area: opt(container()),
+        heading: opt(str("a heading title inside the destination project")),
+        inbox: opt(bool()),
+        noHeading: opt(bool()),
+        loose: opt(bool()),
+    },
+    "todo.set-tags": SET_TAGS,
+    "todo.replace-checklist": { uuid: str("an item uuid"), items: checklistItems() },
+    "todo.edit-checklist-item": {
+        uuid: str("an item uuid"),
+        action: enumOf(["add", "remove", "check", "uncheck", "rename", "move"]),
+        title: opt(str()),
+        index: opt(int(1, 10_000, "a whole number ≥ 1 (1-based position)")),
+        at: opt(int(1, 10_000, "a whole number ≥ 1 (1-based position)")),
+        to: opt(int(1, 10_000, "a whole number ≥ 1 (1-based position)")),
+        newTitle: opt(str()),
+    },
+    "todo.delete": UUID_ONLY,
+    "project.add": {
+        title: str(),
+        notes: opt(text()),
+        area: opt(container()),
+        when: opt(whenValue()),
+        deadline: opt(isoDate()),
+        todos: opt(strArray("an array of child to-do titles")),
+        items: opt(projectItems()),
+        createdAt: opt(timestamp()),
+        completedAt: opt(timestamp()),
+    },
+    "project.update": { uuid: str("a project uuid or unique title"), ...UPDATE_FIELDS },
+    "project.complete": {
+        uuid: str("a project uuid or unique title"),
+        children: enumOf(["require-resolved", "auto-complete"]),
+    },
+    "project.delete": { uuid: str("a project uuid or unique title") },
+    "area.add": { title: str(), tags: opt(strArray("an array of tag titles")) },
+    "area.delete": NAME_OR_UUID,
+    "tag.add": { title: str(), parent: opt(str("an existing parent tag title")) },
+    "tag.delete": NAME_OR_UUID,
+    "trash.empty": NO_PARAMS,
+    reorder: {
+        scope: enumOf(REORDER_SCOPES),
+        container: opt(container()),
+        uuids: strArray("an array of item uuids, top-first"),
+        named: opt(strArray("an array of item uuids (a subset of uuids)")),
+        strategy: opt(enumOf(["native", "bounce"])),
+    },
+    "todo.duplicate": UUID_ONLY,
+    "area.update": {
+        target: str("a uuid or a unique title"),
+        title: opt(str()),
+        tags: opt(strArray("an array of existing tag titles")),
+    },
+    "tag.update": {
+        target: str("a uuid or a unique title"),
+        title: opt(str()),
+        parent: opt(str("an existing parent tag title")),
+        unnest: opt(bool()),
+        shortcut: opt(str("a single character")),
+        clearShortcut: opt(bool()),
+    },
+    "project.move": {
+        uuid: str("a project uuid or unique title"),
+        area: opt(container()),
+        noArea: opt(bool()),
+    },
+    "todo.restore": UUID_ONLY,
+    "project.duplicate": { uuid: str("a project uuid or unique title") },
+    "project.cancel": {
+        uuid: str("a project uuid or unique title"),
+        children: enumOf(["require-resolved", "auto-cancel"]),
+    },
+    "project.reopen": { uuid: str("a project uuid or unique title") },
+    "project.restore": { uuid: str("a project uuid or unique title") },
+    "project.set-tags": {
+        uuid: str("a project uuid or unique title"),
+        tags: strArray("an array of tag titles (an empty array clears all tags)"),
+    },
+    "todo.set-dates": SET_DATES,
+    "project.set-dates": SET_DATES,
+    "project.add-heading": { project: container(), title: str() },
+    "project.rename-heading": { uuid: str("a heading uuid"), title: str() },
+    "project.archive-heading": {
+        uuid: str("a heading uuid"),
+        children: opt(enumOf(["complete", "cancel", "reparent"])),
+    },
+    "project.unarchive-heading": { uuid: str("a heading uuid"), restoreChildren: opt(bool()) },
+    "project.promote-heading": { uuid: str("a heading uuid") },
+    "project.move-heading": {
+        project: container(),
+        headings: strArray("an array of heading uuids, in the order they should land"),
+        placement: headingPlacement(),
+    },
+    "project.move-heading-to-project": {
+        project: container(),
+        heading: str("a heading title or uuid inside the source project"),
+        toProject: container(),
+    },
+    "project.dissolve-heading": { uuid: str("a heading uuid") },
+    "todo.clear-dated-reminder": UUID_ONLY,
+    "todo.make-repeating": REPEAT_RULE,
+    "todo.reschedule-repeat": REPEAT_RULE,
+    "todo.pause-repeat": UUID_ONLY,
+    "todo.resume-repeat": UUID_ONLY,
+    "todo.create-next-copy": UUID_ONLY,
+    "todo.convert-to-project": UUID_ONLY,
+    "project.reschedule-repeat": REPEAT_RULE,
+    "project.pause-repeat": { uuid: str("a project uuid or unique title") },
+    "project.resume-repeat": { uuid: str("a project uuid or unique title") },
+    "area.reorder": {
+        target: str("an area uuid or unique title"),
+        before: opt(str("an area uuid or unique title")),
+        after: opt(str("an area uuid or unique title")),
+        position: opt(enumOf(["first", "last"])),
+    },
+    "project.make-repeating": REPEAT_RULE,
+    "project.add-repeating": {
+        ...ADD_REPEATING_RULE,
+        title: str(),
+        notes: opt(text()),
+        area: opt(container()),
+        when: opt(whenValue()),
+        deadline: opt(isoDate()),
+        todos: opt(strArray("an array of child to-do titles")),
+        items: opt(projectItems()),
+        createdAt: opt(timestamp()),
+    },
+    "todo.add-repeating": {
+        ...ADD_REPEATING_RULE,
+        title: str(),
+        notes: opt(text()),
+        when: opt(whenValue()),
+        reminder: opt(reminderTime()),
+        deadline: opt(isoDate()),
+        startDaysEarlier: opt(int(0, 366, "a whole number of days ≥ 0")),
+        tags: opt(strArray("an array of tag titles")),
+        checklistItems: opt(strArray("an array of checklist item titles")),
+        project: opt(container()),
+        area: opt(container()),
+        heading: opt(str("a heading title inside the destination project")),
+        createdAt: opt(timestamp()),
+    },
+    "todo.clone": CLONE,
+    "project.clone": CLONE,
+    "log-now": NO_PARAMS,
+};
+// ------------------------------------------------------------------ the check
+/**
+ * The STRUCTURAL parameter check for one operation. Returns the FIRST refusal
+ * detail (JSON path · expected shape · received type), or null when the bag is
+ * well-shaped. Never throws; never mutates or normalizes the params.
+ */
+export function validateOperationParams(op, params) {
+    if (!isRecord(params)) {
+        return `params: expected an object of operation parameters — received ${describeType(params)}`;
+    }
+    const schema = PARAM_SCHEMAS[op];
+    const known = Object.keys(PARAM_SCHEMAS[op]);
+    for (const key of Object.keys(params)) {
+        if (params[key] === undefined)
+            continue;
+        if (!Object.hasOwn(schema, key)) {
+            return known.length === 0
+                ? `params.${key}: "${op}" takes no parameters — nothing was applied for this field`
+                : `params.${key}: not a parameter of "${op}" — accepted parameters are ${known.join(", ")}`;
+        }
+    }
+    for (const key of known) {
+        const spec = schema[key];
+        if (spec === undefined)
+            continue;
+        const error = checkField(spec, params[key], `params.${key}`);
+        if (error !== null)
+            return error;
+    }
+    return null;
+}
+/** A structural parameter refusal — an input-contract error, never an app failure. */
+export class ParamSchemaError extends RangeError {
+    /** The operation whose parameter bag was refused. */
+    op;
+    constructor(op, detail) {
+        super(detail);
+        this.name = "ParamSchemaError";
+        this.op = op;
+    }
+}
+/** {@link validateOperationParams}, as a throwing assertion for the pipeline. */
+export function assertOperationParams(op, params) {
+    const detail = validateOperationParams(op, params);
+    if (detail !== null)
+        throw new ParamSchemaError(op, detail);
+}
+/**
+ * The per-op parameter summary `things capabilities` publishes, so the promise
+ * that the catalog carries "operation kinds AND their parameter shapes" is met by
+ * data rather than by prose.
+ */
+export function paramSummary(op) {
+    const schema = PARAM_SCHEMAS[op];
+    return Object.entries(schema).map(([name, spec]) => {
+        const row = {
+            name,
+            kind: spec.kind,
+            optional: spec.optional,
+            expects: spec.describe,
+        };
+        if (spec.values !== undefined)
+            row.values = spec.values;
+        return row;
+    });
+}
+/** Runtime completeness law: every cataloged operation declares a schema. */
+export function operationsMissingSchema() {
+    return OPERATION_KINDS.filter((op) => !Object.hasOwn(PARAM_SCHEMAS, op));
+}
+/** Every `unvalidated` escape in the registry, with its written reason (currently none). */
+export function unvalidatedFields() {
+    const out = [];
+    for (const op of OPERATION_KINDS) {
+        for (const [field, spec] of Object.entries(PARAM_SCHEMAS[op])) {
+            if (spec.kind === "unvalidated")
+                out.push({ op, field, reason: spec.reason ?? "" });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=param-schema.js.map