things-api 0.18.0 → 0.19.1

package/dist/write/opid.d.ts

@@ -1,31 +1,89 @@
 /**
  * Shared client-idempotency (`opId`) machinery — the ONE place the lookback
- * window and match rule live, so the batch path and the single-op path agree by
- * construction rather than by two copies staying in sync.
+ * window, the match rule and the ambiguous-outcome reconciliation live, so the
+ * batch path and the single-op path agree by construction rather than by two
+ * copies staying in sync.
  *
  * An `opId` is a caller-supplied idempotency key recorded on the audit record of
  * the mutation it accompanied. Before a mutation that carries one is dispatched,
- * the recent change history is scanned for an `ok` record bearing the SAME id;
- * on a hit the mutation is SKIPPED (reported already-applied) rather than
- * re-run. The id namespace is the whole trail — a batch leg and a single op that
- * share an id match each other — so resubmitting an ambiguously-failed write
- * (as a batch line OR a single `--op-id` invocation) is safe against a double.
+ * the recent change history is scanned for a record bearing the SAME id; on a
+ * hit the mutation is SKIPPED (reported already-applied) rather than re-run. The
+ * id namespace is the whole trail — a batch leg and a single op that share an id
+ * match each other — so resubmitting an ambiguously-failed write (as a batch
+ * line OR a single `--op-id` invocation) is safe against a double.
+ *
+ * Two match classes:
+ *
+ *  - a VERIFIED-OK record — the earlier change is known to have landed, so the
+ *    resubmission replays its identity and runs nothing;
+ *  - a `verify-failed:timeout` record — the earlier attempt dispatched and never
+ *    confirmed, so what landed is unknown. That record carries the assertion the
+ *    attempt was verifying ({@link AuditRecord.expected}), and THAT assertion is
+ *    the presence oracle: re-evaluated against current state it says the change
+ *    is there (replay it, disclosing the reconciliation) or is absent (execute
+ *    normally). When the recorded assertion cannot distinguish the two — the
+ *    operation asserts a whole-database singleton, or nothing was recorded — the
+ *    resubmission is REFUSED with a pointer at the item, never guessed.
+ *
+ * Every other result class (blocked, unsupported, intent, the other
+ * verify-failed reasons) is not a match: a blocked/unsupported attempt changed
+ * nothing, a mismatch/silent-noop landed something the caller must look at
+ * first, and an intent marker means the attempt may still be in flight.
  */
 import type { AuditRecord } from "../audit/schema.ts";
+import { type MutationResult, type WriteDeps, type WriteOptions } from "./pipeline.ts";
+import { type DeltaSpec } from "./verify/delta.ts";
 /** The idempotency-key charset/length, identical for a batch line and a single-op flag. */
 export declare const OP_ID_RE: RegExp;
 /**
  * opId idempotency lookback: at most the last {@link OPID_LOOKBACK_RECORDS}
  * records, AND only the last {@link OPID_LOOKBACK_MS} (whichever is more
- * restrictive). Phase 1 matches VERIFIED-OK records only.
+ * restrictive).
  */
 export declare const OPID_LOOKBACK_RECORDS = 1000;
 export declare const OPID_LOOKBACK_MS: number;
+/** The disclosure a reconciled replay carries — see {@link reconcileTimedOut}. */
+export declare const RECONCILED_NOTE: string;
+/**
+ * The recent-history lookback for an opId: the most recent MATCHABLE record
+ * carrying that id, within the last {@link OPID_LOOKBACK_RECORDS} records AND
+ * the last {@link OPID_LOOKBACK_MS} (whichever is more restrictive). Undo/intent/
+ * blocked records are naturally excluded.
+ */
+export declare function findOpIdRecord(records: AuditRecord[], opId: string, now: Date): AuditRecord | undefined;
 /**
- * The recent-history lookback for an opId: the most recent `ok` record carrying
- * that id, within the last {@link OPID_LOOKBACK_RECORDS} records AND the last
- * {@link OPID_LOOKBACK_MS} (whichever is more restrictive). Undo/intent/blocked
- * records are naturally excluded — only `result === "ok"` matches (phase 1; the
- * verify-failed:timeout reconciliation variant is a queued phase-2 round).
+ * Can the recorded assertion decide, after the fact, whether the timed-out
+ * change landed? Usable means the assertion is keyed to a SUBJECT the attempt
+ * itself identified — a target row, or a creation probe naming the row it was
+ * making. Unusable means the assertion is either vacuous (nothing to check) or a
+ * whole-database singleton that names none of the items the call was about, so a
+ * satisfied assertion now says nothing about THIS call. `why` completes the
+ * sentence "… and <why>" in the refusal.
+ */
+export type PresenceOracle = {
+    usable: true;
+} | {
+    usable: false;
+    why: string;
+};
+export declare function presenceOracle(spec: DeltaSpec | undefined): PresenceOracle;
+/**
+ * The lookback as a DISPATCH DECISION over an already-read trail: the replay
+ * result when this key was already applied, a refusal when it matched an
+ * unsettleable attempt, or null when the write must run. Shared by the batch
+ * line path and {@link replayIfApplied}.
+ */
+export declare function resolveOpId(deps: WriteDeps, records: AuditRecord[], opId: string, now: Date): MutationResult | null;
+/**
+ * The dispatch decision for a SINGLE invocation, reading the trail itself. The
+ * ONE gate every single-invocation entry point calls before doing anything — the
+ * client's single-op `run`, and the composites that own their own dispatch (the
+ * complete/cancel/exception template-target verbs, the `--completed-at`
+ * flip-dance, and the promote-via-clone verbs; they never reach `run`, so
+ * without this the key would be recorded and never honored).
+ *
+ * Three conditions fail-open (run the write) rather than fail-closed: no key, a
+ * dry run (it mints and records nothing, so there is nothing to deduplicate
+ * against), or no trail to read.
  */
-export declare function findAppliedOpId(records: AuditRecord[], opId: string, now: Date): AuditRecord | undefined;
+export declare function replayIfApplied(deps: WriteDeps, options: WriteOptions): MutationResult | null;

package/dist/write/opid.js

@@ -1,25 +1,35 @@
+import { replayResultFromRecord, } from "./pipeline.js";
+import { readAuditRecords } from "./undo.js";
+import { createDbReader, evaluateDelta } from "./verify/delta.js";
 /** The idempotency-key charset/length, identical for a batch line and a single-op flag. */
 export const OP_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 /**
  * opId idempotency lookback: at most the last {@link OPID_LOOKBACK_RECORDS}
  * records, AND only the last {@link OPID_LOOKBACK_MS} (whichever is more
- * restrictive). Phase 1 matches VERIFIED-OK records only.
+ * restrictive).
  */
 export const OPID_LOOKBACK_RECORDS = 1000;
 export const OPID_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
+/** The disclosure a reconciled replay carries — see {@link reconcileTimedOut}. */
+export const RECONCILED_NOTE = "an earlier submission with this idempotency key did not finish confirming; the change was " +
+    "found already in place, so nothing ran again. It cannot be reversed with `things undo` — the " +
+    "earlier attempt never recorded a completed change to reverse";
+/** Result classes an `opId` match acts on (see the module header). */
+function matchable(result) {
+    return result === "ok" || result === "verify-failed:timeout";
+}
 /**
- * The recent-history lookback for an opId: the most recent `ok` record carrying
- * that id, within the last {@link OPID_LOOKBACK_RECORDS} records AND the last
- * {@link OPID_LOOKBACK_MS} (whichever is more restrictive). Undo/intent/blocked
- * records are naturally excluded — only `result === "ok"` matches (phase 1; the
- * verify-failed:timeout reconciliation variant is a queued phase-2 round).
+ * The recent-history lookback for an opId: the most recent MATCHABLE record
+ * carrying that id, within the last {@link OPID_LOOKBACK_RECORDS} records AND
+ * the last {@link OPID_LOOKBACK_MS} (whichever is more restrictive). Undo/intent/
+ * blocked records are naturally excluded.
  */
-export function findAppliedOpId(records, opId, now) {
+export function findOpIdRecord(records, opId, now) {
     const cutoff = now.getTime() - OPID_LOOKBACK_MS;
     const window = records.slice(-OPID_LOOKBACK_RECORDS);
     let match;
     for (const r of window) {
-        if (r.opId !== opId || r.result !== "ok")
+        if (r.opId !== opId || !matchable(r.result))
             continue;
         if (new Date(r.ts).getTime() < cutoff)
             continue;
@@ -27,4 +37,138 @@ export function findAppliedOpId(records, opId, now) {
     }
     return match;
 }
+export function presenceOracle(spec) {
+    if (spec === undefined) {
+        return {
+            usable: false,
+            why: "that attempt did not record what it was waiting to see",
+        };
+    }
+    switch (spec.mode) {
+        case "update":
+        case "state": {
+            const cascade = spec.mode === "state" ? (spec.cascade?.length ?? 0) : 0;
+            return spec.assert.length + cascade > 0
+                ? { usable: true }
+                : { usable: false, why: "it named no field whose value would show the change" };
+        }
+        case "entity-updated":
+            return spec.assert.length > 0
+                ? { usable: true }
+                : { usable: false, why: "it named no field whose value would show the change" };
+        case "create":
+            // An unbounded probe (sinceEpoch 0) matches any same-titled item ever
+            // created, so an older namesake would be read as this call's own work.
+            return spec.probe.sinceEpoch > 0
+                ? { usable: true }
+                : {
+                    usable: false,
+                    why: "its record of the new item is not bounded in time, so an older item of the same " +
+                        "name would be mistaken for it",
+                };
+        case "entity-created":
+        case "gone":
+            return { usable: true };
+        case "ordering":
+            return spec.sequence.length > 1
+                ? { usable: true }
+                : { usable: false, why: "a single item's order reads the same before and after" };
+        case "trash-emptied":
+            return {
+                usable: false,
+                why: "emptying the Trash records none of the items it destroyed, so an empty Trash now " +
+                    "says nothing about whether this call is what emptied it",
+            };
+        case "logged-now":
+            return {
+                usable: false,
+                why: "moving finished items to the Logbook records none of the items it moved, and Things " +
+                    "moves them on its own as well",
+            };
+        default: {
+            const exhaustive = spec;
+            throw new Error(`unknown delta mode: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/** The refusal: the key matched an unconfirmed attempt nothing here can settle. */
+function unreconcilable(record, why) {
+    const target = record.uuid === null ? "the item" : record.uuid;
+    return {
+        kind: "blocked",
+        op: record.op,
+        reason: "reconcile",
+        detail: `an earlier submission with this idempotency key (${record.ts}) never confirmed its ` +
+            `change, and ${why} — so whether that change took effect cannot be settled from here`,
+        remediation: `check ${target} in Things (\`things op-result ${record.opId ?? "<key>"}\` reports what the ` +
+            "earlier attempt recorded); once you know whether the change is there, leave it alone or " +
+            "re-run with a NEW --op-id",
+    };
+}
+/**
+ * Reconcile a resubmission against a TIMED-OUT original: re-read current state
+ * through the attempt's own recorded assertion and decide.
+ *
+ *  - satisfied  → the change is there: replay it as already-applied, disclosing
+ *    that a timeout was reconciled. The replay carries NO undo token — the trail
+ *    holds no completed-change record for undo to reverse — and takes its uuid
+ *    from the re-read, which is how a create whose uuid was never discovered
+ *    (recorded `uuid: null`) still answers with the row it made.
+ *  - not satisfied → the change is absent: return null so the write runs.
+ *  - no usable oracle → refuse (never a guess).
+ */
+function reconcileTimedOut(deps, record) {
+    const oracle = presenceOracle(record.expected);
+    if (!oracle.usable)
+        return unreconcilable(record, oracle.why);
+    const spec = record.expected;
+    const evaluation = evaluateDelta(spec, createDbReader(deps.db, deps.now?.() ?? new Date(), deps.zone), 
+    // The movement classification needs the attempt's pre-read, which is long
+    // gone; only `satisfied`/`observed` are consulted here, and neither uses it.
+    { modDates: {}, fields: {} });
+    if (!evaluation.satisfied)
+        return null;
+    const replay = replayResultFromRecord(record);
+    if (replay.kind !== "ok")
+        return replay; // replayResultFromRecord always builds an ok
+    const { undoToken: _noToken, ...rest } = replay;
+    return {
+        ...rest,
+        uuid: evaluation.discoveredUuid ?? record.uuid,
+        observed: evaluation.observed,
+        ...(evaluation.repeating !== undefined && { repeating: evaluation.repeating }),
+        warnings: [...(replay.warnings ?? []), RECONCILED_NOTE],
+    };
+}
+/**
+ * The lookback as a DISPATCH DECISION over an already-read trail: the replay
+ * result when this key was already applied, a refusal when it matched an
+ * unsettleable attempt, or null when the write must run. Shared by the batch
+ * line path and {@link replayIfApplied}.
+ */
+export function resolveOpId(deps, records, opId, now) {
+    const match = findOpIdRecord(records, opId, now);
+    if (match === undefined)
+        return null;
+    return match.result === "ok" ? replayResultFromRecord(match) : reconcileTimedOut(deps, match);
+}
+/**
+ * The dispatch decision for a SINGLE invocation, reading the trail itself. The
+ * ONE gate every single-invocation entry point calls before doing anything — the
+ * client's single-op `run`, and the composites that own their own dispatch (the
+ * complete/cancel/exception template-target verbs, the `--completed-at`
+ * flip-dance, and the promote-via-clone verbs; they never reach `run`, so
+ * without this the key would be recorded and never honored).
+ *
+ * Three conditions fail-open (run the write) rather than fail-closed: no key, a
+ * dry run (it mints and records nothing, so there is nothing to deduplicate
+ * against), or no trail to read.
+ */
+export function replayIfApplied(deps, options) {
+    if (options.opId === undefined || options.dryRun === true)
+        return null;
+    if (deps.auditDirPath === undefined)
+        return null;
+    return resolveOpId(deps, readAuditRecords(deps.auditDirPath), options.opId, deps.now?.() ?? new Date());
+}
 //# sourceMappingURL=opid.js.map

package/dist/write/opid.js.map

@@ -1 +1 @@
-{"version":3,"file":"opid.js","sourceRoot":"","sources":["../../src/write/opid.ts"],"names":[],"mappings":"AAeA,2FAA2F;AAC3F,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAsB,EACtB,IAAY,EACZ,GAAS;IAET,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,gBAAgB,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACrD,IAAI,KAA8B,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;YAAE,SAAS;QACnD,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,MAAM;YAAE,SAAS;QAChD,KAAK,GAAG,CAAC,CAAC,CAAC,4DAA4D;IACzE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"opid.js","sourceRoot":"","sources":["../../src/write/opid.ts"],"names":[],"mappings":"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"}

package/dist/write/param-schema.d.ts

@@ -0,0 +1,80 @@
+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 {};