@vllnt/convex-idempotency 0.1.0-canary.6abc175

package/dist/component/queries.js

@@ -0,0 +1,22 @@
+import { v } from "convex/values";
+import { query } from "./_generated/server";
+import { keyState } from "./validators";
+export const get = query({
+    args: { key: v.string(), scope: v.string() },
+    returns: v.union(v.null(), keyState),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("keys")
+            .withIndex("by_scope_key", (q) => q.eq("scope", args.scope).eq("key", args.key))
+            .unique();
+        if (row === null) {
+            return null;
+        }
+        return {
+            status: row.status,
+            result: row.result,
+            expiresAt: row.expiresAt,
+        };
+    },
+});
+//# sourceMappingURL=queries.js.map

package/dist/component/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/component/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC;IACvB,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;IAC5C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC;IACpC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,EAAE;aACrB,KAAK,CAAC,MAAM,CAAC;aACb,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAC/B,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAC9C;aACA,MAAM,EAAE,CAAC;QACZ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/component/schema.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sandboxed tables — the idempotency ledger's own concern. A `key` is unique
+ * within a `scope`; `result` carries the opaque host-owned outcome (never
+ * inspected). `expiresAt` is an absolute ms timestamp that bounds the grace
+ * window after which a key may be re-minted.
+ */
+declare const _default: import("convex/server").SchemaDefinition<{
+    keys: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        result?: any;
+        key: string;
+        scope: string;
+        status: "inflight" | "done";
+        expiresAt: number;
+    }, {
+        key: import("convex/values").VString<string, "required">;
+        scope: import("convex/values").VString<string, "required">;
+        status: import("convex/values").VUnion<"inflight" | "done", [import("convex/values").VLiteral<"inflight", "required">, import("convex/values").VLiteral<"done", "required">], "required", never>;
+        result: import("convex/values").VAny<any, "optional", string>;
+        expiresAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "key" | "scope" | "result" | "status" | "expiresAt" | `result.${string}`>, {
+        by_scope_key: ["scope", "key", "_creationTime"];
+        by_expires: ["expiresAt", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/component/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;;;;;;;;;;;;;;;;;;;AACH,wBAUG"}

package/dist/component/schema.js

@@ -0,0 +1,21 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { jsonValue } from "./validators";
+/**
+ * Sandboxed tables — the idempotency ledger's own concern. A `key` is unique
+ * within a `scope`; `result` carries the opaque host-owned outcome (never
+ * inspected). `expiresAt` is an absolute ms timestamp that bounds the grace
+ * window after which a key may be re-minted.
+ */
+export default defineSchema({
+    keys: defineTable({
+        key: v.string(),
+        scope: v.string(),
+        status: v.union(v.literal("inflight"), v.literal("done")),
+        result: v.optional(jsonValue),
+        expiresAt: v.number(),
+    })
+        .index("by_scope_key", ["scope", "key"])
+        .index("by_expires", ["expiresAt"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;GAKG;AACH,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;QAChB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;KACtB,CAAC;SACC,KAAK,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;SACvC,KAAK,CAAC,YAAY,EAAE,CAAC,WAAW,CAAC,CAAC;CACtC,CAAC,CAAC"}

package/dist/component/validators.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Opaque host-owned outcome stored against a completed key. The component never
+ * inspects it — last-resort arbitrary data, aliased here rather than left bare
+ * in function signatures. The host narrows it at the {@link Idempotency} client
+ * boundary via an optional `resultValidator`.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the
+ * lint rule `convex-rules/no-bare-v-any` is satisfied by routing every arbitrary
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export declare const jsonValue: import("convex/values").VAny<any, "required", string>;
+/**
+ * Result of {@link begin}. `fresh` — the key was just minted, the caller should
+ * do the work and then `complete`. `inflight` — another attempt holds the key;
+ * `expiresAt` is when the lease frees and `retryAfterMs` how long to back off
+ * before retrying. `done` — a prior attempt already completed; `result` carries
+ * the recorded outcome for a short-circuit replay.
+ */
+export declare const beginResult: import("convex/values").VUnion<{
+    state: "fresh";
+} | {
+    state: "inflight";
+    expiresAt: number;
+    retryAfterMs: number;
+} | {
+    result?: any;
+    state: "done";
+}, [import("convex/values").VObject<{
+    state: "fresh";
+}, {
+    state: import("convex/values").VLiteral<"fresh", "required">;
+}, "required", "state">, import("convex/values").VObject<{
+    state: "inflight";
+    expiresAt: number;
+    retryAfterMs: number;
+}, {
+    state: import("convex/values").VLiteral<"inflight", "required">;
+    expiresAt: import("convex/values").VFloat64<number, "required">;
+    retryAfterMs: import("convex/values").VFloat64<number, "required">;
+}, "required", "state" | "expiresAt" | "retryAfterMs">, import("convex/values").VObject<{
+    result?: any;
+    state: "done";
+}, {
+    state: import("convex/values").VLiteral<"done", "required">;
+    result: import("convex/values").VAny<any, "optional", string>;
+}, "required", "result" | "state" | `result.${string}`>], "required", "result" | "state" | "expiresAt" | "retryAfterMs" | `result.${string}`>;
+/**
+ * Result of {@link complete}. `recorded: true` — the outcome was written.
+ * `recorded: false` — the claim was lost; `reason` distinguishes a never-claimed
+ * key (`missing`), a lease that expired before completion (`expired`), and a key
+ * already marked done by a prior attempt (`already_done`). A host that sees
+ * `recorded: false` knows its work finished but the ledger row was gone.
+ */
+export declare const completeResult: import("convex/values").VUnion<{
+    recorded: true;
+} | {
+    recorded: false;
+    reason: "missing" | "expired" | "already_done";
+}, [import("convex/values").VObject<{
+    recorded: true;
+}, {
+    recorded: import("convex/values").VLiteral<true, "required">;
+}, "required", "recorded">, import("convex/values").VObject<{
+    recorded: false;
+    reason: "missing" | "expired" | "already_done";
+}, {
+    recorded: import("convex/values").VLiteral<false, "required">;
+    reason: import("convex/values").VUnion<"missing" | "expired" | "already_done", [import("convex/values").VLiteral<"missing", "required">, import("convex/values").VLiteral<"expired", "required">, import("convex/values").VLiteral<"already_done", "required">], "required", never>;
+}, "required", "recorded" | "reason">], "required", "recorded" | "reason">;
+/** Stored projection of a key returned by {@link get}. */
+export declare const keyState: import("convex/values").VObject<{
+    result?: any;
+    status: "inflight" | "done";
+    expiresAt: number;
+}, {
+    status: import("convex/values").VUnion<"inflight" | "done", [import("convex/values").VLiteral<"inflight", "required">, import("convex/values").VLiteral<"done", "required">], "required", never>;
+    result: import("convex/values").VAny<any, "optional", string>;
+    expiresAt: import("convex/values").VFloat64<number, "required">;
+}, "required", "result" | "status" | "expiresAt" | `result.${string}`>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/component/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,uDAAU,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;6IAQvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;0EAU1B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,QAAQ;;;;;;;;sEAInB,CAAC"}

package/dist/component/validators.js

@@ -0,0 +1,42 @@
+import { v } from "convex/values";
+/**
+ * Opaque host-owned outcome stored against a completed key. The component never
+ * inspects it — last-resort arbitrary data, aliased here rather than left bare
+ * in function signatures. The host narrows it at the {@link Idempotency} client
+ * boundary via an optional `resultValidator`.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the
+ * lint rule `convex-rules/no-bare-v-any` is satisfied by routing every arbitrary
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export const jsonValue = v.any();
+/**
+ * Result of {@link begin}. `fresh` — the key was just minted, the caller should
+ * do the work and then `complete`. `inflight` — another attempt holds the key;
+ * `expiresAt` is when the lease frees and `retryAfterMs` how long to back off
+ * before retrying. `done` — a prior attempt already completed; `result` carries
+ * the recorded outcome for a short-circuit replay.
+ */
+export const beginResult = v.union(v.object({ state: v.literal("fresh") }), v.object({
+    state: v.literal("inflight"),
+    expiresAt: v.number(),
+    retryAfterMs: v.number(),
+}), v.object({ state: v.literal("done"), result: v.optional(jsonValue) }));
+/**
+ * Result of {@link complete}. `recorded: true` — the outcome was written.
+ * `recorded: false` — the claim was lost; `reason` distinguishes a never-claimed
+ * key (`missing`), a lease that expired before completion (`expired`), and a key
+ * already marked done by a prior attempt (`already_done`). A host that sees
+ * `recorded: false` knows its work finished but the ledger row was gone.
+ */
+export const completeResult = v.union(v.object({ recorded: v.literal(true) }), v.object({
+    recorded: v.literal(false),
+    reason: v.union(v.literal("missing"), v.literal("expired"), v.literal("already_done")),
+}));
+/** Stored projection of a key returned by {@link get}. */
+export const keyState = v.object({
+    status: v.union(v.literal("inflight"), v.literal("done")),
+    result: v.optional(jsonValue),
+    expiresAt: v.number(),
+});
+//# sourceMappingURL=validators.js.map

package/dist/component/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAChC,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,EACvC,CAAC,CAAC,MAAM,CAAC;IACP,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;CACzB,CAAC,EACF,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CACtE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CACnC,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EACvC,CAAC,CAAC,MAAM,CAAC;IACP,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IAC1B,MAAM,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAC1B;CACF,CAAC,CACH,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,17 @@
+/** Shared constants used by both `client/` and `component/`. */
+export declare const COMPONENT_NAME = "idempotency";
+/** Default namespace when the host does not scope a key. */
+export declare const DEFAULT_SCOPE = "global";
+/**
+ * Default inflight lease: 60 seconds, in milliseconds. Short by design so a
+ * crashed worker's claim self-heals quickly and the key can be re-minted.
+ */
+export declare const DEFAULT_INFLIGHT_TTL_MS = 60000;
+/**
+ * Default done grace window: 24 hours, in milliseconds. How long a recorded
+ * outcome replays before the key may be re-minted.
+ */
+export declare const DEFAULT_DONE_TTL_MS = 86400000;
+/** Default page size for a `purge` pass before the sweep self-reschedules. */
+export declare const DEFAULT_PURGE_BATCH = 200;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,WAAa,CAAC;AAE9C,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/shared.js

@@ -0,0 +1,17 @@
+/** Shared constants used by both `client/` and `component/`. */
+export const COMPONENT_NAME = "idempotency";
+/** Default namespace when the host does not scope a key. */
+export const DEFAULT_SCOPE = "global";
+/**
+ * Default inflight lease: 60 seconds, in milliseconds. Short by design so a
+ * crashed worker's claim self-heals quickly and the key can be re-minted.
+ */
+export const DEFAULT_INFLIGHT_TTL_MS = 60_000;
+/**
+ * Default done grace window: 24 hours, in milliseconds. How long a recorded
+ * outcome replays before the key may be re-minted.
+ */
+export const DEFAULT_DONE_TTL_MS = 86_400_000;
+/** Default page size for a `purge` pass before the sweep self-reschedules. */
+export const DEFAULT_PURGE_BATCH = 200;
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC"}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@vllnt/convex-idempotency",
+  "version": "0.1.0-canary.6abc175",
+  "description": "Exactly-once idempotency key ledger for retried operations, as a Convex component",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "pnpm convex codegen --component-dir ./src/component && pnpm build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && pnpm build:codegen",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test:coverage && pnpm typecheck && pnpm generate:llms",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "convex": "^1.41.0"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.41.0",
+    "convex-test": "^0.0.53",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "homepage": "https://github.com/vllnt/convex-idempotency#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-idempotency/issues"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-idempotency"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "convex",
+    "convex-component",
+    "idempotency"
+  ]
+}

package/src/client/index.ts

@@ -0,0 +1,251 @@
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+} from "convex/server";
+import type {
+  BeginResult,
+  CompleteResult,
+  IdempotencyOptions,
+  KeyState,
+  ResultParser,
+} from "./types.js";
+import {
+  DEFAULT_DONE_TTL_MS,
+  DEFAULT_INFLIGHT_TTL_MS,
+  DEFAULT_PURGE_BATCH,
+  DEFAULT_SCOPE,
+} from "../shared.js";
+
+/**
+ * The component's raw `begin` return, before the client narrows `result`. The
+ * stored outcome is opaque here (`unknown`); the {@link Idempotency} client runs
+ * the host `resultValidator` over it at its typed boundary.
+ */
+type RawBegin =
+  | { state: "fresh" }
+  | { state: "inflight"; expiresAt: number; retryAfterMs: number }
+  | { state: "done"; result?: unknown };
+
+/**
+ * The idempotency component's function references, as exposed on the host via
+ * `components.idempotency`. The host's stored outcome type is opaque here
+ * (`unknown`); the {@link Idempotency} client narrows it to `TResult` at its
+ * own typed boundary.
+ */
+export interface IdempotencyComponent {
+  mutations: {
+    begin: FunctionReference<
+      "mutation",
+      "internal",
+      { key: string; scope: string; inflightTtlMs: number },
+      RawBegin
+    >;
+    complete: FunctionReference<
+      "mutation",
+      "internal",
+      {
+        key: string;
+        scope: string;
+        result?: unknown;
+        doneTtlMs: number;
+        upsertOnMissing: boolean;
+      },
+      CompleteResult
+    >;
+    purge: FunctionReference<
+      "mutation",
+      "internal",
+      { before?: number; batch: number },
+      number
+    >;
+  };
+  queries: {
+    get: FunctionReference<
+      "query",
+      "internal",
+      { key: string; scope: string },
+      {
+        status: "inflight" | "done";
+        result?: unknown;
+        expiresAt: number;
+      } | null
+    >;
+  };
+}
+
+interface RunQueryCtx {
+  runQuery<Q extends FunctionReference<"query", "internal">>(
+    reference: Q,
+    args: FunctionArgs<Q>,
+  ): Promise<FunctionReturnType<Q>>;
+}
+
+interface RunMutationCtx {
+  runMutation<M extends FunctionReference<"mutation", "internal">>(
+    reference: M,
+    args: FunctionArgs<M>,
+  ): Promise<FunctionReturnType<M>>;
+}
+
+/** Per-call overrides for `scope` and the inflight lease. */
+interface BeginOptions {
+  scope?: string;
+  inflightTtlMs?: number;
+}
+
+/** Per-call overrides for `scope`, the done grace window, and lost-claim upsert. */
+interface CompleteOptions {
+  scope?: string;
+  doneTtlMs?: number;
+  upsertOnMissing?: boolean;
+}
+
+/**
+ * Consumer-facing client for the exactly-once idempotency key ledger. The host
+ * owns meaning and auth; it passes an opaque `key` and an optional `scope`, and
+ * stores an arbitrary `TResult` outcome that replays return verbatim. Pass a
+ * `resultValidator` to narrow the opaque stored value to `TResult` at the
+ * boundary — there is no unchecked cast.
+ *
+ * @typeParam TResult - The host's stored outcome type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const idem = new Idempotency(components.idempotency, {
+ *   resultValidator: v.object({ chargeId: v.string() }).parse,
+ * });
+ * const r = await idem.begin(ctx, requestId);
+ * if (r.state === "done") return r.result;                  // typed replay
+ * if (r.state === "inflight") throw new Error(`retry in ${r.retryAfterMs}ms`);
+ * const out = await doWork();                               // r.state === "fresh"
+ * const done = await idem.complete(ctx, requestId, out);
+ * if (!done.recorded) log.warn("claim lost", done.reason);  // work ran, row gone
+ * ```
+ */
+export class Idempotency<TResult = unknown> {
+  private readonly defaultScope: string;
+  private readonly defaultInflightTtlMs: number;
+  private readonly defaultDoneTtlMs: number;
+  private readonly defaultUpsertOnMissing: boolean;
+  private readonly resultValidator: ResultParser<TResult> | undefined;
+
+  constructor(
+    private readonly component: IdempotencyComponent,
+    options: IdempotencyOptions<TResult> = {},
+  ) {
+    this.defaultScope = options.defaultScope ?? DEFAULT_SCOPE;
+    this.defaultInflightTtlMs =
+      options.defaultInflightTtlMs ?? DEFAULT_INFLIGHT_TTL_MS;
+    this.defaultDoneTtlMs = options.defaultDoneTtlMs ?? DEFAULT_DONE_TTL_MS;
+    this.defaultUpsertOnMissing = options.upsertOnMissing ?? false;
+    this.resultValidator = options.resultValidator;
+  }
+
+  private scopeOf(scope: string | undefined): string {
+    return scope ?? this.defaultScope;
+  }
+
+  /**
+   * Narrow an opaque stored `result` to `TResult` via the host validator. Absent
+   * values pass through untouched; with no validator the value is returned as-is
+   * (the host accepted the unchecked-type tradeoff by omitting one).
+   */
+  private parseResult(value: unknown): TResult | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    if (this.resultValidator === undefined) {
+      return value as TResult;
+    }
+    return this.resultValidator(value);
+  }
+
+  /**
+   * Claim `key`. `fresh` mints an inflight key (do the work, then `complete`);
+   * `inflight` means a concurrent attempt holds it — back off `retryAfterMs`;
+   * `done` returns the validated recorded `result` for a short-circuit replay.
+   */
+  async begin(
+    ctx: RunMutationCtx,
+    key: string,
+    opts: BeginOptions = {},
+  ): Promise<BeginResult<TResult>> {
+    const r: RawBegin = await ctx.runMutation(this.component.mutations.begin, {
+      key,
+      scope: this.scopeOf(opts.scope),
+      inflightTtlMs: opts.inflightTtlMs ?? this.defaultInflightTtlMs,
+    });
+    if (r.state === "done") {
+      return { state: "done", result: this.parseResult(r.result) };
+    }
+    return r;
+  }
+
+  /**
+   * Mark `key` `done`, recording `result` and extending the done grace window.
+   * Returns a discriminated outcome: `recorded: true` on success, or
+   * `recorded: false` with a `reason` when the claim was lost (missing, expired,
+   * or already done) so the host can react to dropped work. `result` is validated
+   * against the host validator before it is stored.
+   */
+  complete(
+    ctx: RunMutationCtx,
+    key: string,
+    result?: TResult,
+    opts: CompleteOptions = {},
+  ): Promise<CompleteResult> {
+    const validated =
+      result === undefined ? undefined : this.parseResult(result);
+    return ctx.runMutation(this.component.mutations.complete, {
+      key,
+      scope: this.scopeOf(opts.scope),
+      result: validated,
+      doneTtlMs: opts.doneTtlMs ?? this.defaultDoneTtlMs,
+      upsertOnMissing: opts.upsertOnMissing ?? this.defaultUpsertOnMissing,
+    });
+  }
+
+  /** The stored state for `key`, or `null` if no key is held in the scope. */
+  async get(
+    ctx: RunQueryCtx,
+    key: string,
+    scope?: string,
+  ): Promise<KeyState<TResult> | null> {
+    const row = await ctx.runQuery(this.component.queries.get, {
+      key,
+      scope: this.scopeOf(scope),
+    });
+    if (row === null) {
+      return null;
+    }
+    return {
+      status: row.status,
+      result: this.parseResult(row.result),
+      expiresAt: row.expiresAt,
+    };
+  }
+
+  /**
+   * Delete expired keys in bounded batches, oldest first. `before` defaults to
+   * the server clock; `batch` caps each pass and the sweep self-reschedules until
+   * the tail is clean. Returns the count removed in the first pass.
+   */
+  purge(
+    ctx: RunMutationCtx,
+    opts: { before?: number; batch?: number } = {},
+  ): Promise<number> {
+    return ctx.runMutation(this.component.mutations.purge, {
+      before: opts.before,
+      batch: opts.batch ?? DEFAULT_PURGE_BATCH,
+    });
+  }
+}
+
+export type {
+  BeginResult,
+  CompleteResult,
+  IdempotencyOptions,
+  KeyState,
+  ResultParser,
+};