things-api 0.10.0 → 0.12.0

package/dist/config.d.ts

@@ -11,10 +11,40 @@ export interface ThingsApiConfig {
     /** User-accepted drifted fingerprint (loud escape hatch; see design §6). */
     acceptedFingerprint: string | null;
     /**
-     * Opt-in to capabilities riding undocumented app surfaces (the private
-     * sdef reorder command). Guarded further by the pipeline's sdef canary.
+     * The Things app version the behavioral LAWS (docs/reference/assumption-register.md)
+     * were last certified against. Set when a baseline ships or by an explicit
+     * `things config set certified-app-version <X>`. The schema fingerprint cannot
+     * see BEHAVIORAL drift (an app update can move an insertion law with zero schema
+     * delta), so `things doctor` compares this against the installed version and
+     * emits a PASSIVE, non-blocking notice on a mismatch, pointing at the drift
+     * suite. Null when never certified (no notice). Precedent: the skill-version
+     * passive drift notice (src/cli/skill-check.ts).
+     */
+    certifiedAppVersion: string | null;
+    /**
+     * Allow capabilities that ride the app's PRIVATE, UNDOCUMENTED sdef reorder
+     * command (default true). This is a private vendor surface, NOT a half-baked
+     * "experimental" one: every write is verify-per-write, fingerprint-gated, and
+     * canaried by the o-suite (incl. O17), which together detect any divergence.
+     * The bidirectional env/config off-switch is retained for hosts that want the
+     * private surface disabled; when off, the planner falls back to a proven bounce
+     * wherever one exists and refuses only where no enabled path remains.
      */
     allowExperimental: boolean;
+    /**
+     * Whether the `when=`-bounce reorder protocols may run (default true). When
+     * false the move/reorder planner REFUSES every bounce-dependent placement
+     * (within-heading order, area-someday order, area-less loose anytime, and the
+     * top-level projects / evening scopes) with a teaching error naming this key —
+     * it never silently falls back to a destructive or unverified path.
+     */
+    bounceEnabled: boolean;
+    /**
+     * Cap on the number of items a single bounce reorder may touch (default 30).
+     * Each item costs two verified mutations (~110 ms/item guest-local, BOUNCE2-t);
+     * the cap bounds the wall-clock and the Things-Cloud change-record fan-out.
+     */
+    bounceMaxItems: number;
     /**
      * The Accessibility GUI ("ui") write vector. When disabled the vector does
      * not exist on this machine: its GUI-only operations report unsupported.
@@ -25,6 +55,20 @@ export interface ThingsApiConfig {
     ui: {
         enabled: boolean;
     };
+    /**
+     * Container-scoped sandbox: a raw ref (uuid / uuid-prefix / unique area or
+     * project name) plus where it came from, resolved to a pinned container at
+     * `openThings()`. Null when unscoped. A stored `scope` jails EVERY process on
+     * this host — including the owner's own terminal — so per-process scoping
+     * belongs on `THINGS_API_SCOPE` / the MCP `--scope` flag, not here (see
+     * docs/design/container-scope.md, Trust model). The MCP flag outranks env,
+     * which outranks this stored key. Optional in the type (a hand-built config
+     * omits it = unscoped); {@link loadConfig} always populates it.
+     */
+    scope?: {
+        ref: string;
+        source: "env" | "config";
+    } | null;
     host: string;
 }
 interface ConfigFile {
@@ -33,10 +77,30 @@ interface ConfigFile {
     actor?: string;
     auditEnabled?: boolean;
     acceptedFingerprint?: string;
+    certifiedAppVersion?: string;
     allowExperimental?: boolean;
+    bounceEnabled?: boolean;
+    bounceMaxItems?: number;
     uiEnabled?: boolean;
+    scope?: string;
 }
 export declare function loadConfig(env?: NodeJS.ProcessEnv): ThingsApiConfig;
 /** Persist one config key (CLI `things config set`). */
 export declare function saveConfigKey(key: keyof ConfigFile, value: string | number | boolean | null, env?: NodeJS.ProcessEnv): void;
+/**
+ * One config key's effective value and where it came from. `key` is the
+ * `things config set` / `things config get` spelling; `value` is the effective
+ * value after env override → stored file → built-in default; `source` says which
+ * layer supplied it. `derived` marks a read-only value computed from the
+ * environment (`host`) or from another key (the profile-derived `maxDisruption`
+ * default) rather than settable directly.
+ */
+export interface ConfigKeyView {
+    key: string;
+    value: string | number | boolean | null;
+    source: "env" | "stored" | "default" | "derived";
+}
+export declare function describeConfig(env?: NodeJS.ProcessEnv): ConfigKeyView[];
+/** One key's effective view, or undefined for an unknown key (`config get <key>`). */
+export declare function getConfigKey(key: string, env?: NodeJS.ProcessEnv): ConfigKeyView | undefined;
 export {};

package/dist/config.js

@@ -13,6 +13,41 @@ const PROFILE_DEFAULT_TIER = {
     workstation: 1,
     "dedicated-server": 2,
 };
+/**
+ * A THINGS_API_* boolean override. Returns the forced value when the env var
+ * holds a recognized token, or undefined when unset/unrecognized (so the
+ * caller falls through to stored config, then the built-in default). The
+ * override is BIDIRECTIONAL — a recognized value always wins over stored
+ * config, so an env var can force a vector off as well as on. `trueToken` /
+ * `falseToken` let THINGS_API_AUDIT keep its legacy on/off vocabulary while
+ * the vectors use true/false.
+ */
+function boolEnvOverride(raw, trueToken, falseToken) {
+    if (raw === trueToken)
+        return true;
+    if (raw === falseToken)
+        return false;
+    return undefined;
+}
+/** THINGS_API_PROFILE override, or undefined when unset/unrecognized. */
+function profileEnvOverride(raw) {
+    return raw === "workstation" || raw === "dedicated-server" ? raw : undefined;
+}
+/** THINGS_API_MAX_DISRUPTION override, or undefined when unset/unrecognized. */
+function tierEnvOverride(raw) {
+    return raw !== undefined && /^[0-3]$/.test(raw) ? Number(raw) : undefined;
+}
+/**
+ * A THINGS_API_BOUNCE_MAX_ITEMS override, or undefined when unset/unrecognized.
+ * Only a positive integer is accepted (a bounce touches at least one item);
+ * anything else falls through to stored config, then the built-in default.
+ */
+function positiveIntEnvOverride(raw) {
+    if (raw === undefined || !/^[0-9]+$/.test(raw))
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
 function configFilePath(env) {
     return join(configDir(env), "config.json");
 }
@@ -27,13 +62,12 @@ export function loadConfig(env = process.env) {
             // Malformed config falls back to defaults; doctor reports it.
         }
     }
-    const profile = env["THINGS_API_PROFILE"] === "dedicated-server" || file.profile === "dedicated-server"
-        ? "dedicated-server"
-        : "workstation";
-    const envTier = env["THINGS_API_MAX_DISRUPTION"];
-    const maxDisruption = (envTier !== undefined && /^[0-3]$/.test(envTier)
-        ? Number(envTier)
-        : (file.maxDisruption ?? PROFILE_DEFAULT_TIER[profile]));
+    // Precedence for every key: env > stored > default. A recognized env value
+    // always wins over stored config; an unset/unrecognized one falls through.
+    const profile = profileEnvOverride(env["THINGS_API_PROFILE"]) ?? file.profile ?? "workstation";
+    const maxDisruption = tierEnvOverride(env["THINGS_API_MAX_DISRUPTION"]) ??
+        file.maxDisruption ??
+        PROFILE_DEFAULT_TIER[profile];
     let username = "unknown";
     try {
         username = userInfo().username;
@@ -41,16 +75,32 @@ export function loadConfig(env = process.env) {
     catch {
         // leave "unknown"
     }
+    const auditEnv = boolEnvOverride(env["THINGS_API_AUDIT"], "on", "off");
+    const experimentalEnv = boolEnvOverride(env["THINGS_API_ALLOW_EXPERIMENTAL"], "true", "false");
+    const bounceEnabledEnv = boolEnvOverride(env["THINGS_API_BOUNCE_ENABLED"], "true", "false");
+    const bounceMaxItemsEnv = positiveIntEnvOverride(env["THINGS_API_BOUNCE_MAX_ITEMS"]);
+    const uiEnv = boolEnvOverride(env["THINGS_API_UI_ENABLED"], "true", "false");
+    // Scope precedence within the config layer: THINGS_API_SCOPE env > stored
+    // `scope` key. The MCP `--scope` flag outranks BOTH and is applied above this
+    // layer, at openThings(). Fail-closed resolution to a container happens there.
+    const scopeEnv = env["THINGS_API_SCOPE"];
+    const scope = scopeEnv !== undefined && scopeEnv !== ""
+        ? { ref: scopeEnv, source: "env" }
+        : file.scope !== undefined && file.scope !== ""
+            ? { ref: file.scope, source: "config" }
+            : null;
     return {
         profile,
         maxDisruption,
         actor: env["THINGS_API_ACTOR"] ?? file.actor ?? `${username}@cli`,
-        auditEnabled: env["THINGS_API_AUDIT"] === "off" ? false : (file.auditEnabled ?? true),
+        auditEnabled: auditEnv ?? file.auditEnabled ?? true,
         acceptedFingerprint: file.acceptedFingerprint ?? null,
-        allowExperimental: env["THINGS_API_ALLOW_EXPERIMENTAL"] === "true" || file.allowExperimental === true,
-        ui: {
-            enabled: env["THINGS_API_UI_ENABLED"] === "true" || file.uiEnabled === true,
-        },
+        certifiedAppVersion: file.certifiedAppVersion ?? null,
+        allowExperimental: experimentalEnv ?? file.allowExperimental ?? true,
+        bounceEnabled: bounceEnabledEnv ?? file.bounceEnabled ?? true,
+        bounceMaxItems: bounceMaxItemsEnv ?? file.bounceMaxItems ?? 30,
+        ui: { enabled: uiEnv ?? file.uiEnabled ?? false },
+        scope,
         host: hostname(),
     };
 }
@@ -76,4 +126,62 @@ export function saveConfigKey(key, value, env = process.env) {
     }
     writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`);
 }
+function readConfigFile(env) {
+    const path = configFilePath(env);
+    if (existsSync(path)) {
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            // Malformed config → treated as no stored keys (doctor reports it).
+        }
+    }
+    return {};
+}
+/**
+ * The effective value + provenance of every config key, in a stable order —
+ * backing `things config get`. Env/stored/default detection mirrors
+ * {@link loadConfig} exactly, so a key reads `env` only when an env var actually
+ * overrode it (a THINGS_API_* value that loadConfig honors), `stored` when the
+ * on-disk config supplied it, `derived` for a read-only value computed from the
+ * environment or another key, and `default` otherwise.
+ */
+function configKeyView(key, value, stored, fromEnv) {
+    return { key, value, source: fromEnv ? "env" : stored ? "stored" : "default" };
+}
+export function describeConfig(env = process.env) {
+    const file = readConfigFile(env);
+    const cfg = loadConfig(env);
+    const view = configKeyView;
+    const tierFromEnv = tierEnvOverride(env["THINGS_API_MAX_DISRUPTION"]) !== undefined;
+    const maxDisruption = {
+        key: "maxDisruption",
+        value: cfg.maxDisruption,
+        // env > stored > profile-derived default (the built-in fallback is
+        // computed from `profile`, so it reports `derived`, not `default`).
+        source: tierFromEnv ? "env" : file.maxDisruption !== undefined ? "stored" : "derived",
+    };
+    return [
+        view("profile", cfg.profile, file.profile !== undefined, profileEnvOverride(env["THINGS_API_PROFILE"]) !== undefined),
+        maxDisruption,
+        view("actor", cfg.actor, file.actor !== undefined, env["THINGS_API_ACTOR"] !== undefined),
+        view("auditEnabled", cfg.auditEnabled, file.auditEnabled !== undefined, boolEnvOverride(env["THINGS_API_AUDIT"], "on", "off") !== undefined),
+        view("accepted-fingerprint", cfg.acceptedFingerprint, file.acceptedFingerprint !== undefined, false),
+        view("certified-app-version", cfg.certifiedAppVersion, file.certifiedAppVersion !== undefined, false),
+        view("allow-experimental", cfg.allowExperimental, file.allowExperimental !== undefined, boolEnvOverride(env["THINGS_API_ALLOW_EXPERIMENTAL"], "true", "false") !== undefined),
+        view("bounce-enabled", cfg.bounceEnabled, file.bounceEnabled !== undefined, boolEnvOverride(env["THINGS_API_BOUNCE_ENABLED"], "true", "false") !== undefined),
+        view("bounce-max-items", cfg.bounceMaxItems, file.bounceMaxItems !== undefined, positiveIntEnvOverride(env["THINGS_API_BOUNCE_MAX_ITEMS"]) !== undefined),
+        view("ui-enabled", cfg.ui.enabled, file.uiEnabled !== undefined, boolEnvOverride(env["THINGS_API_UI_ENABLED"], "true", "false") !== undefined),
+        // The container scope's RAW ref (resolved to a container at open); env >
+        // stored. A stored value jails every process on this host — see the
+        // trust-model note in docs/design/container-scope.md.
+        view("scope", cfg.scope?.ref ?? null, file.scope !== undefined, env["THINGS_API_SCOPE"] !== undefined && env["THINGS_API_SCOPE"] !== ""),
+        // Read-only, computed from the environment; not settable via `config set`.
+        { key: "host", value: cfg.host, source: "derived" },
+    ];
+}
+/** One key's effective view, or undefined for an unknown key (`config get <key>`). */
+export function getConfigKey(key, env = process.env) {
+    return describeConfig(env).find((v) => v.key === key);
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/contracts.d.ts

@@ -13,7 +13,7 @@ export declare const API_VERSION = 1;
  * Package version, surfaced by `things --version` and the MCP serverInfo.
  * Kept in lockstep with package.json by a contract test.
  */
-export declare const PKG_VERSION = "0.10.0";
+export declare const PKG_VERSION = "0.12.0";
 /**
  * Stable exit-code contract for the `things` CLI (mirrored by MCP error
  * codes). Part of the public API surface consumed by agents and scripts —
@@ -51,21 +51,29 @@ export interface SectionCount {
     total: number;
 }
 /**
- * List-view truncation metadata (ADDITIVE). Present on the meta of any read
- * command that applies a row limit; absent on unbounded/structured views.
- * `shown` items were returned of `total` that matched after all filters;
- * `limit` is the effective cap (null when the caller asked for all rows);
- * `truncated` is true exactly when `shown < total`. The dropped remainder is
- * `total - shown`. `sections` is present only on a split flat view (the Today
- * split), breaking the whole-view counts down per render section.
+ * The single truncation-metadata shape for every read (the `meta.truncation`
+ * field). `shown` items were returned of `total` that matched after all
+ * filters; `limit` is the effective cap (null when the caller asked for all
+ * rows, and always null on a grouped view whose caps are per-block); `truncated`
+ * is the UNIVERSAL completeness check — true exactly when anything was dropped
+ * (`shown < total`, or any block hid rows). The dropped remainder is
+ * `total - shown`.
+ *
+ * Two optional per-shape breakdowns hang off it: `sections` for a split flat
+ * view (the Today split — per render-section shown/total), and `blocks` for a
+ * grouped view (anytime/someday/`area show` — the identity-carrying per-block
+ * nesting). Exactly one of them is present on the shapes that have it; both are
+ * absent on a plain flat view.
  */
 export interface Truncation {
     shown: number;
     total: number;
     limit: number | null;
     truncated: boolean;
-    /** Per-section shown/total breakdown for a split flat view; absent otherwise. */
+    /** Per-section shown/total breakdown for a split flat view (Today); absent otherwise. */
     sections?: SectionCount[];
+    /** Per-block nesting for a grouped view (anytime/someday/area card); absent otherwise. */
+    blocks?: GroupBlock[];
 }
 /**
  * One identity-carrying block of a grouped catalogue (anytime/someday) or a
@@ -103,12 +111,6 @@ export interface GroupBlock {
     /** Nested project blocks (anytime item-lists / someday active-project groups). Absent when none. */
     children?: GroupBlock[];
 }
-/** Grouped-view truncation metadata (ADDITIVE); the per-block counterpart of {@link Truncation}. */
-export interface GroupedTruncation {
-    /** True when any block hid items. */
-    truncated: boolean;
-    blocks: GroupBlock[];
-}
 export interface EnvelopeMeta {
     /** Things database schema version (`Meta.databaseVersion`), null when no DB was opened. */
     dbVersion: number | null;
@@ -116,10 +118,13 @@ export interface EnvelopeMeta {
     fingerprint: "ok" | "drift" | "user-accepted" | "unknown";
     /** Wall-clock duration of the command in milliseconds. */
     elapsedMs: number;
-    /** List-view truncation metadata; present only on limited flat read views. */
+    /**
+     * The read's completeness metadata (the single truncation shape). Present on
+     * any read that could drop rows — flat views (row `limit`), the Today split
+     * (`sections`), and grouped views (anytime/someday/`area show`, `blocks`).
+     * `meta.truncation.truncated` is the universal "did I see everything" check.
+     */
     truncation?: Truncation;
-    /** Per-block truncation metadata; present only on grouped views (anytime/someday). */
-    grouped?: GroupedTruncation;
     /**
      * The canonical `things …` command a sugar invocation normalized to (bare
      * noun, keyword-in-show, uuid/share-link routing). Present only on routed
@@ -133,6 +138,42 @@ export interface EnvelopeMeta {
      * (reads stay best-effort; run `things doctor`). Absent means none.
      */
     warnings?: string[];
+    /**
+     * The effective clock this response's date boundaries were computed for
+     * (ADDITIVE honesty field). Present ONLY when a consumer zone (`THINGS_TZ` /
+     * the MCP `tz` argument) or a pinned `THINGS_NOW` is in effect; ABSENT on the
+     * host clock, so the wire shape is unchanged for ordinary consumers.
+     */
+    clock?: {
+        timezone: string;
+        today: string;
+    };
+    /**
+     * The active content filter this response was scoped to (ADDITIVE). Present
+     * ONLY when a scope was applied — currently `area` (the `--area` view filter),
+     * carrying the resolved area's uuid + title; ABSENT otherwise, so the wire
+     * shape is unchanged for unscoped reads (the `meta.clock` precedent).
+     */
+    filter?: {
+        area: {
+            uuid: string;
+            title: string;
+        };
+    };
+    /**
+     * The active container scope this response was jailed to (ADDITIVE). Present
+     * ONLY when a scope is in force (the MCP `--scope` flag / `THINGS_API_SCOPE` /
+     * a stored `scope`), naming the container + where the scope came from; ABSENT
+     * otherwise, so the wire shape is unchanged for unscoped reads. Lets an agent
+     * know its own jail — which is not an oracle for what lies outside it (the
+     * `meta.clock` / `meta.filter` additive precedent).
+     */
+    scope?: {
+        kind: "area" | "project";
+        uuid: string;
+        title: string;
+        source: "flag" | "env" | "config";
+    };
 }
 export interface OkEnvelope<T> {
     apiVersion: typeof API_VERSION;
@@ -142,13 +183,38 @@ export interface OkEnvelope<T> {
     data: T;
     meta: EnvelopeMeta;
 }
+/**
+ * The registry of stable machine-readable error codes an error envelope can
+ * carry — the compiler IS the registry. Every `error.code` value the surfaces
+ * emit is a member of this union, and the human-readable meaning of each is
+ * frozen at v1.0 (new codes may still be ADDED after v1.0 — that is
+ * non-breaking; a documented code's MEANING never changes). The canonical
+ * per-code table (meaning + the `detail` keys each may carry) lives in
+ * `docs/contract.md` (The error-code registry).
+ *
+ * Two members are template-literal families rather than fixed strings, because
+ * their suffix is minted in the write layer and the core deliberately never
+ * depends on it (see {@link blockedCode} / {@link verifyFailedCode}):
+ *  - `verify-failed:${reason}` — a single mutation executed but read-after-write
+ *    verification failed; the suffix is the reason (`timeout` | `mismatch` |
+ *    `silent-noop`). The bare `verify-failed` (no suffix) is the multi-leg
+ *    move/reorder failure.
+ *  - `blocked:${suffix}` — a mutation refused before touching the app; the
+ *    suffix is the specific hazard id (`H-…`) when one is named, else the block
+ *    reason (`drift` | `disruption-tier` | `lock` | `environment` | `clock` |
+ *    `scope`). The bare `blocked` is a policy refusal from the move planner.
+ *
+ * `blocked:drift` maps to exit code 5 (DriftBlocked); every other `blocked:*`
+ * maps to exit code 4 (Blocked).
+ */
+export type ErrorCode = "usage" | "not-found" | "ambiguous" | "unsupported" | "environment" | "unexpected" | "bounce-aborted" | "verify-failed" | "blocked" | `verify-failed:${string}` | `blocked:${string}`;
 export interface ErrorEnvelope {
     apiVersion: typeof API_VERSION;
     ok: false;
     kind: "error";
     error: {
-        /** Stable machine-readable code, mirrors the exit-code family (e.g. "verify-failed", "blocked"). */
-        code: string;
+        /** Stable machine-readable code from the {@link ErrorCode} registry (mirrors the exit-code family, e.g. "verify-failed", "blocked:H-UNKNOWN-TAG"). */
+        code: ErrorCode;
         message: string;
         /**
          * Advisory attribution when failure signals point somewhere: e.g.
@@ -158,25 +224,117 @@ export interface ErrorEnvelope {
         likelyCause?: string;
         /** Actionable next step for the caller, when one exists. */
         remediation?: string;
-        detail?: unknown;
         /**
-         * Structured, machine-readable failure context (ADDITIVE). For an
-         * unresolved show/bare-noun subject it carries `candidates` — the
-         * did-you-mean title matches (standard item shapes, capped) so an agent
-         * can self-correct without a second round-trip. For a bare mutation verb
-         * (`things update <ref>`) it carries `suggestions` — the concrete
-         * namespaced command(s) to run instead.
+         * The SINGLE structured, machine-readable failure-context object (there is
+         * no separate `details` field — the two were reconciled into this one). Each
+         * key is present only for the failures that produce it:
+         *  - `expected` / `observed` — a verify-failed mutation's expected delta and
+         *    the observed post-write state.
+         *  - `candidates` — the disambiguation list for a not-found / ambiguous
+         *    resolution (or a show/bare-noun did-you-mean): the ONE fixed, flag-
+         *    invariant candidate shape (`CandidateRef`; see docs/contract.md), a
+         *    LIVE-scoped pool capped at 8, so an agent can self-correct without
+         *    another round-trip.
+         *  - `suggestions` — for a bare mutation verb (`things update <ref>`), the
+         *    concrete namespaced command(s) to run instead.
+         *  - `considered` — the vectors weighed (and why each was rejected) for an
+         *    unsupported operation.
+         *  - `placed` / `remaining` / `cause` — a bounce reorder that aborted
+         *    part-way: the items already placed, those not yet placed, and the cause.
+         *  - `failed` / `completed` — a multi-leg move that failed mid-way: the leg
+         *    that failed and the legs already completed before it.
          */
-        details?: {
+        detail?: {
+            expected?: unknown;
+            observed?: Record<string, unknown> | null;
             candidates?: unknown[];
             suggestions?: string[];
+            considered?: {
+                vector: string;
+                why: string;
+            }[];
+            placed?: string[];
+            remaining?: string[];
+            cause?: unknown;
+            failed?: unknown;
+            completed?: unknown[];
         };
     };
     meta: EnvelopeMeta;
 }
 export type Envelope<T> = OkEnvelope<T> | ErrorEnvelope;
+/**
+ * The envelope `kind` discriminators a SUCCESSFUL response carries today (the
+ * error envelope's `kind` is always the literal `"error"`). This union is the
+ * schema's record of the known payload classes — the flat-list reads
+ * (`data.items`), the sectioned reads (`data.sections`), the composite cards
+ * (`data.view`), the single-entity detail (`data.item`), the mutations/plans
+ * (flat `data` fields), and the diagnostic payloads.
+ *
+ * Per the compatibility covenant (docs/contract.md) a consumer MUST tolerate an
+ * UNKNOWN `kind`: adding a new kind is additive / non-breaking. So this union is
+ * "the kinds known to THIS build", not a closed set a generic reader may assume
+ * complete — the JSON Schema pins it as an enum so drift is caught, but a
+ * forward-compatible consumer routes on the wrapper it finds in `data`.
+ */
+export type WireOkKind = "inbox" | "upcoming" | "logbook" | "trash" | "changes" | "search" | "projects" | "areas" | "tags" | "today" | "anytime" | "someday" | "area-view" | "project-view" | "detail" | "mutation-result" | "move-result" | "mutation-plan" | "move-plan" | "project-reopen" | "doctor" | "capabilities" | "config" | "legend" | "setup-shortcuts" | "install-skill";
+/**
+ * The `data` payload of a successful envelope. Its CONCRETE shape is
+ * command-specific — one of the R1/R2 read wrappers (`item` | `view` | `items` |
+ * `sections`) or a mutation's flat result fields — and, crucially, entity
+ * payloads are omit-empty pruned on the wire (docs/design/contracts.md).
+ *
+ * COVERAGE BOUNDARY: this schema does NOT model the per-kind payload shapes. It
+ * pins the ENVELOPE layer exactly (`apiVersion`, `ok`, `kind`, `meta`, and the
+ * whole `error` object) and treats `data` as an open JSON object. Fully typing
+ * every kind's payload against the omit-empty wire shape is a separate, larger
+ * effort; until then `src/contracts.ts` and `docs/contract.md` remain the
+ * authoritative description of what each `kind`'s `data` contains.
+ */
+export type WireData = Record<string, unknown>;
+/** A successful `--json` envelope, exactly as emitted on stdout. */
+export interface WireOkEnvelope {
+    apiVersion: typeof API_VERSION;
+    ok: true;
+    /** The payload class — see {@link WireOkKind}. */
+    kind: WireOkKind;
+    /** Command-specific payload; open at the schema layer (see {@link WireData}). */
+    data: WireData;
+    meta: EnvelopeMeta;
+}
+/**
+ * The machine-readable ROOT the envelope JSON Schema is generated from
+ * (`schema/envelope.schema.json`, produced by `npm run schema:gen`): the
+ * discriminated union — on the boolean `ok` — of a successful envelope and an
+ * {@link ErrorEnvelope}, exactly as written to stdout by the CLI `--json`
+ * surface and inherited by the MCP server. This is the same grammar
+ * docs/contract.md describes in prose; the schema is its generated, testable
+ * rendering. NB: the streaming commands (`batch`, `undo`) emit JSON Lines, a
+ * documented exception NOT covered by this envelope type.
+ */
+export type WireEnvelope = WireOkEnvelope | ErrorEnvelope;
 export declare function okEnvelope<T>(kind: string, data: T, meta: EnvelopeMeta): OkEnvelope<T>;
 export declare function errorEnvelope(error: ErrorEnvelope["error"], meta: EnvelopeMeta): ErrorEnvelope;
+/**
+ * Project a successful mutation/reorder/move outcome to its ENVELOPE `data`
+ * shape. The wire's mutation-success discriminator is REDUNDANT and is not
+ * emitted: the envelope already carries call success (`ok: true`, and the
+ * envelope `kind` names the payload class — `mutation-result` / `move-result`).
+ * So the result's internal `kind` discriminator is STRIPPED here — the emitted
+ * `data` has no `result` and no `kind`, just the payload fields (`op`, `uuid`,
+ * `title`, `undoToken`, `observed`, `vector`, `tier`, `touched`, notes, …).
+ * Only the internal tags `"ok"` / `"move-ok"` ever reach this boundary
+ * (failures route to error envelopes, dry-runs to the `mutation-plan` /
+ * `move-plan` kinds), so nothing is lost by dropping it. The library keeps the
+ * idiomatic `kind` discriminator on its in-memory
+ * `MutationResult`/`ReorderResult`/`MoveResult` unions; it simply never appears
+ * on the wire. BOTH consumer surfaces emit through it: the CLI (`mutation-result`
+ * / `move-result` envelopes) and the MCP mutation/move content block (phase-2
+ * framing sweep, 2026-07-31) — a dry-run routes to the bare `plan` on both.
+ */
+export declare function mutationWireData<T extends {
+    kind: string;
+}>(ok: T): Omit<T, "kind">;
 /**
  * Canonical machine-readable error CODE for a refused ("blocked") mutation: the
  * specific hazard id when one is named, else the block reason. Every surface —

package/dist/contracts.js

@@ -13,7 +13,7 @@ export const API_VERSION = 1;
  * Package version, surfaced by `things --version` and the MCP serverInfo.
  * Kept in lockstep with package.json by a contract test.
  */
-export const PKG_VERSION = "0.10.0";
+export const PKG_VERSION = "0.12.0";
 /**
  * Stable exit-code contract for the `things` CLI (mirrored by MCP error
  * codes). Part of the public API surface consumed by agents and scripts —
@@ -43,6 +43,27 @@ export function okEnvelope(kind, data, meta) {
 export function errorEnvelope(error, meta) {
     return { apiVersion: API_VERSION, ok: false, kind: "error", error, meta };
 }
+/**
+ * Project a successful mutation/reorder/move outcome to its ENVELOPE `data`
+ * shape. The wire's mutation-success discriminator is REDUNDANT and is not
+ * emitted: the envelope already carries call success (`ok: true`, and the
+ * envelope `kind` names the payload class — `mutation-result` / `move-result`).
+ * So the result's internal `kind` discriminator is STRIPPED here — the emitted
+ * `data` has no `result` and no `kind`, just the payload fields (`op`, `uuid`,
+ * `title`, `undoToken`, `observed`, `vector`, `tier`, `touched`, notes, …).
+ * Only the internal tags `"ok"` / `"move-ok"` ever reach this boundary
+ * (failures route to error envelopes, dry-runs to the `mutation-plan` /
+ * `move-plan` kinds), so nothing is lost by dropping it. The library keeps the
+ * idiomatic `kind` discriminator on its in-memory
+ * `MutationResult`/`ReorderResult`/`MoveResult` unions; it simply never appears
+ * on the wire. BOTH consumer surfaces emit through it: the CLI (`mutation-result`
+ * / `move-result` envelopes) and the MCP mutation/move content block (phase-2
+ * framing sweep, 2026-07-31) — a dry-run routes to the bare `plan` on both.
+ */
+export function mutationWireData(ok) {
+    const { kind: _kind, ...rest } = ok;
+    return rest;
+}
 /**
  * Canonical machine-readable error CODE for a refused ("blocked") mutation: the
  * specific hazard id when one is named, else the block reason. Every surface —

package/dist/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,4DAA4D;IAC5D,UAAU,EAAE,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,CAAC;IACR,uGAAuG;IACvG,YAAY,EAAE,CAAC;IACf,wFAAwF;IACxF,OAAO,EAAE,CAAC;IACV,gGAAgG;IAChG,YAAY,EAAE,CAAC;IACf,6DAA6D;IAC7D,WAAW,EAAE,CAAC;IACd,kFAAkF;IAClF,WAAW,EAAE,CAAC;CACN,CAAC;AAkJX,MAAM,UAAU,UAAU,CAAI,IAAY,EAAE,IAAO,EAAE,IAAkB;IACrE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA6B,EAAE,IAAkB;IAC7E,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA4C;IACtE,OAAO,WAAW,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAmB,OAAsB;IACvE,OAAO,iBAAiB,OAAO,CAAC,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAsD;IAEtD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,EAAE,CAAC;QACvE,OAAO,QAAQ,CAAC,YAAY,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC;IAClD,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAO,QAAQ,CAAC,WAAW,CAAC;IAC1D,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,4DAA4D;IAC5D,UAAU,EAAE,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,CAAC;IACR,uGAAuG;IACvG,YAAY,EAAE,CAAC;IACf,wFAAwF;IACxF,OAAO,EAAE,CAAC;IACV,gGAAgG;IAChG,YAAY,EAAE,CAAC;IACf,6DAA6D;IAC7D,WAAW,EAAE,CAAC;IACd,kFAAkF;IAClF,WAAW,EAAE,CAAC;CACN,CAAC;AAmUX,MAAM,UAAU,UAAU,CAAI,IAAY,EAAE,IAAO,EAAE,IAAkB;IACrE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA6B,EAAE,IAAkB;IAC7E,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAA6B,EAAK;IAChE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;IACpC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA4C;IACtE,OAAO,WAAW,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAmB,OAAsB;IACvE,OAAO,iBAAiB,OAAO,CAAC,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAsD;IAEtD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,EAAE,CAAC;QACvE,OAAO,QAAQ,CAAC,YAAY,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC;IAClD,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAO,QAAQ,CAAC,WAAW,CAAC;IAC1D,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC"}