@daski/pay 0.3.1 → 0.4.1

package/dist/store/lock.d.ts

@@ -0,0 +1,59 @@
+import type { CliError } from "../cli/errors.js";
+/** Why an acquisition gave up: a live or unverifiable owner kept it past the wait, or a reclaim was left by a dead process. */
+export type LockRefusal = "held" | "orphaned";
+/**
+ * The facts a lock owner's identity is recorded from and checked against.
+ * Injectable so a test can describe another boot, namespace, or host without
+ * switching any of them.
+ */
+export interface LockHost {
+    platform: NodeJS.Platform;
+    hostname(): string;
+    /** Linux: `/proc/sys/kernel/random/boot_id`; undefined when it cannot be read. */
+    bootId(): string | undefined;
+    /** Linux: this process's pid namespace (`/proc/self/ns/pid`); undefined when it cannot be read. */
+    pidNamespace(): string | undefined;
+    /** Linux: field 22 of `/proc/<pid>/stat`; `gone` when `/proc/<pid>` is absent; undefined when it cannot be read. */
+    startTime(pid: number): string | "gone" | undefined;
+    /** `process.kill(pid, 0)`: false only on ESRCH (a permission error still means the process exists). */
+    signalable(pid: number): boolean;
+}
+export interface FileLockOptions {
+    /** How long to wait for a live (or unverifiable) owner before giving up. */
+    waitMs: number;
+    /** The error raised when the wait expires (`held`) or recovery needs a person (`orphaned`). */
+    locked: (reason: LockRefusal) => CliError;
+    /** Where this process runs; defaults to the real host. */
+    host?: LockHost | undefined;
+}
+/** True when a process with this id exists (a permission error still means it exists). */
+export declare function processAlive(pid: number): boolean;
+/**
+ * Field 22 of a `/proc/<pid>/stat` line: the start time in clock ticks since
+ * boot. The command name (field 2) may contain spaces and parentheses, so
+ * fields are counted from the last closing parenthesis, after which field 3
+ * is first.
+ */
+export declare function startTimeFromStat(stat: string): string | undefined;
+/** The real host's facts. */
+export declare function nativeLockHost(platform?: NodeJS.Platform): LockHost;
+/**
+ * This process's identity as its lock tokens record it: `linux/<boot id>/<pid
+ * namespace>/<start time>`, or `host/<hostname>` off Linux. A part that cannot
+ * be read is left empty, which no reader verifies, so such a lock is only
+ * ever removed by hand.
+ */
+export declare function lockIdentity(host: LockHost, pid?: number): string;
+export type OwnerState = "alive" | "gone" | "unverifiable";
+/**
+ * Whether the owner a token names is still running. `gone` only when the
+ * recorded identity is verifiable from here and shows it: on Linux the same
+ * boot and pid namespace with `/proc/<pid>` absent or a different start time
+ * (the pid was reused); elsewhere the same hostname with ESRCH. Anything else
+ * (another boot, namespace, or host; `/proc` unavailable; a token without an
+ * identity) is `unverifiable`, which is treated like `alive`: never reclaimed.
+ */
+export declare function ownerState(host: LockHost, token: string): OwnerState;
+export declare function withFileLock<T>(lock: string, options: FileLockOptions, run: () => Promise<T>): Promise<T>;
+export declare function withFileLockSync<T>(lock: string, options: FileLockOptions, run: () => T): T;
+//# sourceMappingURL=lock.d.ts.map

package/dist/store/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,+HAA+H;AAC/H,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,QAAQ,IAAI,MAAM,CAAC;IACnB,kFAAkF;IAClF,MAAM,IAAI,MAAM,GAAG,SAAS,CAAC;IAC7B,mGAAmG;IACnG,YAAY,IAAI,MAAM,GAAG,SAAS,CAAC;IACnC,oHAAoH;IACpH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpD,uGAAuG;IACvG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,QAAQ,CAAC;IAC1C,0DAA0D;IAC1D,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B;AAKD,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQjD;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKlE;AAED,6BAA6B;AAC7B,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,QAAQ,CAuBrF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,SAAc,GAAG,MAAM,CAItE;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,cAAc,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAmBpE;AAgFD,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAID,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAiB3F"}

package/dist/store/lock.js

@@ -0,0 +1,269 @@
+/**
+ * Cross-process exclusive locks as files.
+ *
+ * A lock is created atomically and already populated: its owner (`pid random
+ * identity`) is written to a private staging file that is hard-linked into
+ * place, so two creators cannot both succeed and a lock is never observed
+ * empty. It is reclaimed only when that owner is verifiably gone (a live
+ * process may legitimately hold a lock for minutes, so elapsed time never
+ * decides), and reclamation is serialized through a reclaim lock: two waiters
+ * that both read a dead owner's token would otherwise both unlink, one of
+ * them removing the live lock the other had just created. A reclaim lock
+ * whose own owner died is not recovered automatically; that needs a person,
+ * and the error says so. Release removes the file only while it still
+ * records this owner.
+ *
+ * A pid alone does not identify a process across the places one state
+ * directory can be shared: a container mount or Windows and WSL see each
+ * other's pids in different namespaces, so `process.kill(pid, 0)` answers
+ * ESRCH for a live owner. The token therefore records where the owner runs:
+ * on Linux the kernel boot id, the pid namespace, and the owner's start time
+ * (field 22 of `/proc/<pid>/stat`, which a reused pid does not repeat); on
+ * other platforms the hostname. An owner is reclaimable only when that
+ * identity can be verified from here and shows the process gone; an owner
+ * from another boot, namespace, or host, or one recorded without an identity,
+ * cannot be verified and is never reclaimed, so the waiter fails closed with
+ * the "locked, remove manually" remediation instead.
+ *
+ * Two flavours share the logic. The asynchronous one serializes keystore
+ * updates and one order's confirmation journal across gateway and chain
+ * calls. The synchronous one guards every whole-file read-modify-write of
+ * the order store, whose functions are synchronous; its critical section is
+ * milliseconds, so a short blocking wait is acceptable.
+ */
+import { closeSync, linkSync, mkdirSync, openSync, readFileSync, readlinkSync, rmSync, writeSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+const POLL_MS = 25;
+const SYNC_POLL_MS = 5;
+/** True when a process with this id exists (a permission error still means it exists). */
+export function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function readTrimmed(path) {
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Field 22 of a `/proc/<pid>/stat` line: the start time in clock ticks since
+ * boot. The command name (field 2) may contain spaces and parentheses, so
+ * fields are counted from the last closing parenthesis, after which field 3
+ * is first.
+ */
+export function startTimeFromStat(stat) {
+    const end = stat.lastIndexOf(")");
+    if (end < 0)
+        return undefined;
+    const start = stat.slice(end + 1).trim().split(/\s+/)[22 - 3];
+    return start !== undefined && /^\d+$/.test(start) ? start : undefined;
+}
+/** The real host's facts. */
+export function nativeLockHost(platform = process.platform) {
+    return {
+        platform,
+        hostname: () => hostname(),
+        bootId: () => readTrimmed("/proc/sys/kernel/random/boot_id"),
+        pidNamespace: () => {
+            try {
+                return /\[(\d+)\]/.exec(readlinkSync("/proc/self/ns/pid"))?.[1];
+            }
+            catch {
+                return undefined;
+            }
+        },
+        startTime: (pid) => {
+            let stat;
+            try {
+                stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            }
+            catch (error) {
+                return error.code === "ENOENT" ? "gone" : undefined;
+            }
+            return startTimeFromStat(stat);
+        },
+        signalable: processAlive,
+    };
+}
+/**
+ * This process's identity as its lock tokens record it: `linux/<boot id>/<pid
+ * namespace>/<start time>`, or `host/<hostname>` off Linux. A part that cannot
+ * be read is left empty, which no reader verifies, so such a lock is only
+ * ever removed by hand.
+ */
+export function lockIdentity(host, pid = process.pid) {
+    if (host.platform !== "linux")
+        return `host/${host.hostname()}`;
+    const start = host.startTime(pid);
+    return ["linux", host.bootId() ?? "", host.pidNamespace() ?? "", start === undefined || start === "gone" ? "" : start].join("/");
+}
+/**
+ * Whether the owner a token names is still running. `gone` only when the
+ * recorded identity is verifiable from here and shows it: on Linux the same
+ * boot and pid namespace with `/proc/<pid>` absent or a different start time
+ * (the pid was reused); elsewhere the same hostname with ESRCH. Anything else
+ * (another boot, namespace, or host; `/proc` unavailable; a token without an
+ * identity) is `unverifiable`, which is treated like `alive`: never reclaimed.
+ */
+export function ownerState(host, token) {
+    const [pidText, , identity] = token.split(" ");
+    const pid = Number(pidText);
+    if (!Number.isInteger(pid) || pid <= 0 || identity === undefined)
+        return "unverifiable";
+    const parts = identity.split("/");
+    if (parts[0] === "linux" && parts.length === 4) {
+        const [, bootId, namespace, start] = parts;
+        if (host.platform !== "linux" || !bootId || !namespace || !start)
+            return "unverifiable";
+        if (host.bootId() !== bootId || host.pidNamespace() !== namespace)
+            return "unverifiable";
+        const current = host.startTime(pid);
+        if (current === "gone")
+            return "gone";
+        if (current === undefined)
+            return "unverifiable";
+        return current === start ? "alive" : "gone";
+    }
+    if (parts[0] === "host" && parts.length === 2 && parts[1]) {
+        if (host.platform === "linux" || host.hostname() !== parts[1])
+            return "unverifiable";
+        return host.signalable(pid) ? "alive" : "gone";
+    }
+    return "unverifiable";
+}
+function owner(host) {
+    return `${process.pid} ${randomBytes(8).toString("hex")} ${lockIdentity(host)}`;
+}
+/** Create `path` holding `token`, atomically and populated; false when it exists. */
+function createExclusive(path, token) {
+    const staging = `${path}.${token.split(" ")[1]}.staging`;
+    const fd = openSync(staging, "wx", 0o600);
+    try {
+        writeSync(fd, token);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        linkSync(staging, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return false;
+    }
+    finally {
+        rmSync(staging, { force: true });
+    }
+}
+/** What a lock file records and whether that owner still runs; null when the file is absent. */
+function recorded(path, host) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return { content, state: ownerState(host, content) };
+}
+/** Remove the lock only while it still records this owner. */
+function release(path, token) {
+    let current;
+    try {
+        current = readFileSync(path, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (current === token)
+        rmSync(path, { force: true });
+}
+function attempt(lock, token, host) {
+    if (createExclusive(lock, token))
+        return "acquired";
+    const current = recorded(lock, host);
+    if (!current)
+        return "retry";
+    // A live owner keeps it; so does one that cannot be verified from here.
+    if (current.state !== "gone")
+        return "held";
+    // The owner died holding it. Only the holder of the reclaim lock unlinks,
+    // and only the exact file it inspected.
+    const reclaim = `${lock}.reclaim`;
+    if (!createExclusive(reclaim, token)) {
+        const reclaimer = recorded(reclaim, host);
+        return reclaimer?.state === "gone" ? "orphaned" : "retry";
+    }
+    try {
+        const again = recorded(lock, host);
+        if (again && again.content === current.content && again.state === "gone")
+            rmSync(lock, { force: true });
+    }
+    finally {
+        release(reclaim, token);
+    }
+    return "retry";
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function withFileLock(lock, options, run) {
+    mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
+    const host = options.host ?? nativeLockHost();
+    const token = owner(host);
+    const deadline = Date.now() + options.waitMs;
+    for (;;) {
+        const outcome = attempt(lock, token, host);
+        if (outcome === "acquired")
+            break;
+        if (outcome === "orphaned")
+            throw options.locked("orphaned");
+        if (Date.now() > deadline)
+            throw options.locked("held");
+        await sleep(POLL_MS);
+    }
+    try {
+        return await run();
+    }
+    finally {
+        release(lock, token);
+    }
+}
+const waiter = new Int32Array(new SharedArrayBuffer(4));
+export function withFileLockSync(lock, options, run) {
+    mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
+    const host = options.host ?? nativeLockHost();
+    const token = owner(host);
+    const deadline = Date.now() + options.waitMs;
+    for (;;) {
+        const outcome = attempt(lock, token, host);
+        if (outcome === "acquired")
+            break;
+        if (outcome === "orphaned")
+            throw options.locked("orphaned");
+        if (Date.now() > deadline)
+            throw options.locked("held");
+        Atomics.wait(waiter, 0, 0, SYNC_POLL_MS);
+    }
+    try {
+        return run();
+    }
+    finally {
+        release(lock, token);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/store/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,MAAM,OAAO,GAAG,EAAE,CAAC;AACnB,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9D,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,cAAc,CAAC,WAA4B,OAAO,CAAC,QAAQ;IACzE,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE;QAC1B,MAAM,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,iCAAiC,CAAC;QAC5D,YAAY,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC;gBACH,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QACD,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;YACjB,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACjF,CAAC;YACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;QACD,UAAU,EAAE,YAAY;KACzB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG;IAC5D,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,QAAQ,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnI,CAAC;AAID;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAc,EAAE,KAAa;IACtD,MAAM,CAAC,OAAO,EAAE,AAAD,EAAG,QAAQ,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QAC3C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK;YAAE,OAAO,cAAc,CAAC;QACxF,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,KAAK,SAAS;YAAE,OAAO,cAAc,CAAC;QACzF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACtC,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,cAAc,CAAC;QACjD,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9C,CAAC;IACD,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,cAAc,CAAC;QACrF,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACjD,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,KAAK,CAAC,IAAc;IAC3B,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,qFAAqF;AACrF,SAAS,eAAe,CAAC,IAAY,EAAE,KAAa;IAClD,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IACzD,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,SAAS,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IACD,IAAI,CAAC;QACH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAOD,gGAAgG;AAChG,SAAS,QAAQ,CAAC,IAAY,EAAE,IAAc;IAC5C,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,8DAA8D;AAC9D,SAAS,OAAO,CAAC,IAAY,EAAE,KAAa;IAC1C,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,KAAK;QAAE,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC;AAID,SAAS,OAAO,CAAC,IAAY,EAAE,KAAa,EAAE,IAAc;IAC1D,IAAI,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC;IAC7B,wEAAwE;IACxE,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IAC5C,0EAA0E;IAC1E,wCAAwC;IACxC,MAAM,OAAO,GAAG,GAAG,IAAI,UAAU,CAAC;IAClC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO,SAAS,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM;YAAE,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1G,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAE/F,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAAwB,EACxB,GAAqB;IAErB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7C,SAAS,CAAC;QACR,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,UAAU;YAAE,MAAM;QAClC,IAAI,OAAO,KAAK,UAAU;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,EAAE,CAAC;IACrB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAExD,MAAM,UAAU,gBAAgB,CAAI,IAAY,EAAE,OAAwB,EAAE,GAAY;IACtF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7C,SAAS,CAAC;QACR,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,UAAU;YAAE,MAAM;QAClC,IAAI,OAAO,KAAK,UAAU;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/store/orders.d.ts

@@ -1,3 +1,4 @@
+import type { Address, Hex } from "viem";
 export type OrderState = "INTENT_RECORDED" | "AUTHORIZED" | "SUBMITTED" | "FULFILLED" | "INPUT_REQUIRED" | "PROVIDER_FAILED" | "CANCELED" | "PENDING_RECONCILIATION"
 /** The gateway said the authorization did not settle; nothing was charged. */
  | "NOT_SETTLED";
@@ -7,6 +8,43 @@ export interface ReadCapability {
     /** Unix seconds. */
     expiresAt: number;
 }
+/** A sponsored review submission retained for retries while sponsorship is pending. */
+export interface ConfirmationSubmissionRecord {
+    action: "confirmation" | "revoke-confirmation";
+    request: {
+        phase: "submit";
+        submission: "sponsored";
+        preparationId: string;
+        signature: string;
+    };
+}
+export type ConfirmationTxState = "prepared" | "submitted" | "observed" | "abandoned";
+/** What the direct-mode call commits to, so a receipt can be bound to it later. */
+export interface ConfirmationTxExpected {
+    schema: Hex;
+    recipient: Address;
+    refUID: Hex;
+    /** keccak256 of the attestation data. */
+    dataHash: Hex;
+    /** For a revocation: the attestation being revoked. */
+    uid?: Hex | undefined;
+}
+/**
+ * A direct-mode confirmation the wallet's own tool submits. `submitted` means
+ * a hash was recorded and nothing has been verified yet; `observed` means the
+ * receipt, the EAS event, the attestation, and the gateway's final read
+ * all agree.
+ */
+export interface ConfirmationTxRecord {
+    action: "attest" | "revoke";
+    callHash: Hex;
+    expected: ConfirmationTxExpected;
+    txHash?: Hex | undefined;
+    state: ConfirmationTxState;
+    /** The attestation the observed receipt created or revoked. */
+    uid?: Hex | undefined;
+    preparedAt: string;
+}
 export interface OrderRecord {
     /** The gateway's order handle, once known. */
     handle?: string | undefined;
@@ -24,15 +62,9 @@ export interface OrderRecord {
     /** The recomputed authorization nonce; identifies the order on-chain. */
     authorizationNonce?: string | undefined;
     readCapability?: ReadCapability | undefined;
-    /** A review submission retained for retries while sponsorship is pending. */
-    confirmationSubmission?: {
-        action: "confirmation" | "revoke-confirmation";
-        request: {
-            phase: "submit";
-            preparationId: string;
-            signature: string;
-        };
-    } | undefined;
+    confirmationSubmission?: ConfirmationSubmissionRecord | undefined;
+    /** The direct-mode confirmation in flight or last observed, if any. */
+    confirmationTx?: ConfirmationTxRecord | undefined;
     createdAt: string;
     updatedAt: string;
     /** The request body, kept so an interrupted purchase can be replayed byte-identically. */
@@ -45,6 +77,14 @@ export declare function findByIntent(intentId: string): OrderRecord | undefined;
 /** Inserts or updates by intent id. The intent id is the stable key. */
 export declare function upsertOrder(record: OrderRecord): OrderRecord;
 export declare function updateOrder(intentId: string, changes: Partial<Omit<OrderRecord, "intentId" | "createdAt">>): OrderRecord | undefined;
+/**
+ * Serializes one order's confirmation journal across processes. The
+ * read-check-write of a preparation spans gateway and chain calls; without
+ * the lock two preparations both find nothing pending and the later write
+ * drops the earlier validated call's tracking. The lock is reclaimed only
+ * when its owner is gone, never by age: the owner may be waiting on a person.
+ */
+export declare function withOrderLock<T>(intentId: string, run: () => Promise<T>): Promise<T>;
 /** True when the record consumed no session budget and its identifier may be signed for again. */
 export declare function isUnspent(record: OrderRecord): boolean;
 /** Total atomic USDC authorized for a profile: the §4.1.5 session running total. */

package/dist/store/orders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../src/store/orders.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,UAAU,GAClB,iBAAiB,GACjB,YAAY,GACZ,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,UAAU,GACV,wBAAwB;AAC1B,8EAA8E;GAC5E,aAAa,CAAC;AAElB,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,KAAK,EAAE,UAAU,CAAC;IAClB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC5C,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE;QACvB,MAAM,EAAE,cAAc,GAAG,qBAAqB,CAAC;QAC/C,OAAO,EAAE;YAAE,KAAK,EAAE,QAAQ,CAAC;YAAC,aAAa,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KACxE,GAAG,SAAS,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC/C;AA0BD,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAG1D;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAI3F;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEtE;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAa5D;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,WAAW,CAAC,CAAC,GAC5D,WAAW,GAAG,SAAS,CAYzB;AAKD,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEtD;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,UAAU,SAAiC,GAC1C,cAAc,GAAG,SAAS,CAM5B"}
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../src/store/orders.ts"],"names":[],"mappings":"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"}