things-api 0.10.0 → 0.12.0

package/dist/write/vectors/registry.js

@@ -3,9 +3,11 @@
  * equally validated candidates. Injectable for tests (FakeVector) and for
  * the lab, which runs the identical pipeline against probe vectors.
  */
+import { resolve } from "node:path";
 import { loadConfig } from "../../config.js";
 import { createAppleScriptVector } from "./applescript.js";
 import { createShortcutsVector } from "./shortcuts.js";
+import { createSimulatorVector, dbCarriesBenchMarker, simulatorFenceReason } from "./simulator.js";
 import { createUiVector } from "./ui.js";
 import { createUrlSchemeVector } from "./url-scheme.js";
 /**
@@ -15,9 +17,53 @@ import { createUrlSchemeVector } from "./url-scheme.js";
  * are never dispatched. `config` is read from disk when not supplied (the
  * `things capabilities` surface has no client). `uiAux` carries the database
  * seam the sidebar drag driver asserts between hops — the client wires it;
- * surfaces that never execute (capabilities) omit it.
+ * surfaces that never execute (capabilities) omit it. `resolvedDbPath` is the
+ * database path the client actually opened (from openThings's resolution); it
+ * anchors the simulator fence's equality check so the applier and the pipeline's
+ * verifier can never split-brain across two different databases.
  */
-export function defaultVectors(config = loadConfig(), uiAux = {}) {
+export function defaultVectors(config = loadConfig(), uiAux = {}, resolvedDbPath) {
+    // Bench harness (Phase 0): THINGS_SIM_WRITES=1 REQUESTS simulated writes. When
+    // it is unset (the ordinary path) the real transports are returned unchanged.
+    // When it IS set, the simulator's fence MUST hold — THINGS_DB names a fenced
+    // bench fixture (marker present, not the production container) AND equals the
+    // database the client opened. If any part is unsatisfied we FAIL CLOSED with a
+    // clear error rather than silently falling through to the real transports:
+    // in this mode no url-scheme/applescript/shortcuts/ui path may reach a real app.
+    if (process.env["THINGS_SIM_WRITES"] === "1") {
+        const thingsDb = process.env["THINGS_DB"];
+        if (thingsDb === undefined || thingsDb.trim() === "") {
+            throw new Error(`${FENCE_UNSATISFIED}THINGS_DB is not set`);
+        }
+        // dbPath equality: the client-opened DB must be the fenced DB (normalized),
+        // else the applier would write one database while the verifier reads another.
+        if (resolvedDbPath !== undefined && resolve(resolvedDbPath) !== resolve(thingsDb)) {
+            throw new Error(`${FENCE_UNSATISFIED}the database the client opened (${resolvedDbPath}) does not equal ` +
+                `THINGS_DB (${thingsDb})`);
+        }
+        const reason = simulatorFenceReason(thingsDb);
+        if (reason !== null) {
+            throw new Error(`${FENCE_UNSATISFIED}${reason}`);
+        }
+        return [createSimulatorVector(thingsDb)];
+    }
+    // Marker fail-closed (2026-07-17 incident): a database carrying the
+    // benchFixture marker is a synthetic bench fixture BY CONSTRUCTION, and the
+    // only legitimate way to write "against" one is the simulator. Reaching this
+    // point with a marked DB means the env fence is absent/incomplete (the exact
+    // shape of the escape that fired real url-scheme adds at a live app while
+    // verification read the fixture) — refuse rather than return real transports.
+    const envDb = process.env["THINGS_DB"];
+    const markedPath = [resolvedDbPath, envDb]
+        .filter((p) => p !== undefined && p.trim() !== "")
+        .find((p) => dbCarriesBenchMarker(p));
+    if (markedPath !== undefined) {
+        throw new Error(`the database in use (${markedPath}) is a bench fixture (Meta.benchFixture marker) but ` +
+            "the simulator fence is not active — refusing to dispatch real write transports " +
+            "against a live app on behalf of a synthetic fixture. Set the full fence env " +
+            "(THINGS_SIM_WRITES=1, THINGS_DB, scratch THINGS_API_STATE_DIR/THINGS_API_CONFIG_DIR) " +
+            "or use an unmarked DB.");
+    }
     return [
         createUrlSchemeVector(),
         createAppleScriptVector(),
@@ -25,4 +71,5 @@ export function defaultVectors(config = loadConfig(), uiAux = {}) {
         createUiVector(config, undefined, uiAux),
     ];
 }
+const FENCE_UNSATISFIED = "simulated writes requested but the fence is unsatisfied: ";
 //# sourceMappingURL=registry.js.map

package/dist/write/vectors/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/write/vectors/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA0B,UAAU,EAAE,EACtC,QAAoB,EAAE;IAEtB,OAAO;QACL,qBAAqB,EAAE;QACvB,uBAAuB,EAAE;QACzB,qBAAqB,EAAE;QACvB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC;KACzC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/write/vectors/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGnG,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA0B,UAAU,EAAE,EACtC,QAAoB,EAAE,EACtB,cAAuB;IAEvB,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,iFAAiF;IACjF,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,GAAG,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,GAAG,iBAAiB,sBAAsB,CAAC,CAAC;QAC9D,CAAC;QACD,4EAA4E;QAC5E,8EAA8E;QAC9E,IAAI,cAAc,KAAK,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClF,MAAM,IAAI,KAAK,CACb,GAAG,iBAAiB,mCAAmC,cAAc,mBAAmB;gBACtF,cAAc,QAAQ,GAAG,CAC5B,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,GAAG,iBAAiB,GAAG,MAAM,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,oEAAoE;IACpE,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,8EAA8E;IAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC;SACvC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;SAC9D,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,wBAAwB,UAAU,sDAAsD;YACtF,iFAAiF;YACjF,8EAA8E;YAC9E,uFAAuF;YACvF,wBAAwB,CAC3B,CAAC;IACJ,CAAC;IACD,OAAO;QACL,qBAAqB,EAAE;QACvB,uBAAuB,EAAE;QACzB,qBAAqB,EAAE;QACvB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,iBAAiB,GAAG,2DAA2D,CAAC"}

package/dist/write/vectors/shortcuts.js

@@ -20,7 +20,7 @@ import { join } from "node:path";
 /** First-run consent can stall the run; give it generous headroom. */
 const SHORTCUTS_TIMEOUT_MS = 25_000;
 export const SHORTCUTS_MATRIX = {
-    "heading.create": {
+    "project.add-heading": {
         support: "yes",
         disruption: 0,
         validation: "validated",

package/dist/write/vectors/shortcuts.js.map

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

package/dist/write/vectors/simulator.d.ts

@@ -0,0 +1,44 @@
+import type { OperationKind } from "../operations.ts";
+import type { WriteVector } from "./types.ts";
+/**
+ * The fence reason, or null when the simulator may run against `dbPath`. Pure
+ * with respect to `env`; opens `dbPath` READ-ONLY only to read the marker.
+ */
+export declare function simulatorFenceReason(dbPath: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The Things schema generation the appliers are written against. When a
+ * Things update bumps the real database version, the fence refuses to
+ * simulate until the whole modeling chain is consciously re-verified —
+ * a schema tripwire, not a compatibility claim.
+ */
+export declare const SIMULATED_DATABASE_VERSION = 26;
+/** Whether the simulator's triple fence is satisfied for `dbPath`. */
+export declare function simulatorFenceActive(dbPath: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the simulator fence is active for the ambient environment — the
+ * single signal every host-escaping code path (reveal `open`, setup install
+ * sheets, the live-app doctor probes, the pipeline's app-launch) consults so a
+ * bench run never touches the real Things/Shortcuts app. True only when
+ * THINGS_SIM_WRITES=1 AND THINGS_DB names a fenced bench fixture (marker
+ * present, not the production container); false — the ordinary path — otherwise.
+ */
+export declare function simFenceActive(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the database at `dbPath` carries the bench-fixture marker — i.e. it
+ * is a synthetic bench DB by construction. Consulted by defaultVectors as a
+ * fail-closed backstop (a marked DB must never be paired with real write
+ * transports) and by the reveal gate. False on any read error.
+ */
+export declare function dbCarriesBenchMarker(dbPath: string): boolean;
+/** The ops this simulator can apply — the ONLY entries in its honest matrix. */
+export declare const SIMULATOR_COVERAGE: OperationKind[];
+/**
+ * Build the simulator vector for `dbPath`. Throws at creation if the fence is
+ * not satisfied (so a misconfigured harness fails loud, never silently writing
+ * to a wrong DB). `now` is injectable for tests; production reads the effective
+ * clock from the environment (THINGS_NOW) so applier timestamps align with the
+ * pipeline's, which the create-probe verification depends on.
+ */
+export declare function createSimulatorVector(dbPath: string, opts?: {
+    now?: () => Date;
+}): WriteVector;