things-api 0.10.0 → 0.12.0

package/dist/write/pipeline.d.ts

@@ -1,14 +1,16 @@
 import type { DatabaseSync } from "node:sqlite";
 import type { AuditWriter } from "../audit/log.ts";
+import { type AuditRecord } from "../audit/schema.ts";
 import type { DisruptionTier, ThingsApiConfig } from "../config.ts";
 import type { FingerprintStatus } from "../db/fingerprint.ts";
+import { type ResolvedScope } from "../read/scope.ts";
 import { type ShortcutsState } from "./availability.ts";
 import { type EnvironmentTracker } from "./environment.ts";
 import { type LikelyCause } from "./failure-hints.ts";
 import { type HazardId } from "./guards.ts";
-import type { Acknowledgements, OperationKind, OperationParamsMap } from "./operations.ts";
+import { type Acknowledgements, type OperationKind, type OperationParamsMap } from "./operations.ts";
 import type { VectorId, WriteVector } from "./vectors/types.ts";
-import { type DeltaSpec } from "./verify/delta.ts";
+import { type DeltaSpec, type RepeatingDiscovery } from "./verify/delta.ts";
 import { type PollerDeps } from "./verify/poller.ts";
 export interface WriteOptions extends Acknowledgements {
     /** Caps vector selection; defaults from the config profile. */
@@ -18,6 +20,16 @@ export interface WriteOptions extends Acknowledgements {
     verifyTimeoutMs?: number;
     /** Return the plan without executing (nothing is audited). */
     dryRun?: boolean;
+    /**
+     * Skip the post-execute state VERIFY poll for this write, treating a clean
+     * transport (exit 0) as ok. Fail-loud on the transport itself is preserved (a
+     * nonzero exit / deadline still runs the recovery re-verify). Used by the
+     * bounce orchestrator for the transient AWAY/BACK legs of a `when=` round-trip:
+     * the intermediate someday state is not independently verified — one verify
+     * per item round-trip (the placed-position + when-restore delta) is asserted by
+     * the orchestrator at item completion instead (reordgaps-results.md BOUNCE2).
+     */
+    skipVerify?: boolean;
     /**
      * Create any tag named in this op's tags that does not exist yet (through the
      * clean `make new tag` path, mkdir-p for `parent/child`) BEFORE applying —
@@ -38,6 +50,29 @@ export interface WriteOptions extends Acknowledgements {
      * already-undone mutation is distinguishable from a nonexistent one.
      */
     undoOf?: string;
+    /**
+     * Client idempotency id — a batch line's `opId` (set by the batch
+     * orchestrator) OR a single mutation's `--op-id` (set by the client `run`
+     * entry). Recorded on the audit record so a resubmission carrying the same id
+     * is recognized as already-applied. Recording is additive and never affects
+     * dispatch; the single-op idempotency CHECK (skip-and-replay on a match) runs
+     * in the client `run` entry before this pipeline is reached.
+     */
+    opId?: string;
+    /**
+     * Consumer IANA zone for THIS write, overriding the client's default zone.
+     * Only affects the clock-relative `when` tokens (today/evening) when
+     * {@link normalizeWhen} is set. Reminder times stay wall-clock and untranslated.
+     */
+    zone?: string;
+    /**
+     * Normalize a CONSUMER-provided clock-relative `when` (today/evening) to the
+     * effective consumer zone BEFORE dispatch — set by the consumer entry points
+     * (the client's `run`, batch), NEVER by the internal orchestrators (undo,
+     * reorder), whose when tokens converse with app-written host state and must
+     * stay on the host clock.
+     */
+    normalizeWhen?: boolean;
 }
 export interface MutationPlan {
     op: OperationKind;
@@ -51,6 +86,13 @@ export type MutationResult = {
     kind: "ok";
     op: OperationKind;
     uuid: string | null;
+    /**
+     * The mutated item's title (ADDITIVE), when the op targets a single
+     * pre-existing item — its pre-write title, captured before the change.
+     * Lets a batch log confirm WHAT was mutated without a second read. Absent
+     * for create/reorder ops, which have no single pre-existing target.
+     */
+    title?: string;
     observed: Record<string, unknown> | null;
     vector: VectorId;
     tier: DisruptionTier;
@@ -60,8 +102,34 @@ export type MutationResult = {
      * unaffected by any other mutations made in between.
      */
     undoToken?: string;
+    /**
+     * Make-repeating conversions (todo/project make-repeating, and
+     * project.add-repeating via its promote leg): the discovered template
+     * uuid, the FK-derived current-occurrence instance (use this for the
+     * VISIBLE item), and the replaced original uuid — plus `childrenReplaced`
+     * for project conversions. `uuid` still equals `templateUuid` (use it to
+     * reschedule the repeat). Absent for every other op.
+     */
+    repeating?: RepeatingDiscovery;
     /** Advisory notes (e.g. a changed environment tuple — consent may re-prompt later). */
     warnings?: string[];
+    /**
+     * Co-bounced siblings (ADDITIVE): a bounce reorder that anchors a block
+     * with --before/--after (or lands it mid-bucket) must re-insert every
+     * UNNAMED member between the block and the bucket edge. Those items get a
+     * modification bump, a changes-feed entry, and an audit leg — disclosed
+     * here explicitly, never as fine print. Absent when only the named movees
+     * were touched.
+     */
+    touched?: string[];
+    /**
+     * Idempotency replay (ADDITIVE, presence-keyed): `true` when this result
+     * did NOT execute — a mutation carrying an `opId` matched a prior verified
+     * `ok` record with the same id in the recent change history, so the earlier
+     * change stands and nothing ran again. The `uuid`/`title`/`undoToken` echo
+     * the ORIGINAL mutation's identity. Absent on a normal (executed) result.
+     */
+    alreadyApplied?: true;
 } | {
     kind: "verify-failed";
     op: OperationKind;
@@ -75,7 +143,7 @@ export type MutationResult = {
 } | {
     kind: "blocked";
     op: OperationKind;
-    reason: "hazard" | "disruption-tier" | "drift" | "lock" | "environment";
+    reason: "hazard" | "disruption-tier" | "drift" | "lock" | "environment" | "clock" | "scope";
     hazard?: HazardId;
     detail: string;
     remediation: string;
@@ -111,9 +179,60 @@ export interface WriteDeps {
     /** Seam: installed Things proxy shortcuts, for the pre-dispatch availability gate (availability.ts). */
     shortcutProxies?: () => ShortcutsState;
     now?: () => Date;
+    /** Default consumer IANA zone (client-resolved from THINGS_TZ); normalizes consumer `when` tokens. */
+    zone?: string;
+    /**
+     * The active container scope (pinned at openThings). When set: uuid targets
+     * resolve scope-aware (out-of-scope == not-found parity), and the universal
+     * scope gate (evaluateScope) runs before the hazard guards. Absent = unscoped.
+     */
+    scope?: ResolvedScope;
     poller?: PollerDeps;
     pkgVersion?: string;
+    /**
+     * Audit-trail directory (client-wired): read by `runBatch` for the opId
+     * idempotency lookback. Absent = no lookback (opId dedup is a no-op), which is
+     * the correct degraded behavior when the trail is unavailable.
+     */
+    auditDirPath?: string;
 }
 export declare function readAuthToken(db: DatabaseSync): string | null;
+/**
+ * Normalize a CONSUMER-provided clock-relative `when` for the effective zone,
+ * so the app (which would interpret the bare word on the HOST clock) never sees
+ * a relative token that means a different calendar date for the consumer.
+ *
+ * - `today` → the consumer-zone calendar date, dispatched as an explicit
+ *   `when=YYYY-MM-DD` (with any reminder still appended) so verification agrees
+ *   by construction. When the consumer's today already equals the app's today
+ *   the token is left as-is (byte-identical dispatch). A consumer-today that is
+ *   host-yesterday yields a past startDate — coherent (lands in Today with
+ *   overdue-start semantics), documented, not special-cased.
+ * - `evening` → This Evening exists ONLY for the app machine's own current day
+ *   (the startBucket=1 rows whose startDate is exactly the app's today; an
+ *   "evening of another day" is not representable in Things' model, not even in
+ *   the GUI — see src/read/views.ts). Refused fail-closed when the dates differ.
+ *
+ * Reminder times are wall-clock and tz-less in Things' own model — never
+ * translated here.
+ */
+export declare function normalizeConsumerWhen(params: Record<string, unknown>, now: Date, zone: string): {
+    ok: true;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    detail: string;
+    remediation: string;
+};
 export declare function runMutation<K extends OperationKind>(deps: WriteDeps, op: K, params: OperationParamsMap[K], options?: WriteOptions): Promise<MutationResult>;
+/**
+ * Build the single-op idempotency REPLAY result from the matched audit record —
+ * a `kind: "ok"` MutationResult that did not execute (`alreadyApplied: true`),
+ * echoing the ORIGINAL mutation's identity. Mirrors the pipeline's own
+ * result-shaping: the `undoToken` is surfaced under the SAME rule the executor
+ * uses (only for a non-leg, reversible op — an irreversible op or a batch leg
+ * carries none), and `title` rides `requested.title` when the record stored one
+ * (the audit record has no dedicated title field — see the trail-record note).
+ */
+export declare function replayResultFromRecord(record: AuditRecord): MutationResult;
 export declare function fingerprintLabel(fp: FingerprintStatus, config: ThingsApiConfig): "ok" | "drift" | "user-accepted" | "unknown";