deduplex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Audan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# deduplex
+
+Idempotency guard for AI agent tool calls — stop duplicate side effects from retries.
+
+```ts
+import { Guard, deriveKey, guard } from "deduplex";
+
+const g = new Guard();
+
+const chargeCustomer = guard<[string, number], string>(
+  (customerId, amount) => deriveKey([customerId, amount], "charge"),
+  g,
+)(async (customerId, amount) => {
+  return stripe.charges.create({ customer: customerId, amount });
+});
+```
+
+A second call with the same derived key returns the original result instead of re-executing; a genuine concurrent race raises `DuplicateInProgressError` by default (or waits, with `onRace: "wait"`); every attempt/block/completion is recorded in a hash-chained `AuditLog` verifiable via `g.auditLog.verify()`.
+
+- `deduplex/redis` — `RedisStore` for multi-process deployments (any `ioredis`-compatible client)
+- `deduplex/http` — `HttpStore` to run against the hosted API server
+- `deduplex/connectors/{stripe,twilio,sendgrid,webhook}` — pre-built idempotent wrappers for common side-effecting calls
+
+Full documentation, the Python SDK, the hosted API server, and the project roadmap live in the [main repository](https://github.com/zachaudan/double-check-harness).

package/dist/audit.d.ts

@@ -0,0 +1,61 @@
+export type AuditEventType = "attempt" | "completed" | "failed" | "blocked_duplicate" | "blocked_after_failure" | "blocked_race" | "wait_timeout";
+export interface AuditEntry {
+    readonly seq: number;
+    readonly key: string;
+    readonly event: AuditEventType;
+    readonly payload: Record<string, unknown>;
+    readonly timestamp: number;
+    readonly prevHash: string;
+    readonly hash: string;
+}
+export declare const GENESIS_HASH: string;
+export interface AuditSink {
+    append(entry: AuditEntry): void;
+    all(): AuditEntry[];
+}
+export declare class InMemoryAuditSink implements AuditSink {
+    private entries;
+    append(entry: AuditEntry): void;
+    all(): AuditEntry[];
+}
+/**
+ * Append-only, hash-chained log of every guarded action.
+ *
+ * This is the artifact a compliance/audit-tier customer actually pays for: a log they (or
+ * their regulator) can independently verify was not edited after the fact, not just a table
+ * of rows in a database that anyone with write access could quietly change. Each entry's hash
+ * covers its own payload AND the previous entry's hash, so altering or deleting any historical
+ * entry breaks the chain from that point forward.
+ */
+export declare class AuditLog {
+    private sink;
+    constructor(sink?: AuditSink);
+    record(key: string, event: AuditEventType, payload?: Record<string, unknown>): AuditEntry;
+    entries(): AuditEntry[];
+    /**
+     * Walk the chain and confirm every entry's hash and prevHash link up correctly.
+     *
+     * Returns [isValid, firstBrokenSeq]. A broken chain means either the log was tampered with,
+     * or entries were reordered/deleted — either way, an integrity failure a customer's auditor
+     * would want surfaced immediately, not silently ignored.
+     */
+    verify(): [boolean, number | null];
+    export(): AuditEntry[];
+    /**
+     * The artifact meant to actually leave the system for an auditor: the full entry list plus
+     * the chain-integrity verdict and a generation timestamp, computed fresh at export time
+     * rather than left for the recipient to (maybe) recompute themselves.
+     */
+    exportManifest(): {
+        generatedAt: number;
+        entryCount: number;
+        chainValid: boolean;
+        brokenAtSeq: number | null;
+        entries: AuditEntry[];
+    };
+    /**
+     * CSV export for auditors/spreadsheet tools that don't want raw JSON. The `payload` column
+     * is itself JSON-encoded since it's a nested object with a variable shape.
+     */
+    exportCsv(): string;
+}

package/dist/audit.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+export const GENESIS_HASH = "0".repeat(64);
+function canonical(obj) {
+    return JSON.stringify(obj);
+}
+function computeHash(entry) {
+    const body = canonical({
+        seq: entry.seq,
+        key: entry.key,
+        event: entry.event,
+        payload: entry.payload,
+        timestamp: entry.timestamp,
+        prevHash: entry.prevHash,
+    });
+    return createHash("sha256").update(body, "utf8").digest("hex");
+}
+export class InMemoryAuditSink {
+    entries = [];
+    append(entry) {
+        this.entries.push(entry);
+    }
+    all() {
+        return [...this.entries];
+    }
+}
+/**
+ * Append-only, hash-chained log of every guarded action.
+ *
+ * This is the artifact a compliance/audit-tier customer actually pays for: a log they (or
+ * their regulator) can independently verify was not edited after the fact, not just a table
+ * of rows in a database that anyone with write access could quietly change. Each entry's hash
+ * covers its own payload AND the previous entry's hash, so altering or deleting any historical
+ * entry breaks the chain from that point forward.
+ */
+export class AuditLog {
+    sink;
+    constructor(sink) {
+        this.sink = sink ?? new InMemoryAuditSink();
+    }
+    record(key, event, payload = {}) {
+        const existing = this.sink.all();
+        const seq = existing.length;
+        const prevHash = existing.length > 0 ? existing[existing.length - 1].hash : GENESIS_HASH;
+        const base = {
+            seq,
+            key,
+            event,
+            payload,
+            timestamp: Date.now() / 1000,
+            prevHash,
+        };
+        const entry = { ...base, hash: computeHash(base) };
+        this.sink.append(entry);
+        return entry;
+    }
+    entries() {
+        return this.sink.all();
+    }
+    /**
+     * Walk the chain and confirm every entry's hash and prevHash link up correctly.
+     *
+     * Returns [isValid, firstBrokenSeq]. A broken chain means either the log was tampered with,
+     * or entries were reordered/deleted — either way, an integrity failure a customer's auditor
+     * would want surfaced immediately, not silently ignored.
+     */
+    verify() {
+        const entries = this.entries();
+        let expectedPrev = GENESIS_HASH;
+        for (const entry of entries) {
+            const recomputed = computeHash({
+                seq: entry.seq,
+                key: entry.key,
+                event: entry.event,
+                payload: entry.payload,
+                timestamp: entry.timestamp,
+                prevHash: entry.prevHash,
+            });
+            if (entry.prevHash !== expectedPrev || entry.hash !== recomputed) {
+                return [false, entry.seq];
+            }
+            expectedPrev = entry.hash;
+        }
+        return [true, null];
+    }
+    export() {
+        return this.entries();
+    }
+    /**
+     * The artifact meant to actually leave the system for an auditor: the full entry list plus
+     * the chain-integrity verdict and a generation timestamp, computed fresh at export time
+     * rather than left for the recipient to (maybe) recompute themselves.
+     */
+    exportManifest() {
+        const [chainValid, brokenAtSeq] = this.verify();
+        const entries = this.export();
+        return {
+            generatedAt: Date.now() / 1000,
+            entryCount: entries.length,
+            chainValid,
+            brokenAtSeq,
+            entries,
+        };
+    }
+    /**
+     * CSV export for auditors/spreadsheet tools that don't want raw JSON. The `payload` column
+     * is itself JSON-encoded since it's a nested object with a variable shape.
+     */
+    exportCsv() {
+        const escape = (value) => `"${value.replace(/"/g, '""')}"`;
+        const rows = [["seq", "key", "event", "payload", "timestamp", "prevHash", "hash"]];
+        for (const e of this.export()) {
+            rows.push([
+                String(e.seq),
+                e.key,
+                e.event,
+                JSON.stringify(e.payload),
+                String(e.timestamp),
+                e.prevHash,
+                e.hash,
+            ]);
+        }
+        return rows.map((row) => row.map(escape).join(",")).join("\n") + "\n";
+    }
+}

package/dist/connectors/sendgrid.d.ts

@@ -0,0 +1,21 @@
+import { Guard } from "../core.js";
+interface SendGridClient {
+    send(mail: Record<string, unknown>): Promise<unknown> | unknown;
+}
+export interface SendEmailOptions {
+    to: string;
+    from: string;
+    subject: string;
+    content: string;
+    namespace?: string;
+    [extra: string]: unknown;
+}
+/**
+ * Send an email exactly once for the given (to, from, subject, content, extras).
+ *
+ * SendGrid's `@sendgrid/mail` client has no native idempotency key, so the Guard is the only
+ * line of defense. `sendgridClient` is anything exposing `.send(mail)` — the default export
+ * of `@sendgrid/mail` after `setApiKey(...)` satisfies this directly.
+ */
+export declare function sendEmail(guard: Guard, sendgridClient: SendGridClient, options: SendEmailOptions): Promise<unknown>;
+export {};

package/dist/connectors/sendgrid.js

@@ -0,0 +1,13 @@
+import { deriveKey } from "../keys.js";
+/**
+ * Send an email exactly once for the given (to, from, subject, content, extras).
+ *
+ * SendGrid's `@sendgrid/mail` client has no native idempotency key, so the Guard is the only
+ * line of defense. `sendgridClient` is anything exposing `.send(mail)` — the default export
+ * of `@sendgrid/mail` after `setApiKey(...)` satisfies this directly.
+ */
+export async function sendEmail(guard, sendgridClient, options) {
+    const { to, from, subject, content, namespace = "sendgrid.email", ...extra } = options;
+    const key = deriveKey([to, from, subject, content, extra], namespace);
+    return guard.execute(key, () => sendgridClient.send({ to, from, subject, text: content, ...extra }));
+}

package/dist/connectors/stripe.d.ts

@@ -0,0 +1,30 @@
+import { Guard } from "../core.js";
+interface StripeChargeClient {
+    Charge: {
+        create(params: Record<string, unknown>): Promise<unknown> | unknown;
+    };
+}
+interface StripePaymentIntentClient {
+    PaymentIntent: {
+        create(params: Record<string, unknown>): Promise<unknown> | unknown;
+    };
+}
+export interface ChargeOptions {
+    customer: string;
+    amount: number;
+    currency?: string;
+    namespace?: string;
+    [extra: string]: unknown;
+}
+/**
+ * Create a Stripe charge exactly once for the given (customer, amount, currency, extras).
+ *
+ * `stripeClient` is the `stripe` package instance (or anything exposing
+ * `.Charge.create(...)`), so this connector never imports `stripe` itself. The derived key
+ * is also passed through as Stripe's own `idempotency_key`, so a retry that races past the
+ * local Guard is still deduplicated by Stripe itself.
+ */
+export declare function charge(guard: Guard, stripeClient: StripeChargeClient, options: ChargeOptions): Promise<unknown>;
+/** Same guarantee as `charge`, for the newer PaymentIntents API. */
+export declare function createPaymentIntent(guard: Guard, stripeClient: StripePaymentIntentClient, options: ChargeOptions): Promise<unknown>;
+export {};

package/dist/connectors/stripe.js

@@ -0,0 +1,20 @@
+import { deriveKey } from "../keys.js";
+/**
+ * Create a Stripe charge exactly once for the given (customer, amount, currency, extras).
+ *
+ * `stripeClient` is the `stripe` package instance (or anything exposing
+ * `.Charge.create(...)`), so this connector never imports `stripe` itself. The derived key
+ * is also passed through as Stripe's own `idempotency_key`, so a retry that races past the
+ * local Guard is still deduplicated by Stripe itself.
+ */
+export async function charge(guard, stripeClient, options) {
+    const { customer, amount, currency = "usd", namespace = "stripe.charge", ...extra } = options;
+    const key = deriveKey([customer, amount, currency, extra], namespace);
+    return guard.execute(key, () => stripeClient.Charge.create({ customer, amount, currency, idempotency_key: key, ...extra }));
+}
+/** Same guarantee as `charge`, for the newer PaymentIntents API. */
+export async function createPaymentIntent(guard, stripeClient, options) {
+    const { customer, amount, currency = "usd", namespace = "stripe.payment_intent", ...extra } = options;
+    const key = deriveKey([customer, amount, currency, extra], namespace);
+    return guard.execute(key, () => stripeClient.PaymentIntent.create({ customer, amount, currency, idempotency_key: key, ...extra }));
+}

package/dist/connectors/twilio.d.ts

@@ -0,0 +1,21 @@
+import { Guard } from "../core.js";
+interface TwilioClient {
+    messages: {
+        create(params: Record<string, unknown>): Promise<unknown> | unknown;
+    };
+}
+export interface SendSmsOptions {
+    to: string;
+    from: string;
+    body: string;
+    namespace?: string;
+    [extra: string]: unknown;
+}
+/**
+ * Send an SMS exactly once for the given (to, from, body, extras).
+ *
+ * Twilio's Messages API has no native idempotency key, so the Guard is the only line of
+ * defense here. `twilioClient` is anything exposing `.messages.create(...)`.
+ */
+export declare function sendSms(guard: Guard, twilioClient: TwilioClient, options: SendSmsOptions): Promise<unknown>;
+export {};

package/dist/connectors/twilio.js

@@ -0,0 +1,12 @@
+import { deriveKey } from "../keys.js";
+/**
+ * Send an SMS exactly once for the given (to, from, body, extras).
+ *
+ * Twilio's Messages API has no native idempotency key, so the Guard is the only line of
+ * defense here. `twilioClient` is anything exposing `.messages.create(...)`.
+ */
+export async function sendSms(guard, twilioClient, options) {
+    const { to, from, body, namespace = "twilio.sms", ...extra } = options;
+    const key = deriveKey([to, from, body, extra], namespace);
+    return guard.execute(key, () => twilioClient.messages.create({ to, from, body, ...extra }));
+}

package/dist/connectors/webhook.d.ts

@@ -0,0 +1,24 @@
+import { Guard } from "../core.js";
+interface HttpClient {
+    post(url: string, options: {
+        json: Record<string, unknown>;
+        headers: Record<string, string>;
+    }): Promise<unknown> | unknown;
+}
+export interface WebhookPostOptions {
+    namespace?: string;
+    headers?: Record<string, string>;
+    idempotencyHeader?: string | null;
+    [extra: string]: unknown;
+}
+/**
+ * POST a JSON payload to any webhook/REST endpoint exactly once for the given
+ * (url, payload, extras).
+ *
+ * `httpClient` is anything exposing `.post(url, { json, headers })`. Since most REST APIs
+ * that care about idempotency read it from a request header rather than a body field, the
+ * derived key is also sent as `idempotencyHeader` (default `Idempotency-Key`, the de facto
+ * convention Stripe/GitHub/etc. use) unless the caller passes `idempotencyHeader: null`.
+ */
+export declare function post(guard: Guard, httpClient: HttpClient, url: string, payload: Record<string, unknown>, options?: WebhookPostOptions): Promise<unknown>;
+export {};

package/dist/connectors/webhook.js

@@ -0,0 +1,19 @@
+import { deriveKey } from "../keys.js";
+/**
+ * POST a JSON payload to any webhook/REST endpoint exactly once for the given
+ * (url, payload, extras).
+ *
+ * `httpClient` is anything exposing `.post(url, { json, headers })`. Since most REST APIs
+ * that care about idempotency read it from a request header rather than a body field, the
+ * derived key is also sent as `idempotencyHeader` (default `Idempotency-Key`, the de facto
+ * convention Stripe/GitHub/etc. use) unless the caller passes `idempotencyHeader: null`.
+ */
+export async function post(guard, httpClient, url, payload, options = {}) {
+    const { namespace = "webhook.post", headers = {}, idempotencyHeader = "Idempotency-Key", ...extra } = options;
+    const key = deriveKey([url, payload, extra], namespace);
+    const mergedHeaders = { ...headers };
+    if (idempotencyHeader) {
+        mergedHeaders[idempotencyHeader] = key;
+    }
+    return guard.execute(key, () => httpClient.post(url, { json: payload, headers: mergedHeaders, ...extra }));
+}

package/dist/core.d.ts

@@ -0,0 +1,45 @@
+import { AuditLog } from "./audit.js";
+import type { Store } from "./store/base.js";
+export type OnRace = "raise" | "wait";
+export interface GuardOptions {
+    store?: Store;
+    auditLog?: AuditLog;
+    defaultTtlSeconds?: number;
+    onRace?: OnRace;
+    waitPollIntervalMs?: number;
+    waitTimeoutMs?: number;
+}
+/**
+ * The core idempotency guard: wraps a side-effecting async function so that two calls with
+ * the same key produce the effect exactly once.
+ *
+ * A Guard is stateless configuration over a Store + AuditLog — construct one per application
+ * (or per tool-type namespace) and reuse it across calls; the Store is what actually holds
+ * per-key state.
+ */
+export declare class Guard {
+    readonly store: Store;
+    readonly auditLog: AuditLog;
+    private readonly defaultTtlSeconds;
+    private readonly onRace;
+    private readonly waitPollIntervalMs;
+    private readonly waitTimeoutMs;
+    constructor(options?: GuardOptions);
+    /**
+     * Run `fn` exactly once for `key`, no matter how many times `execute` is called with that
+     * key. `fn` takes no arguments — bind any needed arguments via closure before calling
+     * execute, since the key itself is the caller's declaration of "these are the arguments
+     * that make two calls the same action."
+     */
+    execute<T>(key: string, fn: () => Promise<T> | T, ttlSeconds?: number): Promise<T>;
+    private handleRace;
+}
+/**
+ * Wraps an existing async function with idempotency-guarded execution.
+ *
+ * `keyFn` receives the same arguments as the wrapped function and returns the idempotency key
+ * string — this keeps key derivation explicit and visible at the call site instead of hidden
+ * magic, since getting the key wrong (too broad or too narrow) is the single most
+ * consequential mistake a user of this library can make.
+ */
+export declare function guard<Args extends unknown[], T>(keyFn: (...args: Args) => string, guardInstance?: Guard): (fn: (...args: Args) => Promise<T> | T) => (...args: Args) => Promise<T>;

package/dist/core.js

@@ -0,0 +1,112 @@
+import { AuditLog } from "./audit.js";
+import { DuplicateInProgressError, StoreError } from "./errors.js";
+import { MemoryStore } from "./store/memoryStore.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * The core idempotency guard: wraps a side-effecting async function so that two calls with
+ * the same key produce the effect exactly once.
+ *
+ * A Guard is stateless configuration over a Store + AuditLog — construct one per application
+ * (or per tool-type namespace) and reuse it across calls; the Store is what actually holds
+ * per-key state.
+ */
+export class Guard {
+    store;
+    auditLog;
+    defaultTtlSeconds;
+    onRace;
+    waitPollIntervalMs;
+    waitTimeoutMs;
+    constructor(options = {}) {
+        this.store = options.store ?? new MemoryStore();
+        this.auditLog = options.auditLog ?? new AuditLog();
+        this.defaultTtlSeconds = options.defaultTtlSeconds ?? 86400;
+        this.onRace = options.onRace ?? "raise";
+        this.waitPollIntervalMs = options.waitPollIntervalMs ?? 50;
+        this.waitTimeoutMs = options.waitTimeoutMs ?? 5000;
+    }
+    /**
+     * Run `fn` exactly once for `key`, no matter how many times `execute` is called with that
+     * key. `fn` takes no arguments — bind any needed arguments via closure before calling
+     * execute, since the key itself is the caller's declaration of "these are the arguments
+     * that make two calls the same action."
+     */
+    async execute(key, fn, ttlSeconds) {
+        const ttl = ttlSeconds ?? this.defaultTtlSeconds;
+        const existing = await this.store.acquire(key, ttl);
+        if (existing === null) {
+            // We won the race — we are the one execution of this action.
+            this.auditLog.record(key, "attempt");
+            try {
+                const result = await fn();
+                await this.store.markDone(key, result);
+                this.auditLog.record(key, "completed");
+                return result;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                await this.store.markFailed(key, message);
+                this.auditLog.record(key, "failed", { error: message });
+                throw err;
+            }
+        }
+        if (existing.status === "done") {
+            this.auditLog.record(key, "blocked_duplicate", { reusedResult: true });
+            return existing.result;
+        }
+        if (existing.status === "failed") {
+            // A prior attempt failed terminally. Do not silently resurrect it as success; surface
+            // the original failure so the caller can decide whether to actually retry under a
+            // fresh key (a deliberate choice) rather than an accidental duplicate.
+            this.auditLog.record(key, "blocked_after_failure", { error: existing.error ?? null });
+            throw new StoreError(`Action "${key}" previously failed: ${existing.error}. ` +
+                "Retry with a new key if this is an intentional new attempt.");
+        }
+        // Status is "in_progress": a genuine concurrent race, not a retry-after-completion.
+        return this.handleRace(key);
+    }
+    async handleRace(key) {
+        if (this.onRace === "raise") {
+            this.auditLog.record(key, "blocked_race");
+            throw new DuplicateInProgressError(key);
+        }
+        // onRace === "wait": poll until the in-flight caller finishes, or time out.
+        const deadline = Date.now() + this.waitTimeoutMs;
+        while (Date.now() < deadline) {
+            await sleep(this.waitPollIntervalMs);
+            const record = await this.store.get(key);
+            if (record === null) {
+                // Released without completing — nothing to reuse; caller must decide next step.
+                throw new DuplicateInProgressError(key);
+            }
+            if (record.status === "done") {
+                this.auditLog.record(key, "blocked_duplicate", { reusedResult: true, waited: true });
+                return record.result;
+            }
+            if (record.status === "failed") {
+                throw new StoreError(`Action "${key}" previously failed: ${record.error}`);
+            }
+        }
+        this.auditLog.record(key, "wait_timeout");
+        throw new DuplicateInProgressError(key);
+    }
+}
+/**
+ * Wraps an existing async function with idempotency-guarded execution.
+ *
+ * `keyFn` receives the same arguments as the wrapped function and returns the idempotency key
+ * string — this keeps key derivation explicit and visible at the call site instead of hidden
+ * magic, since getting the key wrong (too broad or too narrow) is the single most
+ * consequential mistake a user of this library can make.
+ */
+export function guard(keyFn, guardInstance) {
+    const g = guardInstance ?? new Guard();
+    return (fn) => {
+        return (...args) => {
+            const key = keyFn(...args);
+            return g.execute(key, () => fn(...args));
+        };
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export declare class DoubleCheckError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a second caller races in on a key whose first call hasn't finished yet.
+ *
+ * This is a concurrency race, not a normal retry-after-completion. The caller must decide
+ * whether to back off and poll, or surface the error — the harness will not guess for them,
+ * since guessing wrong here is exactly the class of bug this library exists to prevent.
+ */
+export declare class DuplicateInProgressError extends DoubleCheckError {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Thrown when the backing store fails in a way that makes the idempotency guarantee unsafe,
+ * or when a key's prior attempt failed terminally and must not be silently replayed as success.
+ */
+export declare class StoreError extends DoubleCheckError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,31 @@
+export class DoubleCheckError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DoubleCheckError";
+    }
+}
+/**
+ * Thrown when a second caller races in on a key whose first call hasn't finished yet.
+ *
+ * This is a concurrency race, not a normal retry-after-completion. The caller must decide
+ * whether to back off and poll, or surface the error — the harness will not guess for them,
+ * since guessing wrong here is exactly the class of bug this library exists to prevent.
+ */
+export class DuplicateInProgressError extends DoubleCheckError {
+    key;
+    constructor(key) {
+        super(`Action with key "${key}" is already in progress`);
+        this.name = "DuplicateInProgressError";
+        this.key = key;
+    }
+}
+/**
+ * Thrown when the backing store fails in a way that makes the idempotency guarantee unsafe,
+ * or when a key's prior attempt failed terminally and must not be silently replayed as success.
+ */
+export class StoreError extends DoubleCheckError {
+    constructor(message) {
+        super(message);
+        this.name = "StoreError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Guard, guard } from "./core.js";
+export type { GuardOptions, OnRace } from "./core.js";
+export { deriveKey } from "./keys.js";
+export { DoubleCheckError, DuplicateInProgressError, StoreError } from "./errors.js";
+export { AuditLog, InMemoryAuditSink, GENESIS_HASH } from "./audit.js";
+export type { AuditEntry, AuditEventType, AuditSink } from "./audit.js";
+export { MemoryStore } from "./store/memoryStore.js";
+export type { Record_, Status, Store } from "./store/base.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Guard, guard } from "./core.js";
+export { deriveKey } from "./keys.js";
+export { DoubleCheckError, DuplicateInProgressError, StoreError } from "./errors.js";
+export { AuditLog, InMemoryAuditSink, GENESIS_HASH } from "./audit.js";
+export { MemoryStore } from "./store/memoryStore.js";

package/dist/keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Derive a stable idempotency key from a set of values.
+ *
+ * A namespace should be supplied per tool/action type (e.g. "stripe.charge") to avoid
+ * accidental key collisions between unrelated tools that happen to share argument values.
+ */
+export declare function deriveKey(parts: unknown[], namespace?: string): string;

package/dist/keys.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+/**
+ * Canonicalize a value for stable hashing: object keys are sorted recursively so that
+ * argument ordering (e.g. differing key order in an options object at different call sites)
+ * never produces a different key for what is semantically the same action.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        const sortedKeys = Object.keys(value).sort();
+        const result = {};
+        for (const k of sortedKeys) {
+            result[k] = canonicalize(value[k]);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Derive a stable idempotency key from a set of values.
+ *
+ * A namespace should be supplied per tool/action type (e.g. "stripe.charge") to avoid
+ * accidental key collisions between unrelated tools that happen to share argument values.
+ */
+export function deriveKey(parts, namespace) {
+    const canonical = JSON.stringify(canonicalize({ namespace: namespace ?? null, parts }));
+    const digest = createHash("sha256").update(canonical, "utf8").digest("hex");
+    return namespace ? `${namespace}:${digest}` : digest;
+}

package/dist/store/base.d.ts

@@ -0,0 +1,40 @@
+export type Status = "in_progress" | "done" | "failed";
+export interface Record_ {
+    key: string;
+    status: Status;
+    result?: unknown;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Backing store for idempotency state.
+ *
+ * The contract every implementation must uphold: `acquire` must be atomic. Two concurrent
+ * callers racing on the same key must never both receive "you have the lock" — exactly one
+ * does, and the other gets back the existing (in-progress or done) record instead. This is
+ * the property that makes the guarantee real under concurrency, not just under sequential
+ * retries, which is the case a naive "check then write" implementation gets wrong.
+ */
+export interface Store {
+    /**
+     * Attempt to claim `key` for execution.
+     *
+     * Returns `null` if the caller acquired the lock (i.e. is the first/only caller and should
+     * proceed to execute). Returns the existing Record if someone else already holds or has
+     * completed this key (i.e. the caller must NOT execute again).
+     */
+    acquire(key: string, ttlSeconds: number): Promise<Record_ | null>;
+    /** Record a successful outcome for `key`, unblocking future duplicate callers with the
+     * cached result instead of re-executing. */
+    markDone(key: string, result: unknown): Promise<void>;
+    /** Record a failed outcome. Whether a failed action should be retried under a new key is a
+     * policy decision left to the caller/Guard, not the store. */
+    markFailed(key: string, error: string): Promise<void>;
+    /** Fetch the current record for `key`, if any, without acquiring it. */
+    get(key: string): Promise<Record_ | null>;
+    /** Release a claimed-but-never-completed key (e.g. after an unrecoverable crash during
+     * execution), so a future retry is not permanently blocked on a record that will never
+     * resolve. Should be used deliberately, not on every failure. */
+    release(key: string): Promise<void>;
+}

package/dist/store/base.js

@@ -0,0 +1 @@
+export {};

package/dist/store/httpStore.d.ts

@@ -0,0 +1,30 @@
+import type { Record_, Store } from "./base.js";
+export interface HttpStoreOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Store implementation that delegates to the Deduplex hosted API instead of a
+ * local Redis/memory store. This is the piece that turns the SDK from "self-hosted library"
+ * into "hosted product": point `Guard` at an `HttpStore` and every idempotency decision,
+ * along with the tamper-evident audit trail, is made and persisted server-side, viewable in
+ * the dashboard, with no infrastructure for the caller to run.
+ *
+ * The server owns the actual atomicity guarantee (via its own SQL-level `INSERT ... ON
+ * CONFLICT`); this class is a thin, honest HTTP client over that contract — it does not
+ * attempt to add its own client-side locking, since a network client cannot make a remote
+ * operation atomic that the server itself doesn't guarantee.
+ */
+export declare class HttpStore implements Store {
+    private baseUrl;
+    private apiKey;
+    private fetchImpl;
+    constructor(options: HttpStoreOptions);
+    private request;
+    acquire(key: string, ttlSeconds: number): Promise<Record_ | null>;
+    markDone(key: string, result: unknown): Promise<void>;
+    markFailed(key: string, error: string): Promise<void>;
+    get(key: string): Promise<Record_ | null>;
+    release(key: string): Promise<void>;
+}

package/dist/store/httpStore.js

@@ -0,0 +1,56 @@
+/**
+ * Store implementation that delegates to the Deduplex hosted API instead of a
+ * local Redis/memory store. This is the piece that turns the SDK from "self-hosted library"
+ * into "hosted product": point `Guard` at an `HttpStore` and every idempotency decision,
+ * along with the tamper-evident audit trail, is made and persisted server-side, viewable in
+ * the dashboard, with no infrastructure for the caller to run.
+ *
+ * The server owns the actual atomicity guarantee (via its own SQL-level `INSERT ... ON
+ * CONFLICT`); this class is a thin, honest HTTP client over that contract — it does not
+ * attempt to add its own client-side locking, since a network client cannot make a remote
+ * operation atomic that the server itself doesn't guarantee.
+ */
+export class HttpStore {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 401) {
+            throw new Error("Deduplex: invalid or missing API key");
+        }
+        const json = (await res.json().catch(() => ({})));
+        return { status: res.status, json };
+    }
+    async acquire(key, ttlSeconds) {
+        const { json } = await this.request("POST", `/v1/keys/${encodeURIComponent(key)}/acquire`, { ttlSeconds });
+        return json.acquired ? null : json.record;
+    }
+    async markDone(key, result) {
+        await this.request("POST", `/v1/keys/${encodeURIComponent(key)}/done`, { result });
+    }
+    async markFailed(key, error) {
+        await this.request("POST", `/v1/keys/${encodeURIComponent(key)}/failed`, { error });
+    }
+    async get(key) {
+        const { status, json } = await this.request("GET", `/v1/keys/${encodeURIComponent(key)}`);
+        if (status === 404)
+            return null;
+        return json.record ?? null;
+    }
+    async release(key) {
+        await this.request("DELETE", `/v1/keys/${encodeURIComponent(key)}`);
+    }
+}

package/dist/store/memoryStore.d.ts

@@ -0,0 +1,20 @@
+import type { Record_, Store } from "./base.js";
+/**
+ * Single-process, in-memory store. Good for local dev, tests, and single-instance
+ * deployments — not for anything running across multiple processes/machines, since state
+ * lives only in this process's memory. Use RedisStore for real distributed deployments.
+ *
+ * Node is single-threaded, but `acquire` is still written to be safe under interleaved async
+ * execution: the check-and-set happens synchronously within one microtask, so no `await`
+ * splits the read from the write and lets a second concurrent call slip through.
+ */
+export declare class MemoryStore implements Store {
+    private records;
+    private ttls;
+    private expireIfNeeded;
+    acquire(key: string, ttlSeconds: number): Promise<Record_ | null>;
+    markDone(key: string, result: unknown): Promise<void>;
+    markFailed(key: string, error: string): Promise<void>;
+    get(key: string): Promise<Record_ | null>;
+    release(key: string): Promise<void>;
+}

package/dist/store/memoryStore.js

@@ -0,0 +1,56 @@
+/**
+ * Single-process, in-memory store. Good for local dev, tests, and single-instance
+ * deployments — not for anything running across multiple processes/machines, since state
+ * lives only in this process's memory. Use RedisStore for real distributed deployments.
+ *
+ * Node is single-threaded, but `acquire` is still written to be safe under interleaved async
+ * execution: the check-and-set happens synchronously within one microtask, so no `await`
+ * splits the read from the write and lets a second concurrent call slip through.
+ */
+export class MemoryStore {
+    records = new Map();
+    ttls = new Map();
+    expireIfNeeded(key) {
+        const expiry = this.ttls.get(key);
+        if (expiry !== undefined && Date.now() >= expiry) {
+            this.records.delete(key);
+            this.ttls.delete(key);
+        }
+    }
+    async acquire(key, ttlSeconds) {
+        this.expireIfNeeded(key);
+        const existing = this.records.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const now = Date.now() / 1000;
+        const record = { key, status: "in_progress", createdAt: now, updatedAt: now };
+        this.records.set(key, record);
+        this.ttls.set(key, Date.now() + ttlSeconds * 1000);
+        return null;
+    }
+    async markDone(key, result) {
+        const record = this.records.get(key);
+        if (!record)
+            return;
+        record.status = "done";
+        record.result = result;
+        record.updatedAt = Date.now() / 1000;
+    }
+    async markFailed(key, error) {
+        const record = this.records.get(key);
+        if (!record)
+            return;
+        record.status = "failed";
+        record.error = error;
+        record.updatedAt = Date.now() / 1000;
+    }
+    async get(key) {
+        this.expireIfNeeded(key);
+        return this.records.get(key) ?? null;
+    }
+    async release(key) {
+        this.records.delete(key);
+        this.ttls.delete(key);
+    }
+}

package/dist/store/redisStore.d.ts

@@ -0,0 +1,36 @@
+import type { Record_, Store } from "./base.js";
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: "PX", ttlMs: number): Promise<string | null>;
+    del(key: string): Promise<number>;
+    pttl(key: string): Promise<number>;
+    defineCommand(name: string, definition: {
+        numberOfKeys: number;
+        lua: string;
+    }): void;
+    [command: string]: unknown;
+}
+/**
+ * Distributed store backed by Redis. Safe across multiple processes/machines, which is the
+ * deployment shape any real hosted or multi-instance self-hosted setup needs — this is the
+ * store that makes the concurrency guarantee (Store.acquire's contract) hold true when two
+ * different servers race on the same idempotency key at the same time.
+ *
+ * Accepts any client satisfying `RedisLike` (a real `ioredis.Redis`, or a compatible mock in
+ * tests) rather than depending on the `ioredis` package directly.
+ */
+export declare class RedisStore implements Store {
+    private client;
+    private prefix;
+    private scriptsRegistered;
+    constructor(client: RedisLike, keyPrefix?: string);
+    private ensureScripts;
+    private rkey;
+    private toRecord;
+    acquire(key: string, ttlSeconds: number): Promise<Record_ | null>;
+    private update;
+    markDone(key: string, result: unknown): Promise<void>;
+    markFailed(key: string, error: string): Promise<void>;
+    get(key: string): Promise<Record_ | null>;
+    release(key: string): Promise<void>;
+}

package/dist/store/redisStore.js

@@ -0,0 +1,106 @@
+// Atomically claim a key only if it doesn't already exist. This is the operation that makes
+// concurrent races safe: two processes calling this script on the same key at the same instant
+// will not both get "created" back — Redis serializes script execution, so exactly one caller
+// wins and the other sees the record the winner just wrote.
+const ACQUIRE_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+if existing then
+  return existing
+end
+redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2])
+return false
+`;
+const UPDATE_SCRIPT = `
+local existing = redis.call('GET', KEYS[1])
+if not existing then
+  return 0
+end
+local ttl = redis.call('PTTL', KEYS[1])
+if ttl < 0 then ttl = ARGV[2] end
+redis.call('SET', KEYS[1], ARGV[1], 'PX', ttl)
+return 1
+`;
+/**
+ * Distributed store backed by Redis. Safe across multiple processes/machines, which is the
+ * deployment shape any real hosted or multi-instance self-hosted setup needs — this is the
+ * store that makes the concurrency guarantee (Store.acquire's contract) hold true when two
+ * different servers race on the same idempotency key at the same time.
+ *
+ * Accepts any client satisfying `RedisLike` (a real `ioredis.Redis`, or a compatible mock in
+ * tests) rather than depending on the `ioredis` package directly.
+ */
+export class RedisStore {
+    client;
+    prefix;
+    scriptsRegistered = false;
+    constructor(client, keyPrefix = "dch:") {
+        this.client = client;
+        this.prefix = keyPrefix;
+    }
+    ensureScripts() {
+        if (this.scriptsRegistered)
+            return;
+        this.client.defineCommand("acquireScript", { numberOfKeys: 1, lua: ACQUIRE_SCRIPT });
+        this.client.defineCommand("updateScript", { numberOfKeys: 1, lua: UPDATE_SCRIPT });
+        this.scriptsRegistered = true;
+    }
+    rkey(key) {
+        return `${this.prefix}${key}`;
+    }
+    toRecord(key, raw) {
+        const data = JSON.parse(raw);
+        return {
+            key,
+            status: data.status,
+            result: data.result,
+            error: data.error ?? undefined,
+            createdAt: data.createdAt,
+            updatedAt: data.updatedAt,
+        };
+    }
+    async acquire(key, ttlSeconds) {
+        this.ensureScripts();
+        const now = Date.now() / 1000;
+        const payload = {
+            status: "in_progress",
+            result: null,
+            error: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const acquireScript = this.client["acquireScript"];
+        const existing = await acquireScript(this.rkey(key), JSON.stringify(payload), ttlSeconds * 1000);
+        if (!existing)
+            return null;
+        return this.toRecord(key, existing);
+    }
+    async update(key, status, extra) {
+        this.ensureScripts();
+        const existingRaw = await this.client.get(this.rkey(key));
+        const createdAt = existingRaw ? JSON.parse(existingRaw).createdAt : Date.now() / 1000;
+        const payload = {
+            status,
+            result: extra.result ?? null,
+            error: extra.error ?? null,
+            createdAt,
+            updatedAt: Date.now() / 1000,
+        };
+        const updateScript = this.client["updateScript"];
+        await updateScript(this.rkey(key), JSON.stringify(payload), 86400 * 1000);
+    }
+    async markDone(key, result) {
+        await this.update(key, "done", { result });
+    }
+    async markFailed(key, error) {
+        await this.update(key, "failed", { error });
+    }
+    async get(key) {
+        const raw = await this.client.get(this.rkey(key));
+        if (raw === null)
+            return null;
+        return this.toRecord(key, raw);
+    }
+    async release(key) {
+        await this.client.del(this.rkey(key));
+    }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "deduplex",
+  "version": "0.1.0",
+  "description": "Idempotency guard for AI agent tool calls — stop duplicate side effects from retries.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./redis": {
+      "types": "./dist/store/redisStore.d.ts",
+      "import": "./dist/store/redisStore.js"
+    },
+    "./http": {
+      "types": "./dist/store/httpStore.d.ts",
+      "import": "./dist/store/httpStore.js"
+    },
+    "./connectors/stripe": {
+      "types": "./dist/connectors/stripe.d.ts",
+      "import": "./dist/connectors/stripe.js"
+    },
+    "./connectors/twilio": {
+      "types": "./dist/connectors/twilio.d.ts",
+      "import": "./dist/connectors/twilio.js"
+    },
+    "./connectors/sendgrid": {
+      "types": "./dist/connectors/sendgrid.d.ts",
+      "import": "./dist/connectors/sendgrid.js"
+    },
+    "./connectors/webhook": {
+      "types": "./dist/connectors/webhook.d.ts",
+      "import": "./dist/connectors/webhook.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "idempotency",
+    "agents",
+    "llm",
+    "retries",
+    "reliability"
+  ],
+  "author": "Zach Audan",
+  "license": "MIT",
+  "homepage": "https://server-beta-seven-23.vercel.app",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "get-port": "^7.1.0",
+    "ioredis": "^5.4.1",
+    "ioredis-mock": "^8.9.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.5.4",
+    "vitest": "^5.0.0"
+  }
+}