things-api 0.18.0 → 0.19.0

package/dist/write/lock.d.ts

@@ -1,16 +1,3 @@
-/**
- * Advisory mutation lockfile: serializes mutations across concurrent CLI
- * invocations so create-probe verification is never ambiguous (design §4).
- * Stale locks (dead pid) are stolen; live locks are awaited with backoff.
- *
- * The steal is atomic: a stealer `rename`s the stale lockfile to a private
- * temp name (rename succeeds for exactly one racer; every other racer gets
- * ENOENT and falls back to the wait/retry loop), then re-reads the renamed
- * file to confirm the holder is still dead before discarding it. This closes
- * the TOCTOU window an unconditional unlink+recreate would leave open, where
- * two processes could both observe a dead holder and both end up believing
- * they hold the lock.
- */
 import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 export declare class MutationLockError extends Error {
     constructor(message: string);
@@ -18,6 +5,22 @@ export declare class MutationLockError extends Error {
 export interface MutationLock {
     release(): void;
 }
+/** True when an enclosing composite already holds `path` on this async context. */
+export declare function mutationLockHeld(path: string): boolean;
+/**
+ * Run `body` holding ONE mutation lock for its whole duration — the COMPOSITE
+ * scope. Every {@link acquireMutationLock} reached from inside (each leg, and
+ * any nested composite) is a reentrant no-op, so the composite serializes
+ * against other writers as a WHOLE rather than leg by leg.
+ *
+ * Already inside a hold on the same path (a composite invoked as another
+ * composite's leg): `body` runs directly on the enclosing hold — never a second
+ * acquisition, which would deadlock against its own holder.
+ *
+ * Throws {@link MutationLockError} if the lock cannot be taken, exactly as the
+ * per-leg acquisition does; the caller shapes that into its own refusal.
+ */
+export declare function withMutationLock<T>(path: string, body: () => Promise<T>, options?: AcquireMutationLockOptions): Promise<T>;
 /**
  * Injectable filesystem + environment seam. Production uses the real node:fs
  * calls; unit tests substitute this to drive the concurrent steal paths

package/dist/write/lock.js

@@ -10,7 +10,17 @@
  * the TOCTOU window an unconditional unlink+recreate would leave open, where
  * two processes could both observe a dead holder and both end up believing
  * they hold the lock.
+ *
+ * SCOPE (2026-08-23): the lock has two scopes, not one. The base case is
+ * PER-LEG — one mutation, acquired and released by the pipeline. A COMPOSITE (a
+ * single verb the engine executes as several mutations — the promote verbs run
+ * clone → trash → promote) instead holds ONE lock across all of its legs via
+ * {@link withMutationLock}, and its legs' own acquisitions become reentrant
+ * no-ops. Without that, two concurrent composites interleave at leg boundaries
+ * — A's clone, B's clone, A's promote — and no single-writer guarantee survives
+ * the whole verb.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 export class MutationLockError extends Error {
@@ -28,6 +38,45 @@ function pidAlive(pid) {
         return false;
     }
 }
+/**
+ * The composite hold, carried on the ASYNC CONTEXT rather than threaded through
+ * every call site. `AsyncLocalStorage` is what makes the reentrancy correctly
+ * COMPOSITE-scoped instead of process-scoped: a leg reached from inside a
+ * composite inherits the store and recognizes the hold, while a genuinely
+ * concurrent composite in the same process (two parallel MCP tool calls) runs in
+ * its OWN context, sees no store, and is excluded exactly as a second process
+ * would be. A process-wide "we hold it" flag would have let those two interleave
+ * silently — the very thing this scoping exists to stop.
+ */
+const compositeHold = new AsyncLocalStorage();
+/** True when an enclosing composite already holds `path` on this async context. */
+export function mutationLockHeld(path) {
+    return compositeHold.getStore()?.path === path;
+}
+/**
+ * Run `body` holding ONE mutation lock for its whole duration — the COMPOSITE
+ * scope. Every {@link acquireMutationLock} reached from inside (each leg, and
+ * any nested composite) is a reentrant no-op, so the composite serializes
+ * against other writers as a WHOLE rather than leg by leg.
+ *
+ * Already inside a hold on the same path (a composite invoked as another
+ * composite's leg): `body` runs directly on the enclosing hold — never a second
+ * acquisition, which would deadlock against its own holder.
+ *
+ * Throws {@link MutationLockError} if the lock cannot be taken, exactly as the
+ * per-leg acquisition does; the caller shapes that into its own refusal.
+ */
+export async function withMutationLock(path, body, options = {}) {
+    if (mutationLockHeld(path))
+        return body();
+    const lock = await acquireMutationLock(path, options);
+    try {
+        return await compositeHold.run({ path }, body);
+    }
+    finally {
+        lock.release();
+    }
+}
 let stealCounter = 0;
 function realDeps() {
     return {
@@ -46,6 +95,12 @@ function errCode(err) {
     return err.code;
 }
 export async function acquireMutationLock(path, options = {}) {
+    // REENTRANT under a composite hold (see withMutationLock): the enclosing
+    // composite already owns this lockfile, so a leg neither re-takes it (it would
+    // wait out the timeout against its own holder) nor releases it (the remaining
+    // legs still need it). The composite's own release is the only one.
+    if (mutationLockHeld(path))
+        return { release() { } };
     const waitMs = options.waitMs ?? 30_000;
     const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const deps = options.deps ?? realDeps();

package/dist/write/lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/write/lock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/write/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAOD,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAMD;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAoB,CAAC;AAEhE,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,aAAa,CAAC,QAAQ,EAAE,EAAE,IAAI,KAAK,IAAI,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,IAAsB,EACtB,UAAsC,EAAE;IAExC,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,OAAO,MAAM,aAAa,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAwBD,IAAI,YAAY,GAAG,CAAC,CAAC;AAErB,SAAS,QAAQ;IACf,OAAO;QACL,SAAS;QACT,YAAY;QACZ,aAAa;QACb,UAAU;QACV,UAAU;QACV,QAAQ;QACR,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,YAAY,EAAE,GAAG,EAAE,CACjB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;KAC1G,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,GAAY;IAC3B,OAAQ,GAA6B,CAAC,IAAI,CAAC;AAC7C,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAY,EACZ,UAAsC,EAAE;IAExC,yEAAyE;IACzE,+EAA+E;IAC/E,8EAA8E;IAC9E,oEAAoE;IACpE,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,KAAI,CAAC,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnD,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,OAAO,GAAgB,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAC/D,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,OAAO;gBACL,OAAO;oBACL,IAAI,CAAC;wBACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;oBACxB,CAAC;oBAAC,MAAM,CAAC;wBACP,sBAAsB;oBACxB,CAAC;gBACH,CAAC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YACzC,IAAI,MAAM,GAAuB,IAAI,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAW,CAAgB,CAAC;YAChF,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,IAAI,CAAC,CAAC,8BAA8B;YAC/C,CAAC;YACD,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClD,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC7B,sEAAsE;gBACtE,mEAAmE;gBACnE,oEAAoE;gBACpE,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC3B,MAAM,IAAI,iBAAiB,CACzB,wCAAwC,MAAM,CAAC,GAAG,UAAU,MAAM,CAAC,EAAE,KAAK;oBACxE,UAAU,MAAM,UAAU,IAAI,EAAE,CACnC,CAAC;YACJ,CAAC;YACD,uFAAuF;YACvF,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAc;IACpD,MAAM,IAAI,GAAG,GAAG,IAAI,UAAU,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;IAChE,IAAI,IAAI,CAAC,aAAa;QAAE,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;IACnD,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,+BAA+B;QACtE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,0EAA0E;IAC1E,IAAI,MAAM,GAAuB,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAW,CAAgB,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAC,CAAC,+BAA+B;IAChD,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,2EAA2E;QAC3E,yEAAyE;QACzE,gBAAgB;QAChB,IAAI,CAAC;YACH,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,2DAA2D;QAC7D,CAAC;QACD,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtB,OAAO;IACT,CAAC;IACD,2EAA2E;IAC3E,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAAC,IAAc,EAAE,IAAY;IAC7C,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC"}

package/dist/write/make-repeating-project.js

@@ -75,19 +75,15 @@ export async function promoteProjectViaGui(deps, params, options = {}) {
     if (options.dangerouslyDriveGui !== true && options.dryRun !== true) {
         return blockedUiDrive("project.make-repeating");
     }
-    const driveParams = {
-        uuid,
-        frequency: params.frequency,
-        interval: params.interval,
-        ...(params.afterCompletion !== undefined && { afterCompletion: params.afterCompletion }),
-        ...(params.weekdays !== undefined && { weekdays: params.weekdays }),
-        ...(params.monthly !== undefined && { monthly: params.monthly }),
-        ...(params.yearly !== undefined && { yearly: params.yearly }),
-        ...(params.ends !== undefined && { ends: params.ends }),
-        ...(params.reminder !== undefined && { reminder: params.reminder }),
-        ...(params.deadline !== undefined && { deadline: params.deadline }),
-        ...(params.startDaysEarlier !== undefined && { startDaysEarlier: params.startDaysEarlier }),
-    };
+    // Everything but the uuid rides THROUGH: this bag is re-keyed to the resolved
+    // project uuid, not filtered. `next` (the dialog's first-occurrence field,
+    // ANCH2) was missing from an earlier hand-enumeration, so every project promote
+    // silently took the app's today-anchored default — a dated `project
+    // make-repeating` / `add-repeating --when` landed on the wrong phase and then
+    // failed its own post-drive verify. Spread first, override the uuid, so a new
+    // rule field is carried by default instead of dropped by omission (the RRF1
+    // hand-enumeration class, decisions.md 2026-08-17).
+    const driveParams = { ...params, uuid };
     if (options.dryRun === true) {
         const coercion = tax.kind === "anytime"
             ? `coerce to Someday (update-project?id=${uuid}&when=someday) → verified → `

package/dist/write/make-repeating-project.js.map

@@ -1 +1 @@
-{"version":3,"file":"make-repeating-project.js","sourceRoot":"","sources":["../../src/write/make-repeating-project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"make-repeating-project.js","sourceRoot":"","sources":["../../src/write/make-repeating-project.ts"],"names":[],"mappings":"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"}

package/dist/write/operations.d.ts

@@ -4,7 +4,7 @@
  * per-vector matrices (data, produced by the lab), not here.
  */
 import type { IsoDate, ReminderTime } from "../model/dates.ts";
-export declare const OPERATION_KINDS: readonly ["todo.add", "todo.update", "todo.complete", "todo.cancel", "todo.reopen", "todo.move", "todo.set-tags", "todo.replace-checklist", "todo.edit-checklist-item", "todo.delete", "project.add", "project.update", "project.complete", "project.delete", "area.add", "area.delete", "tag.add", "tag.delete", "trash.empty", "reorder", "todo.duplicate", "area.update", "tag.update", "project.move", "todo.restore", "project.duplicate", "project.cancel", "project.reopen", "project.restore", "project.set-tags", "todo.set-dates", "project.set-dates", "project.add-heading", "project.rename-heading", "project.archive-heading", "project.unarchive-heading", "project.promote-heading", "project.move-heading", "project.move-heading-to-project", "project.dissolve-heading", "todo.clear-dated-reminder", "todo.make-repeating", "todo.reschedule-repeat", "todo.pause-repeat", "todo.resume-repeat", "todo.convert-to-project", "project.reschedule-repeat", "project.pause-repeat", "project.resume-repeat", "area.reorder", "project.make-repeating", "project.add-repeating", "todo.add-repeating", "todo.clone", "project.clone", "log-now"];
+export declare const OPERATION_KINDS: readonly ["todo.add", "todo.update", "todo.complete", "todo.cancel", "todo.reopen", "todo.move", "todo.set-tags", "todo.replace-checklist", "todo.edit-checklist-item", "todo.delete", "project.add", "project.update", "project.complete", "project.delete", "area.add", "area.delete", "tag.add", "tag.delete", "trash.empty", "reorder", "todo.duplicate", "area.update", "tag.update", "project.move", "todo.restore", "project.duplicate", "project.cancel", "project.reopen", "project.restore", "project.set-tags", "todo.set-dates", "project.set-dates", "project.add-heading", "project.rename-heading", "project.archive-heading", "project.unarchive-heading", "project.promote-heading", "project.move-heading", "project.move-heading-to-project", "project.dissolve-heading", "todo.clear-dated-reminder", "todo.make-repeating", "todo.reschedule-repeat", "todo.pause-repeat", "todo.resume-repeat", "todo.create-next-copy", "todo.convert-to-project", "project.reschedule-repeat", "project.pause-repeat", "project.resume-repeat", "area.reorder", "project.make-repeating", "project.add-repeating", "todo.add-repeating", "todo.clone", "project.clone", "log-now"];
 export type OperationKind = (typeof OPERATION_KINDS)[number];
 /**
  * Operations delivered EXCLUSIVELY through the Accessibility GUI ("ui")
@@ -82,8 +82,20 @@ export interface TodoAddParams {
      */
     completedAt?: string;
 }
-export interface TodoUpdateParams {
-    uuid: string;
+/**
+ * The attribute vocabulary of the update verbs — ONE declaration shared by
+ * {@link TodoUpdateParams} and {@link ProjectUpdateParams} (the two carry an
+ * identical field set; the app's `update` / `update-project` URL commands take
+ * the same parameter names).
+ *
+ * It is a MULTI-CONSUMER vocabulary: the URL compilation, the expected-delta
+ * assertions, the undo inverse, and the CLI/MCP patch builders all speak it. Per
+ * the exhaustive-map doctrine (decisions.md 2026-08-17, #491) none of them may
+ * hand-enumerate it — every consumer derives from the exhaustive `Record<keyof
+ * UpdateFields, …>` in [update-fields.ts](./update-fields.ts), so a field added
+ * here breaks compilation until it is consciously handled everywhere.
+ */
+export interface UpdateFields {
     title?: string;
     notes?: string;
     /** Append to the existing notes (newline-joined). Exclusive with notes/prependNotes. */
@@ -92,14 +104,17 @@ export interface TodoUpdateParams {
     prependNotes?: string;
     when?: WhenValue;
     /**
-     * `HH:mm` sets a reminder (requires when: today|evening in the same call);
-     * null clears it (today/evening only — a dated reminder can only be
+     * `HH:mm` sets a reminder (requires when: today|evening|YYYY-MM-DD in the same
+     * call); null clears it (today/evening only — a dated reminder can only be
      * changed, not cleared). When re-scheduling with this OMITTED, an existing
-     * reminder is auto-preserved.
+     * (live) reminder is auto-preserved.
      */
     reminder?: ReminderTime | null;
     deadline?: IsoDate | null;
 }
+export interface TodoUpdateParams extends UpdateFields {
+    uuid: string;
+}
 export interface UuidParams {
     uuid: string;
 }
@@ -310,22 +325,9 @@ export interface ProjectAddParams {
      */
     completedAt?: string;
 }
-export interface ProjectUpdateParams {
+/** Projects take the same {@link UpdateFields} vocabulary as to-dos (A3). */
+export interface ProjectUpdateParams extends UpdateFields {
     uuid: string;
-    title?: string;
-    notes?: string;
-    /** Append to the existing notes (newline-joined). Exclusive with notes/prependNotes. */
-    appendNotes?: string;
-    /** Prepend to the existing notes (newline-joined). Exclusive with notes/appendNotes. */
-    prependNotes?: string;
-    when?: WhenValue;
-    /**
-     * `HH:mm` sets a reminder (requires when: today|evening|YYYY-MM-DD in the
-     * same call); null clears it (today/evening only — a dated reminder can
-     * only be changed, not cleared). Same semantics as to-do reminders.
-     */
-    reminder?: ReminderTime | null;
-    deadline?: IsoDate | null;
 }
 export interface ProjectSetTagsParams {
     uuid: string;
@@ -565,6 +567,11 @@ export interface AddRepeatingRuleFields {
  * seeds a pure-AX taxonomy (an `area` lands a selectable AREA-view row; otherwise
  * Someday) so the promote never needs a coercion. The two legs are NOT atomic:
  * the created project persists even if the promote refuses.
+ *
+ * `deadline` is the exception, exactly as on {@link TodoAddRepeatingParams}: a
+ * concrete deadline DATE maps to the RULE (each occurrence starts
+ * `deadline − when` days before its own deadline) rather than landing on the
+ * created project, which the promote replaces with the series' own instance.
  */
 export interface ProjectAddRepeatingParams extends AddRepeatingRuleFields {
     title: string;
@@ -572,6 +579,13 @@ export interface ProjectAddRepeatingParams extends AddRepeatingRuleFields {
     /** Destination area (uuid or unique name); when omitted the project is created in Someday. */
     area?: ContainerRef;
     when?: WhenValue;
+    /**
+     * The FIRST occurrence's due date — mapped to the RULE (derive
+     * start-days-earlier = deadline − when), so every occurrence is deadlined and
+     * the created project carries none. Needs a concrete `when` on or before it;
+     * refused on an after-completion series, whose instance is created without a
+     * deadline (RSIM-P P4).
+     */
     deadline?: IsoDate;
     /** Flat child to-do titles (born open). Exclusive with `items`. */
     todos?: string[];
@@ -700,6 +714,7 @@ export interface OperationParamsMap {
     "todo.reschedule-repeat": RepeatRuleParams;
     "todo.pause-repeat": UuidParams;
     "todo.resume-repeat": UuidParams;
+    "todo.create-next-copy": UuidParams;
     "todo.convert-to-project": UuidParams;
     "project.reschedule-repeat": RepeatRuleParams;
     "project.pause-repeat": UuidParams;

package/dist/write/operations.js

@@ -44,6 +44,7 @@ export const OPERATION_KINDS = [
     "todo.reschedule-repeat",
     "todo.pause-repeat",
     "todo.resume-repeat",
+    "todo.create-next-copy",
     "todo.convert-to-project",
     "project.reschedule-repeat",
     "project.pause-repeat",
@@ -68,6 +69,12 @@ export const UI_DRIVE_OPS = [
     "todo.reschedule-repeat",
     "todo.pause-repeat",
     "todo.resume-repeat",
+    // CNC1: `Items ▸ Repeat ▸ Create Next Copy` — materialize the pending
+    // occurrence and advance the series. Not a user-facing verb: it is the first
+    // leg of the template-mutation composites (template-mutation.ts), which mutate
+    // the row it mints. Its template delta is byte-identical to the app's own
+    // `Make Exception` (docs/lab/cnc1-template-mutations.md §1).
+    "todo.create-next-copy",
     "todo.convert-to-project",
     "project.promote-heading",
     "project.reschedule-repeat",

package/dist/write/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/write/operations.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,wBAAwB;IACxB,0BAA0B;IAC1B,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,aAAa;IACb,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,gBAAgB;IAChB,mBAAmB;IACnB,qBAAqB;IACrB,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,sBAAsB;IACtB,iCAAiC;IACjC,0BAA0B;IAC1B,2BAA2B;IAC3B,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,yBAAyB;IACzB,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,wBAAwB;IACxB,uBAAuB;IACvB,oBAAoB;IACpB,YAAY;IACZ,eAAe;IACf,SAAS;CACD,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,yBAAyB;IACzB,yBAAyB;IACzB,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,iEAAiE;IACjE,wBAAwB;IACxB,2EAA2E;IAC3E,4EAA4E;IAC5E,+EAA+E;IAC/E,kEAAkE;IAClE,iCAAiC;IACjC,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,8EAA8E;IAC9E,gBAAgB;IAChB,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAA6B;IACnD,qBAAqB;IACrB,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,sBAAsB;IACtB,iCAAiC;IACjC,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,iBAAiB,CAAC,EAAiB;IACjD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AA+gBD,MAAM,CAAC,MAAM,QAAQ,GAAuB;IAC1C,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/write/operations.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,wBAAwB;IACxB,0BAA0B;IAC1B,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,aAAa;IACb,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,gBAAgB;IAChB,mBAAmB;IACnB,qBAAqB;IACrB,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,sBAAsB;IACtB,iCAAiC;IACjC,0BAA0B;IAC1B,2BAA2B;IAC3B,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,uBAAuB;IACvB,yBAAyB;IACzB,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,wBAAwB;IACxB,uBAAuB;IACvB,oBAAoB;IACpB,YAAY;IACZ,eAAe;IACf,SAAS;CACD,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,sEAAsE;IACtE,6EAA6E;IAC7E,+EAA+E;IAC/E,0EAA0E;IAC1E,6DAA6D;IAC7D,uBAAuB;IACvB,yBAAyB;IACzB,yBAAyB;IACzB,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,iEAAiE;IACjE,wBAAwB;IACxB,2EAA2E;IAC3E,4EAA4E;IAC5E,+EAA+E;IAC/E,kEAAkE;IAClE,iCAAiC;IACjC,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,8EAA8E;IAC9E,gBAAgB;IAChB,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAA6B;IACnD,qBAAqB;IACrB,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,sBAAsB;IACtB,iCAAiC;IACjC,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,wBAAwB;IACxB,yBAAyB;IACzB,2BAA2B;IAC3B,yBAAyB;IACzB,0BAA0B;CAClB,CAAC;AAEX,MAAM,UAAU,iBAAiB,CAAC,EAAiB;IACjD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAkhBD,MAAM,CAAC,MAAM,QAAQ,GAAuB;IAC1C,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC"}

package/dist/write/opid.d.ts

@@ -12,6 +12,7 @@
  * (as a batch line OR a single `--op-id` invocation) is safe against a double.
  */
 import type { AuditRecord } from "../audit/schema.ts";
+import { type MutationResult, type WriteDeps, type WriteOptions } from "./pipeline.ts";
 /** The idempotency-key charset/length, identical for a batch line and a single-op flag. */
 export declare const OP_ID_RE: RegExp;
 /**
@@ -29,3 +30,16 @@ export declare const OPID_LOOKBACK_MS: number;
  * verify-failed:timeout reconciliation variant is a queued phase-2 round).
  */
 export declare function findAppliedOpId(records: AuditRecord[], opId: string, now: Date): AuditRecord | undefined;
+/**
+ * The lookback as a DISPATCH DECISION: the replay result when this write's
+ * `opId` was already applied, or null when it must run. The ONE gate every
+ * single-invocation entry point calls before doing anything — the client's
+ * single-op `run`, and the complete/cancel/exception entries whose composites
+ * own their own dispatch (they never reach `run`, so without this the key would
+ * be recorded and never honored).
+ *
+ * Three conditions, all fail-open (run the write) rather than fail-closed:
+ * no key, a dry run (it mints and records nothing, so there is nothing to
+ * deduplicate against), or no trail to read.
+ */
+export declare function replayIfApplied(deps: WriteDeps, options: WriteOptions): MutationResult | null;

package/dist/write/opid.js

@@ -1,3 +1,5 @@
+import { replayResultFromRecord, } from "./pipeline.js";
+import { readAuditRecords } from "./undo.js";
 /** The idempotency-key charset/length, identical for a batch line and a single-op flag. */
 export const OP_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 /**
@@ -27,4 +29,24 @@ export function findAppliedOpId(records, opId, now) {
     }
     return match;
 }
+/**
+ * The lookback as a DISPATCH DECISION: the replay result when this write's
+ * `opId` was already applied, or null when it must run. The ONE gate every
+ * single-invocation entry point calls before doing anything — the client's
+ * single-op `run`, and the complete/cancel/exception entries whose composites
+ * own their own dispatch (they never reach `run`, so without this the key would
+ * be recorded and never honored).
+ *
+ * Three conditions, all fail-open (run the write) rather than fail-closed:
+ * no key, a dry run (it mints and records nothing, so there is nothing to
+ * deduplicate against), or no trail to read.
+ */
+export function replayIfApplied(deps, options) {
+    if (options.opId === undefined || options.dryRun === true)
+        return null;
+    if (deps.auditDirPath === undefined)
+        return null;
+    const applied = findAppliedOpId(readAuditRecords(deps.auditDirPath), options.opId, deps.now?.() ?? new Date());
+    return applied === undefined ? null : replayResultFromRecord(applied);
+}
 //# sourceMappingURL=opid.js.map

package/dist/write/opid.js.map

@@ -1 +1 @@
-{"version":3,"file":"opid.js","sourceRoot":"","sources":["../../src/write/opid.ts"],"names":[],"mappings":"AAeA,2FAA2F;AAC3F,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAsB,EACtB,IAAY,EACZ,GAAS;IAET,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,gBAAgB,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACrD,IAAI,KAA8B,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;YAAE,SAAS;QACnD,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,MAAM;YAAE,SAAS;QAChD,KAAK,GAAG,CAAC,CAAC,CAAC,4DAA4D;IACzE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"opid.js","sourceRoot":"","sources":["../../src/write/opid.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,sBAAsB,GAIvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAsB,EACtB,IAAY,EACZ,GAAS;IAET,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,gBAAgB,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACrD,IAAI,KAA8B,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;YAAE,SAAS;QACnD,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,MAAM;YAAE,SAAS;QAChD,KAAK,GAAG,CAAC,CAAC,CAAC,4DAA4D;IACzE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,OAAqB;IACpE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,OAAO,GAAG,eAAe,CAC7B,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,EACnC,OAAO,CAAC,IAAI,EACZ,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAC3B,CAAC;IACF,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AACxE,CAAC"}

package/dist/write/param-schema.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 { type OperationKind, type OperationParamsMap } from "./operations.ts";
+/**
+ * The shape vocabulary. `custom` carries a hand-written validator for the shapes
+ * the primitives cannot express (a discriminated bag, a structured item list, a
+ * calendar anchor — those WRAP the engine's existing validators rather than
+ * restating them). `unvalidated` is the escape hatch and requires a WRITTEN
+ * reason; there are currently none.
+ */
+export type FieldKind = "string" | "boolean" | "number" | "stringArray" | "enum" | "container" | "custom" | "unvalidated";
+export interface FieldSpec {
+    kind: FieldKind;
+    /** Absent (or explicitly `null`) is accepted. */
+    optional: boolean;
+    /** Behavioral description of the accepted shape — the "expected" half of every refusal. */
+    describe: string;
+    /** enum: the accepted values. */
+    values?: readonly string[];
+    /** string: reject the empty string. */
+    nonEmpty?: boolean;
+    /** number: whole numbers only, and the inclusive bounds. */
+    integer?: boolean;
+    min?: number;
+    max?: number;
+    /** custom: returns a refusal detail, or null when the value is well-shaped. */
+    validate?: (value: unknown, path: string) => string | null;
+    /** unvalidated: why this field carries no shape check. */
+    reason?: string;
+}
+/** The received-type half of a refusal, in the words a caller reading JSON uses. */
+export declare function describeType(value: unknown): string;
+type OpSchema<K extends OperationKind> = {
+    [F in keyof OperationParamsMap[K]]-?: FieldSpec;
+};
+/**
+ * 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 declare const PARAM_SCHEMAS: {
+    [K in OperationKind]: OpSchema<K>;
+};
+/**
+ * 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 declare function validateOperationParams(op: OperationKind, params: unknown): string | null;
+/** A structural parameter refusal — an input-contract error, never an app failure. */
+export declare class ParamSchemaError extends RangeError {
+    /** The operation whose parameter bag was refused. */
+    readonly op: OperationKind;
+    constructor(op: OperationKind, detail: string);
+}
+/** {@link validateOperationParams}, as a throwing assertion for the pipeline. */
+export declare function assertOperationParams(op: OperationKind, params: unknown): void;
+/** One parameter's machine-readable summary (the `capabilities` params column). */
+export interface ParamSummary {
+    name: string;
+    kind: FieldKind;
+    optional: boolean;
+    /** Behavioral description of the accepted shape. */
+    expects: string;
+    /** enum only: the accepted values. */
+    values?: readonly string[];
+}
+/**
+ * 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 declare function paramSummary(op: OperationKind): ParamSummary[];
+/** Runtime completeness law: every cataloged operation declares a schema. */
+export declare function operationsMissingSchema(): OperationKind[];
+/** Every `unvalidated` escape in the registry, with its written reason (currently none). */
+export declare function unvalidatedFields(): {
+    op: OperationKind;
+    field: string;
+    reason: string;
+}[];
+export {};