things-api 0.19.3 → 0.20.0

package/dist/write/pipeline.js

@@ -11,6 +11,7 @@ import { statSync } from "node:fs";
 import { undoToken } from "../audit/schema.js";
 import { blockedCode, verifyFailedCode } from "../contracts.js";
 import { localToday } from "../model/dates.js";
+import { currentInstance } from "../process-instance.js";
 import { liveSeriesInstances, resolveProjectWriteTarget, resolveTaskUuidPrefix, } from "../read/queries.js";
 import { namedProjectClause, taskMembershipClause } from "../read/scope.js";
 import { evaluateScope } from "./scope-guard.js";
@@ -18,13 +19,19 @@ import { isThingsRunning } from "./automation-probe.js";
 import { readShortcutProxies } from "./availability.js";
 import { uiAllowed, uiCapability as uiCapabilityDefault, urlSchemeAllowed, urlSchemeCapability as urlSchemeCapabilityDefault, writeAllowed, writeCapability as writeCapabilityDefault, } from "../capability.js";
 import { COMMANDS } from "./commands.js";
+import { carry, disclose, newDisclosures, tiers } from "./disclosures.js";
 import { describeEnvironmentChanges, diffEnvironment, } from "./environment.js";
-import { privateReorderIsNoOp, sdefDeclaresPrivateReorder } from "./experimental.js";
+import { privateReorderIsNoOp, sdefDeclaresPrivateReorder, urlReanchorSupported, } from "./experimental.js";
 import { classifyTransportFailure, classifyVerifyFailure, } from "./failure-hints.js";
 import { evaluateGuards } from "./guards.js";
-import { acquireMutationLock, MutationLockError, withMutationLock, } from "./lock.js";
-import { isHeadingTargetOp, } from "./operations.js";
+import { acquireMutationLock, describeLockRefusal, MutationLockError, withMutationLock, } from "./lock.js";
+import { isHeadingTargetOp, isRepeatReanchor, } from "./operations.js";
 import { describeTruncation } from "./field-limits.js";
+// The idempotency gate is a MUTUAL import with this module (it builds its replay
+// results from `replayResultFromRecord` here, and the double-checked lookback
+// here calls back into it). Both sides are hoisted function declarations, so the
+// cycle resolves at module-evaluation time; nothing is read at import time.
+import { replayIfApplied } from "./opid.js";
 import { assertOperationParams } from "./param-schema.js";
 import { computeCompletionContext } from "./completion-context.js";
 import { assessOffRuleFirst } from "./repeat-anchor.js";
@@ -43,6 +50,15 @@ import { setInflight, trace } from "../trace/tracer.js";
  * transport exit is re-verified over ~2s before the write is declared lost.
  */
 const RECOVERY_VERIFY_TIMEOUT_MS = 2000;
+/**
+ * The drive's step play-by-play as a spreadable fragment, omitted when there is
+ * none (a transport vector runs no steps). One helper so the FAILURE paths, the
+ * change-history record, and the `--verbose` success all read the same field and
+ * cannot drift apart (#632).
+ */
+function stepsOf(result) {
+    return result.steps !== undefined && result.steps.length > 0 ? { steps: result.steps } : {};
+}
 export function readAuthToken(db) {
     try {
         const row = db.prepare("SELECT uriSchemeAuthenticationToken AS t FROM TMSettings").get();
@@ -295,40 +311,92 @@ function truncationDetail(delta, observed) {
     }
     return undefined;
 }
-/**
- * Run a COMPOSITE — a single verb the engine executes as several mutations —
- * under ONE mutation lock held end-to-end, so it serializes against other
- * writers as a whole instead of leg by leg. Every leg's own
- * `acquireMutationLock` inside `body` is a reentrant no-op (see
- * {@link withMutationLock}); the per-leg lock stays the base case for an
- * ordinary single mutation.
- *
- * Wrap only the MUTATING tail: validation, dry-run planning, and the hazard /
- * session gates belong outside, so a refusal never takes the lock. On contention
- * the refusal is the same `blocked` / `lock` shape the pipeline returns for a
- * single op, carrying the composite's own op name. No audit record is written
- * for it — unlike the single-op path, nothing was attempted, so there is no leg
- * to record.
- */
-export async function runComposite(deps, op, body, 
+export async function runComposite(deps, op, body, keyed, 
 /** @internal test seam — see {@link AcquireMutationLockOptions}. */
 lockOptions = {}) {
     try {
-        return await withMutationLock(deps.lockPath, body, lockOptions);
+        return await withMutationLock(deps.lockPath, async () => {
+            if (keyed === undefined || keyed.options.opId === undefined)
+                return body();
+            const locked = replayIfApplied(deps, keyed.options);
+            if (locked !== null)
+                return locked;
+            appendSummaryIntent(deps, op, keyed);
+            const outcome = await body();
+            closeSummaryIntent(deps, op, keyed, outcome);
+            return outcome;
+        }, lockOptions);
     }
     catch (err) {
         if (err instanceof MutationLockError) {
-            return {
-                kind: "blocked",
-                op,
-                reason: "lock",
-                detail: err.message,
-                remediation: "wait for the concurrent mutation to finish and retry",
-            };
+            return { kind: "blocked", op, reason: "lock", ...describeLockRefusal(err) };
         }
         throw err;
     }
 }
+/**
+ * The keyed composite's write-ahead intent: ONE summary-layer record marking the
+ * key as in flight, with the holder identity that makes "still running" a
+ * decidable question rather than a hedge. Superseded, append-only, by whichever
+ * summary the verb writes when it finishes — this record is never rewritten.
+ */
+function appendSummaryIntent(deps, op, keyed, result = "intent") {
+    const fp = deps.fingerprint();
+    const inFlight = result === "intent";
+    deps.audit.append({
+        v: 1,
+        ts: keyed.startedAt.toISOString(),
+        actor: keyed.options.actor ?? deps.config.actor,
+        host: deps.config.host,
+        op,
+        uuid: keyed.uuid,
+        vector: null,
+        disruption: null,
+        invocation: null,
+        txn: { id: keyed.txnId, role: "summary" },
+        opId: keyed.options.opId,
+        ...(inFlight && { holder: currentInstance() }),
+        ...(inFlight && keyed.expected !== undefined && { expected: keyed.expected }),
+        requested: keyed.requested,
+        pre: null,
+        observed: null,
+        result,
+        verify: null,
+        durationMs: 0,
+        env: {
+            pkg: deps.pkgVersion ?? "0.0.1",
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fingerprintLabel(fp, deps.config),
+        },
+    });
+}
+/**
+ * Supersede the write-ahead intent for the outcomes whose composite bodies write
+ * NO summary of their own — a refusal, an unsupported verb, or a verification
+ * failure that is not a timeout. Those all mean "this key is finished and
+ * nothing landed", and without a record saying so the intent would stand
+ * unsuperseded: once this process exits, its holder reads as dead and every
+ * later use of the key would be met with a reconcile refusal for a change that
+ * never happened.
+ *
+ * The two outcomes NOT closed here are the two the bodies already record: `ok`
+ * (the success summary, the verb's single undoable unit) and a `timeout`
+ * verify-failed (the AMBIGUOUS summary carrying the presence oracle). Writing a
+ * second record for either would compete with the one the caller's replay is
+ * meant to find.
+ */
+function closeSummaryIntent(deps, op, keyed, outcome) {
+    if (outcome.kind === "ok" || outcome.kind === "dry-run")
+        return;
+    if (outcome.kind === "verify-failed" && outcome.reason === "timeout")
+        return;
+    const result = outcome.kind === "blocked"
+        ? blockedCode(outcome)
+        : outcome.kind === "unsupported"
+            ? "unsupported"
+            : verifyFailedCode(outcome);
+    appendSummaryIntent(deps, op, keyed, result);
+}
 export async function runMutation(deps, op, params, options = {}) {
     const startedAt = deps.now?.() ?? new Date();
     // Things' own "Enable Things URLs" standing, read at most ONCE per mutation
@@ -452,17 +520,29 @@ export async function runMutation(deps, op, params, options = {}) {
     catch (err) {
         if (err instanceof MutationLockError) {
             audit({ result: blockedCode({ reason: "lock" }) });
-            return {
-                kind: "blocked",
-                op,
-                reason: "lock",
-                detail: err.message,
-                remediation: "wait for the concurrent mutation to finish and retry",
-            };
+            return { kind: "blocked", op, reason: "lock", ...describeLockRefusal(err) };
         }
         throw err;
     }
     try {
+        // 2a. DOUBLE-CHECKED IDEMPOTENCY (#639). The consumer entry already ran this
+        // lookback before we got here — but it ran it BEFORE the lock, and the whole
+        // point of a lock is that the world changes while you wait for it. A retry
+        // fired while the original was still mid-drive saw no record, queued here,
+        // and used to wake up after the original finished and execute the verb a
+        // SECOND time. Re-asking under the lock is what makes the earlier answer
+        // safe to have acted on: by now the original has written its record, so the
+        // answer is a replay (or a reconcile refusal) instead of a duplicate.
+        //
+        // The pre-lock check is kept as the cheap fast path — a settled key never
+        // reaches the lock at all — so this costs one extra trail read on exactly
+        // the writes that raced.
+        // (Returning here releases the lock through the `finally` below — never an
+        // explicit release as well: releasing twice unlinks whatever lock the NEXT
+        // writer has since created.)
+        const locked = replayIfApplied(deps, options);
+        if (locked !== null)
+            return locked;
         // 3. Pre-read. The consumer zone (options.zone ?? deps.zone) is threaded so
         // any boundary-derived pre-state (the reorder swept/unswept log boundary,
         // LOGSORT ORD-13) is computed under the SAME zone the reads use.
@@ -543,12 +623,36 @@ export async function runMutation(deps, op, params, options = {}) {
             }
             params = norm.params;
         }
+        // 3c. The series RE-ANCHOR's VERSION gate (REANCH1 §6). A dated `when=` on a
+        // repeating template re-anchors the series on Things 3.23 and KILLS the
+        // process on 3.22.14 — an unannounced behavior change, in the unusual
+        // direction. So the capability is gated on the installed version and fails
+        // CLOSED on an unreadable one; below the gate the dialog spelling (which
+        // works on both lines) is the remedy. Checked here, before planning, so the
+        // refusal names the version rather than surfacing as an unsupported vector.
+        if ((op === "todo.reschedule-repeat" || op === "project.reschedule-repeat") &&
+            isRepeatReanchor(params) &&
+            !urlReanchorSupported(deps.environment?.capture().thingsVersion ?? null)) {
+            audit({ result: blockedCode({ reason: "environment" }) });
+            return {
+                kind: "blocked",
+                op,
+                reason: "environment",
+                detail: "this version of Things cannot move a repeating item's next occurrence on its own — " +
+                    "the version that can is 3.23 or later",
+                remediation: "restate the rule instead: `things " +
+                    (op.startsWith("project.") ? "project" : "todo") +
+                    " reschedule-repeat <ref> --frequency <freq> --interval <n> --when <date> " +
+                    "--dangerously-drive-gui`, or update Things",
+            };
+        }
         // 4. Vector planning under the disruption policy.
         const appRunning = (deps.isAppRunning ?? defaultIsAppRunning)();
         const plan = planVector(op, deps.vectors, {
             maxDisruption,
             appRunning,
             allowExperimental: config.allowExperimental,
+            ...(spec.vectorsFor !== undefined && { allowVectors: spec.vectorsFor(params) }),
             ...(options.vector !== undefined && { forcedVector: options.vector }),
         });
         if (plan.kind === "unsupported") {
@@ -674,6 +778,8 @@ export async function runMutation(deps, op, params, options = {}) {
             const preEval = evaluateDelta(delta, preReader, preCapture);
             if (preEval.satisfied) {
                 const uuid = delta.uuid;
+                const noOp = newDisclosures();
+                disclose(noOp, "already-in-state", "the item was already in the requested state — no GUI drive was performed (idempotent no-op)");
                 audit({
                     result: "ok",
                     vector: vector.id,
@@ -693,9 +799,7 @@ export async function runMutation(deps, op, params, options = {}) {
                     vector: vector.id,
                     tier: effectiveTier,
                     // No undoToken: nothing changed, so there is nothing to invert.
-                    warnings: [
-                        "the item was already in the requested state — no GUI drive was performed (idempotent no-op)",
-                    ],
+                    ...tiers(noOp),
                 };
             }
         }
@@ -866,6 +970,12 @@ export async function runMutation(deps, op, params, options = {}) {
         // ONLY evidence the mutation may have landed. `things doctor` surfaces such
         // orphans; the final record written after verify supersedes this one.
         // (dry-run returned above, so nothing is recorded for a dry-run — preserved.)
+        //
+        // A KEYED write additionally makes this intent READABLE (#639): the holder's
+        // instance identity turns "no outcome recorded" into a decidable question
+        // (still running vs. died mid-flight), and `expected` gives a dead holder's
+        // resubmission the same presence oracle a timeout gets. Both are recorded
+        // only under a key — an unkeyed intent is crash evidence nobody polls.
         const intentUuid = delta.mode === "update" || delta.mode === "state"
             ? delta.uuid
             : delta.mode === "ordering"
@@ -878,6 +988,7 @@ export async function runMutation(deps, op, params, options = {}) {
             invocation: invocation.redactedPayload,
             pre: flattenPreFields(preCapture.fields),
             uuid: intentUuid,
+            ...(options.opId !== undefined && { holder: currentInstance(), expected: delta }),
         });
         // Mark the write as touching the app (read by the CLI's signal handler so a
         // SIGTERM/SIGINT can name the exact op — and last UI step — it interrupted,
@@ -962,6 +1073,7 @@ export async function runMutation(deps, op, params, options = {}) {
                         invocation: invocation.redactedPayload,
                         pre: flattenPreFields(preCapture.fields),
                         observed: recovery.observed,
+                        ...stepsOf(executeResult),
                         // The watchdog abort is THE ambiguous outcome — the detail below says
                         // so — so the assertion rides the record and a resubmission with the
                         // same opId re-reads state instead of risking the duplicate.
@@ -990,6 +1102,7 @@ export async function runMutation(deps, op, params, options = {}) {
                             `retrying (retrying could create a duplicate series).${traceNote}`,
                         uncertain: true,
                         ...(wd.tracePath != null && wd.tracePath !== "" && { tracePath: wd.tracePath }),
+                        ...stepsOf(executeResult),
                     };
                 }
                 // The ui drive stopped because the Things WINDOW stopped answering
@@ -1011,6 +1124,7 @@ export async function runMutation(deps, op, params, options = {}) {
                         invocation: invocation.redactedPayload,
                         pre: flattenPreFields(preCapture.fields),
                         observed: recovery.observed,
+                        ...stepsOf(executeResult),
                     });
                     return {
                         kind: "verify-failed",
@@ -1018,6 +1132,7 @@ export async function runMutation(deps, op, params, options = {}) {
                         reason: "ui-unreachable",
                         expected: delta,
                         observed: recovery.observed,
+                        ...stepsOf(executeResult),
                         detail: `the Things window could not be driven: the drive stopped at step ` +
                             `"${unreachable.step}" because ` +
                             (unreachable.cause === "unreachable"
@@ -1106,7 +1221,8 @@ export async function runMutation(deps, op, params, options = {}) {
             // and a row whose umd did not rise needs no restore (a silent op — no-op).
             // Best-effort: a failed restore is disclosed per row, never fatal (the
             // mutation already stands). The captured pre-values ride the audit record
-            // when the flag is active (enables a future symmetric undo).
+            // when the flag is active, which is what the symmetric undo restores from
+            // (undo.ts, keyed on `preModDates`).
             let preserve = null;
             let preModDatesAudit;
             if (options.preserveModified === true) {
@@ -1125,10 +1241,15 @@ export async function runMutation(deps, op, params, options = {}) {
                     preModDatesAudit = captured;
                 preserve = await restoreModDates(deps.db, deps.vectors, targets);
             }
+            // The change-history record is the APPEND-ONLY DEBUG LOG (#632): it
+            // captures the drive's step list on success as well as on failure, so the
+            // play-by-play a default success output no longer prints is still
+            // retrievable — `things op-result <key>` renders it.
             audit({
                 ...auditCommon,
                 result: "ok",
                 uuid,
+                ...stepsOf(executeResult),
                 ...(preModDatesAudit !== undefined && { preModDates: preModDatesAudit }),
             });
             if (deps.environment !== undefined) {
@@ -1154,12 +1275,12 @@ export async function runMutation(deps, op, params, options = {}) {
                     uuid,
                     ...(options.txn !== undefined && { txn: options.txn }),
                 });
-            const warnings = [];
+            const bag = newDisclosures();
             // Auto-launch disclosure (#486): the app was not running when this write
             // started, so it was background-launched for the write. Never silent — a
             // side effect the caller should see (a simulating vector never launches).
             if (!appRunning && vector.simulates !== true) {
-                warnings.push("Things was not running, so it was launched in the background for this write");
+                disclose(bag, "auto-launch", "Things was not running, so it was launched in the background for this write");
             }
             // Template-delete disclosure (public deletes only — internal trash-both legs
             // run under a txn and aggregate their own result). The series stops, its live
@@ -1168,48 +1289,64 @@ export async function runMutation(deps, op, params, options = {}) {
             if (templateDelete && options.txn?.role !== "leg" && pre.target !== null) {
                 const kindNoun = op === "project.delete" ? "project" : "to-do";
                 const series = liveSeriesInstances(deps.db, pre.target.uuid);
-                warnings.push("this repeating series will no longer generate new occurrences");
+                disclose(bag, "template-delete-series-stops", "this repeating series will no longer generate new occurrences");
                 if (series.count > 0) {
-                    warnings.push(`its ${series.count} existing occurrence${series.count === 1 ? " was" : "s were"} ` +
+                    disclose(bag, "template-delete-occurrences-left", `its ${series.count} existing occurrence${series.count === 1 ? " was" : "s were"} ` +
                         "left in place (not moved to the Trash)" +
                         (series.currentUuid !== null ? ` — the current one is ${series.currentUuid}` : ""));
                 }
-                warnings.push(`this cannot be undone here — to bring the series back, use the Things app's Trash ` +
+                disclose(bag, "template-delete-irreversible", `this cannot be undone here — to bring the series back, use the Things app's Trash ` +
                     `(Put Back on the ${kindNoun})`);
             }
             if (transportRecovered) {
-                warnings.push("the GUI drive reported a transport error, but a follow-up re-read confirmed the " +
+                disclose(bag, "transport-recovered", "the GUI drive reported a transport error, but a follow-up re-read confirmed the " +
                     "requested change DID land — no retry is needed (retrying could overwrite it)");
             }
-            if (outcome.repeatingWarnings !== undefined)
-                warnings.push(...outcome.repeatingWarnings);
+            // The instance-derivation disclosures arrive ALREADY TIERED from the
+            // expectation assertion (#634) — carried, never reclassified here.
+            carry(bag, outcome.repeatingDisclosures);
             // DACON1 off-rule-first disclosure (reschedule-repeat): an explicit anchor
             // that disagrees with --when lands an OFF-RULE first occurrence (honored for
             // weekly/yearly). State both halves of the landed pattern; the dishonored
             // monthly shape was already refused at validation. (make/add-repeating carry
             // their own disclosure via the promote result.)
             if (op === "todo.reschedule-repeat" || op === "project.reschedule-repeat") {
-                const offRuleParams = params;
-                const offRule = assessOffRuleFirst(offRuleParams, preservedDeadlineOffsetFor(pre, offRuleParams));
-                if (offRule?.kind === "honored")
-                    warnings.push(offRule.disclosure.message);
+                const reschedule = params;
+                if (isRepeatReanchor(reschedule)) {
+                    // The three things a re-anchor does that the caller did not ask for,
+                    // all measured (REANCH1 §2.3, §2.2/§7, §8): the recurring pattern moves
+                    // with the date, the slots in between are dropped, and there is no
+                    // headless way back.
+                    disclose(bag, "reanchor-series-moved", `the whole series moved: it now repeats from ${reschedule.next} — a weekly item ` +
+                        "moved to a Thursday repeats on Thursdays, a monthly one moved to the 17th " +
+                        "repeats on the 17th");
+                    disclose(bag, "reanchor-slots-skipped", `any occurrence due before ${reschedule.next} will not appear — the series resumes ` +
+                        "on the new date");
+                    disclose(bag, "reanchor-irreversible", "this cannot be undone here — move the series to another date, or use the Things " +
+                        "app's own undo");
+                }
+                else {
+                    const offRuleParams = reschedule;
+                    const offRule = assessOffRuleFirst(offRuleParams, preservedDeadlineOffsetFor(pre, offRuleParams));
+                    if (offRule?.kind === "honored") {
+                        disclose(bag, "promote-off-rule-first", offRule.disclosure.message);
+                    }
+                }
             }
             if (vector.id === "ui") {
-                warnings.push("this change was applied by driving the local Things app through the Accessibility API");
-                // Surface the drive's own step summary (e.g. how a sidebar move was
-                // performed: one drag / scroll-while-held / N hops) — behavior detail
-                // the caller can log, and the lab's certification evidence.
-                const driveSummary = executeResult.stdout.trim();
-                if (driveSummary !== "")
-                    warnings.push(driveSummary);
+                // COMPRESSED mechanism disclosure (#632). The old sentence spent a line
+                // explaining the Accessibility API on every GUI-applied write; `vector`
+                // and `tier` already carry the fact structurally, so the prose is now
+                // just the few words a reader needs to place it.
+                disclose(bag, "ui-mechanism", `applied via GUI drive (tier ${effectiveTier})`);
                 const cert = certificationOf(op);
                 if (cert !== undefined && cert.status !== "certified") {
-                    warnings.push(`this operation is ${cert.status}: its GUI recipe has not been confirmed on real ` +
+                    disclose(bag, "ui-recipe-uncertified", `this operation is ${cert.status}: its GUI recipe has not been confirmed on real ` +
                         "hardware (see `things doctor` / docs/lab/ui-certification-runbook.md)");
                 }
             }
             if (envChanges.length > 0) {
-                warnings.push(`environment changed since the last verified write: ` +
+                disclose(bag, "environment-changed", `environment changed since the last verified write: ` +
                     `${describeEnvironmentChanges(envChanges)} — the first use of another ` +
                     `capability may show a macOS consent prompt`);
             }
@@ -1246,12 +1383,18 @@ export async function runMutation(deps, op, params, options = {}) {
                 ...(preserve !== null &&
                     preserve.failures.length > 0 && { preserveFailures: preserve.failures }),
                 ...(completionContext !== undefined && { context: completionContext }),
-                ...(warnings.length > 0 && { warnings }),
+                // The step list rides a SUCCESS only when the caller asked for it —
+                // the diagnostic ladder's middle rung (#632).
+                ...(options.verbose === true && stepsOf(executeResult)),
+                ...tiers(bag),
             };
         }
+        // A FAILURE always carries the drive's play-by-play — on the record and on
+        // the result (#632). It is why the field bug reports were rich enough to fix.
         audit({
             ...auditCommon,
             result: verifyFailedCode({ reason: outcome.kind }),
+            ...stepsOf(executeResult),
             // A TIMEOUT is the one ambiguous verdict — the change may or may not have
             // landed — so the assertion this attempt was checking is recorded with it.
             // A resubmission carrying the same opId re-evaluates it against current
@@ -1264,6 +1407,7 @@ export async function runMutation(deps, op, params, options = {}) {
             reason: outcome.kind,
             expected: delta,
             observed: outcome.observed,
+            ...stepsOf(executeResult),
             detail: 
             // The collateral verdict carries its own sentence — which field moved,
             // from what to what, and why a retry is not the answer (CGRD1).