things-api 0.17.0 → 0.19.0

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 {};