replyonce 0.0.0-stage → 0.1.0

package/dist/redis.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stores/redis.ts"],"sourcesContent":["import type { ScopeState, Store, TransactResult } from '../types.js';\n\n/**\n * The one Redis command replyonce uses, in ioredis' signature. For node-redis, pass\n * `{ eval: (script, n, ...args) => client.eval(script, { keys: args.slice(0, n), arguments: args.slice(n) }) }`.\n */\nexport interface RedisLike {\n  eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;\n}\n\nexport interface RedisStoreOptions {\n  client: RedisLike;\n  /** Key prefix. Default `replyonce`. */\n  prefix?: string;\n  /** Expire idle scopes after this long. 0 disables expiry. Default 30 days. */\n  keyTtlMs?: number;\n  /** Optimistic retries under contention before giving up. Default 200. */\n  maxRetries?: number;\n}\n\nconst READ = `return redis.call('HMGET', KEYS[1], 's', 'v')`;\n\nconst CAS = `\nlocal v = tonumber(redis.call('HGET', KEYS[1], 'v') or '0')\nif v ~= tonumber(ARGV[1]) then return 0 end\nredis.call('HSET', KEYS[1], 's', ARGV[2], 'v', v + 1)\nlocal ttl = tonumber(ARGV[3])\nif ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end\nreturn 1\n`;\n\nexport class StoreContentionError extends Error {\n  constructor(scope: string, attempts: number) {\n    super(`replyonce: gave up on scope ${JSON.stringify(scope)} after ${attempts} contended attempts`);\n    this.name = 'StoreContentionError';\n  }\n}\n\n/**\n * Redis store. Each scope is one hash holding the state and a version. `transact` reads\n * both, decides locally, then writes with a compare-and-set Lua script, retrying on a lost\n * race. Works on a shared connection (no WATCH) and with Redis Cluster (one key per op).\n */\nexport class RedisStore implements Store {\n  private readonly client: RedisLike;\n  private readonly prefix: string;\n  private readonly keyTtlMs: number;\n  private readonly maxRetries: number;\n\n  constructor(options: RedisStoreOptions) {\n    if (!options?.client) throw new TypeError('replyonce: RedisStore needs a client');\n    this.client = options.client;\n    this.prefix = options.prefix ?? 'replyonce';\n    this.keyTtlMs = options.keyTtlMs ?? 30 * 24 * 3_600_000;\n    this.maxRetries = options.maxRetries ?? 200;\n  }\n\n  private redisKey(scope: string): string {\n    return `${this.prefix}:{${scope}}`;\n  }\n\n  private async load(scope: string): Promise<{ state: ScopeState | null; version: number }> {\n    const reply = (await this.client.eval(READ, 1, this.redisKey(scope))) as Array<string | null>;\n    const raw = reply?.[0] ?? null;\n    const version = reply?.[1] ? Number(reply[1]) : 0;\n    return { state: raw ? (JSON.parse(raw) as ScopeState) : null, version };\n  }\n\n  async read(scope: string): Promise<ScopeState | null> {\n    return (await this.load(scope)).state;\n  }\n\n  async transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T> {\n    const key = this.redisKey(scope);\n    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {\n      const { state, version } = await this.load(scope);\n      const { next, result } = fn(state);\n      // A read-only decision was taken against one consistent snapshot, so it stands.\n      if (!next) return result;\n      const ok = await this.client.eval(CAS, 1, key, version, JSON.stringify(next), this.keyTtlMs);\n      if (Number(ok) === 1) return result;\n      const cap = Math.min(50, 2 ** Math.min(attempt, 6));\n      await new Promise((r) => setTimeout(r, Math.random() * cap));\n    }\n    throw new StoreContentionError(scope, this.maxRetries + 1);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBA,IAAM,OAAO;AAEb,IAAM,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASL,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAAY,OAAe,UAAkB;AAC3C,UAAM,+BAA+B,KAAK,UAAU,KAAK,CAAC,UAAU,QAAQ,qBAAqB;AACjG,SAAK,OAAO;AAAA,EACd;AACF;AAOO,IAAM,aAAN,MAAkC;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,SAA4B;AACtC,QAAI,CAAC,SAAS,OAAQ,OAAM,IAAI,UAAU,sCAAsC;AAChF,SAAK,SAAS,QAAQ;AACtB,SAAK,SAAS,QAAQ,UAAU;AAChC,SAAK,WAAW,QAAQ,YAAY,KAAK,KAAK;AAC9C,SAAK,aAAa,QAAQ,cAAc;AAAA,EAC1C;AAAA,EAEQ,SAAS,OAAuB;AACtC,WAAO,GAAG,KAAK,MAAM,KAAK,KAAK;AAAA,EACjC;AAAA,EAEA,MAAc,KAAK,OAAuE;AACxF,UAAM,QAAS,MAAM,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK,SAAS,KAAK,CAAC;AACnE,UAAM,MAAM,QAAQ,CAAC,KAAK;AAC1B,UAAM,UAAU,QAAQ,CAAC,IAAI,OAAO,MAAM,CAAC,CAAC,IAAI;AAChD,WAAO,EAAE,OAAO,MAAO,KAAK,MAAM,GAAG,IAAmB,MAAM,QAAQ;AAAA,EACxE;AAAA,EAEA,MAAM,KAAK,OAA2C;AACpD,YAAQ,MAAM,KAAK,KAAK,KAAK,GAAG;AAAA,EAClC;AAAA,EAEA,MAAM,SAAY,OAAe,IAAiE;AAChG,UAAM,MAAM,KAAK,SAAS,KAAK;AAC/B,aAAS,UAAU,GAAG,WAAW,KAAK,YAAY,WAAW;AAC3D,YAAM,EAAE,OAAO,QAAQ,IAAI,MAAM,KAAK,KAAK,KAAK;AAChD,YAAM,EAAE,MAAM,OAAO,IAAI,GAAG,KAAK;AAEjC,UAAI,CAAC,KAAM,QAAO;AAClB,YAAM,KAAK,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,KAAK,SAAS,KAAK,UAAU,IAAI,GAAG,KAAK,QAAQ;AAC3F,UAAI,OAAO,EAAE,MAAM,EAAG,QAAO;AAC7B,YAAM,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,SAAS,CAAC,CAAC;AAClD,YAAM,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,KAAK,OAAO,IAAI,GAAG,CAAC;AAAA,IAC7D;AACA,UAAM,IAAI,qBAAqB,OAAO,KAAK,aAAa,CAAC;AAAA,EAC3D;AACF;","names":[]}

package/dist/redis.d.cts

@@ -0,0 +1,40 @@
+import { Store, ScopeState, TransactResult } from './index.cjs';
+
+/**
+ * The one Redis command replyonce uses, in ioredis' signature. For node-redis, pass
+ * `{ eval: (script, n, ...args) => client.eval(script, { keys: args.slice(0, n), arguments: args.slice(n) }) }`.
+ */
+interface RedisLike {
+    eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
+}
+interface RedisStoreOptions {
+    client: RedisLike;
+    /** Key prefix. Default `replyonce`. */
+    prefix?: string;
+    /** Expire idle scopes after this long. 0 disables expiry. Default 30 days. */
+    keyTtlMs?: number;
+    /** Optimistic retries under contention before giving up. Default 200. */
+    maxRetries?: number;
+}
+declare class StoreContentionError extends Error {
+    constructor(scope: string, attempts: number);
+}
+/**
+ * Redis store. Each scope is one hash holding the state and a version. `transact` reads
+ * both, decides locally, then writes with a compare-and-set Lua script, retrying on a lost
+ * race. Works on a shared connection (no WATCH) and with Redis Cluster (one key per op).
+ */
+declare class RedisStore implements Store {
+    private readonly client;
+    private readonly prefix;
+    private readonly keyTtlMs;
+    private readonly maxRetries;
+    constructor(options: RedisStoreOptions);
+    private redisKey;
+    private load;
+    read(scope: string): Promise<ScopeState | null>;
+    transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T>;
+}
+
+export { RedisStore, StoreContentionError };
+export type { RedisLike, RedisStoreOptions };

package/dist/redis.d.ts

@@ -0,0 +1,40 @@
+import { Store, ScopeState, TransactResult } from './index.js';
+
+/**
+ * The one Redis command replyonce uses, in ioredis' signature. For node-redis, pass
+ * `{ eval: (script, n, ...args) => client.eval(script, { keys: args.slice(0, n), arguments: args.slice(n) }) }`.
+ */
+interface RedisLike {
+    eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
+}
+interface RedisStoreOptions {
+    client: RedisLike;
+    /** Key prefix. Default `replyonce`. */
+    prefix?: string;
+    /** Expire idle scopes after this long. 0 disables expiry. Default 30 days. */
+    keyTtlMs?: number;
+    /** Optimistic retries under contention before giving up. Default 200. */
+    maxRetries?: number;
+}
+declare class StoreContentionError extends Error {
+    constructor(scope: string, attempts: number);
+}
+/**
+ * Redis store. Each scope is one hash holding the state and a version. `transact` reads
+ * both, decides locally, then writes with a compare-and-set Lua script, retrying on a lost
+ * race. Works on a shared connection (no WATCH) and with Redis Cluster (one key per op).
+ */
+declare class RedisStore implements Store {
+    private readonly client;
+    private readonly prefix;
+    private readonly keyTtlMs;
+    private readonly maxRetries;
+    constructor(options: RedisStoreOptions);
+    private redisKey;
+    private load;
+    read(scope: string): Promise<ScopeState | null>;
+    transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T>;
+}
+
+export { RedisStore, StoreContentionError };
+export type { RedisLike, RedisStoreOptions };

package/dist/redis.js

@@ -0,0 +1,59 @@
+// src/stores/redis.ts
+var READ = `return redis.call('HMGET', KEYS[1], 's', 'v')`;
+var CAS = `
+local v = tonumber(redis.call('HGET', KEYS[1], 'v') or '0')
+if v ~= tonumber(ARGV[1]) then return 0 end
+redis.call('HSET', KEYS[1], 's', ARGV[2], 'v', v + 1)
+local ttl = tonumber(ARGV[3])
+if ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end
+return 1
+`;
+var StoreContentionError = class extends Error {
+  constructor(scope, attempts) {
+    super(`replyonce: gave up on scope ${JSON.stringify(scope)} after ${attempts} contended attempts`);
+    this.name = "StoreContentionError";
+  }
+};
+var RedisStore = class {
+  client;
+  prefix;
+  keyTtlMs;
+  maxRetries;
+  constructor(options) {
+    if (!options?.client) throw new TypeError("replyonce: RedisStore needs a client");
+    this.client = options.client;
+    this.prefix = options.prefix ?? "replyonce";
+    this.keyTtlMs = options.keyTtlMs ?? 30 * 24 * 36e5;
+    this.maxRetries = options.maxRetries ?? 200;
+  }
+  redisKey(scope) {
+    return `${this.prefix}:{${scope}}`;
+  }
+  async load(scope) {
+    const reply = await this.client.eval(READ, 1, this.redisKey(scope));
+    const raw = reply?.[0] ?? null;
+    const version = reply?.[1] ? Number(reply[1]) : 0;
+    return { state: raw ? JSON.parse(raw) : null, version };
+  }
+  async read(scope) {
+    return (await this.load(scope)).state;
+  }
+  async transact(scope, fn) {
+    const key = this.redisKey(scope);
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const { state, version } = await this.load(scope);
+      const { next, result } = fn(state);
+      if (!next) return result;
+      const ok = await this.client.eval(CAS, 1, key, version, JSON.stringify(next), this.keyTtlMs);
+      if (Number(ok) === 1) return result;
+      const cap = Math.min(50, 2 ** Math.min(attempt, 6));
+      await new Promise((r) => setTimeout(r, Math.random() * cap));
+    }
+    throw new StoreContentionError(scope, this.maxRetries + 1);
+  }
+};
+export {
+  RedisStore,
+  StoreContentionError
+};
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stores/redis.ts"],"sourcesContent":["import type { ScopeState, Store, TransactResult } from '../types.js';\n\n/**\n * The one Redis command replyonce uses, in ioredis' signature. For node-redis, pass\n * `{ eval: (script, n, ...args) => client.eval(script, { keys: args.slice(0, n), arguments: args.slice(n) }) }`.\n */\nexport interface RedisLike {\n  eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;\n}\n\nexport interface RedisStoreOptions {\n  client: RedisLike;\n  /** Key prefix. Default `replyonce`. */\n  prefix?: string;\n  /** Expire idle scopes after this long. 0 disables expiry. Default 30 days. */\n  keyTtlMs?: number;\n  /** Optimistic retries under contention before giving up. Default 200. */\n  maxRetries?: number;\n}\n\nconst READ = `return redis.call('HMGET', KEYS[1], 's', 'v')`;\n\nconst CAS = `\nlocal v = tonumber(redis.call('HGET', KEYS[1], 'v') or '0')\nif v ~= tonumber(ARGV[1]) then return 0 end\nredis.call('HSET', KEYS[1], 's', ARGV[2], 'v', v + 1)\nlocal ttl = tonumber(ARGV[3])\nif ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end\nreturn 1\n`;\n\nexport class StoreContentionError extends Error {\n  constructor(scope: string, attempts: number) {\n    super(`replyonce: gave up on scope ${JSON.stringify(scope)} after ${attempts} contended attempts`);\n    this.name = 'StoreContentionError';\n  }\n}\n\n/**\n * Redis store. Each scope is one hash holding the state and a version. `transact` reads\n * both, decides locally, then writes with a compare-and-set Lua script, retrying on a lost\n * race. Works on a shared connection (no WATCH) and with Redis Cluster (one key per op).\n */\nexport class RedisStore implements Store {\n  private readonly client: RedisLike;\n  private readonly prefix: string;\n  private readonly keyTtlMs: number;\n  private readonly maxRetries: number;\n\n  constructor(options: RedisStoreOptions) {\n    if (!options?.client) throw new TypeError('replyonce: RedisStore needs a client');\n    this.client = options.client;\n    this.prefix = options.prefix ?? 'replyonce';\n    this.keyTtlMs = options.keyTtlMs ?? 30 * 24 * 3_600_000;\n    this.maxRetries = options.maxRetries ?? 200;\n  }\n\n  private redisKey(scope: string): string {\n    return `${this.prefix}:{${scope}}`;\n  }\n\n  private async load(scope: string): Promise<{ state: ScopeState | null; version: number }> {\n    const reply = (await this.client.eval(READ, 1, this.redisKey(scope))) as Array<string | null>;\n    const raw = reply?.[0] ?? null;\n    const version = reply?.[1] ? Number(reply[1]) : 0;\n    return { state: raw ? (JSON.parse(raw) as ScopeState) : null, version };\n  }\n\n  async read(scope: string): Promise<ScopeState | null> {\n    return (await this.load(scope)).state;\n  }\n\n  async transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T> {\n    const key = this.redisKey(scope);\n    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {\n      const { state, version } = await this.load(scope);\n      const { next, result } = fn(state);\n      // A read-only decision was taken against one consistent snapshot, so it stands.\n      if (!next) return result;\n      const ok = await this.client.eval(CAS, 1, key, version, JSON.stringify(next), this.keyTtlMs);\n      if (Number(ok) === 1) return result;\n      const cap = Math.min(50, 2 ** Math.min(attempt, 6));\n      await new Promise((r) => setTimeout(r, Math.random() * cap));\n    }\n    throw new StoreContentionError(scope, this.maxRetries + 1);\n  }\n}\n"],"mappings":";AAoBA,IAAM,OAAO;AAEb,IAAM,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASL,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAAY,OAAe,UAAkB;AAC3C,UAAM,+BAA+B,KAAK,UAAU,KAAK,CAAC,UAAU,QAAQ,qBAAqB;AACjG,SAAK,OAAO;AAAA,EACd;AACF;AAOO,IAAM,aAAN,MAAkC;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,SAA4B;AACtC,QAAI,CAAC,SAAS,OAAQ,OAAM,IAAI,UAAU,sCAAsC;AAChF,SAAK,SAAS,QAAQ;AACtB,SAAK,SAAS,QAAQ,UAAU;AAChC,SAAK,WAAW,QAAQ,YAAY,KAAK,KAAK;AAC9C,SAAK,aAAa,QAAQ,cAAc;AAAA,EAC1C;AAAA,EAEQ,SAAS,OAAuB;AACtC,WAAO,GAAG,KAAK,MAAM,KAAK,KAAK;AAAA,EACjC;AAAA,EAEA,MAAc,KAAK,OAAuE;AACxF,UAAM,QAAS,MAAM,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK,SAAS,KAAK,CAAC;AACnE,UAAM,MAAM,QAAQ,CAAC,KAAK;AAC1B,UAAM,UAAU,QAAQ,CAAC,IAAI,OAAO,MAAM,CAAC,CAAC,IAAI;AAChD,WAAO,EAAE,OAAO,MAAO,KAAK,MAAM,GAAG,IAAmB,MAAM,QAAQ;AAAA,EACxE;AAAA,EAEA,MAAM,KAAK,OAA2C;AACpD,YAAQ,MAAM,KAAK,KAAK,KAAK,GAAG;AAAA,EAClC;AAAA,EAEA,MAAM,SAAY,OAAe,IAAiE;AAChG,UAAM,MAAM,KAAK,SAAS,KAAK;AAC/B,aAAS,UAAU,GAAG,WAAW,KAAK,YAAY,WAAW;AAC3D,YAAM,EAAE,OAAO,QAAQ,IAAI,MAAM,KAAK,KAAK,KAAK;AAChD,YAAM,EAAE,MAAM,OAAO,IAAI,GAAG,KAAK;AAEjC,UAAI,CAAC,KAAM,QAAO;AAClB,YAAM,KAAK,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,KAAK,SAAS,KAAK,UAAU,IAAI,GAAG,KAAK,QAAQ;AAC3F,UAAI,OAAO,EAAE,MAAM,EAAG,QAAO;AAC7B,YAAM,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,SAAS,CAAC,CAAC;AAClD,YAAM,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,KAAK,OAAO,IAAI,GAAG,CAAC;AAAA,IAC7D;AACA,UAAM,IAAI,qBAAqB,OAAO,KAAK,aAAa,CAAC;AAAA,EAC3D;AACF;","names":[]}

package/dist/replyonce-CGwSjxB2.d.cts

@@ -0,0 +1,209 @@
+import { i as RunRecord, b as EffectRecord, S as Store, d as ErrorClass, e as ReconcileVerdict, g as ReplyOnceEvent, E as EffectContext, O as OnceResult, c as EffectStatus, J as Json, R as RunMode, h as RunEndReason } from './types-Dn7TSEnu.cjs';
+
+/**
+ * The replyonce state machine. Every function here is pure: it takes a scope's state and
+ * returns the next state plus a decision. Stores only make each call atomic.
+ */
+interface Policy {
+    pendingTtlMs: number;
+    maxAttempts: number;
+    retentionMs: number;
+}
+type ConflictMode = 'any' | 'same-intent' | 'none';
+type BeginOutcome = {
+    state: 'new' | 'resumed' | 'superseded' | 'ended';
+    run: RunRecord;
+    priorEffects: EffectRecord[];
+} | {
+    state: 'busy';
+    holder: {
+        runId: string;
+        token: number;
+        leaseExpiresAt: number;
+    };
+};
+
+/** Throw this (or anything with `replyonce: 'not_applied'`) when the effect definitely did not happen. */
+declare class NotApplied extends Error {
+    readonly replyonce: "not_applied";
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+declare function defaultClassifyError(err: unknown): ErrorClass;
+interface KeyParts {
+    /** Usually the conversation or thread id. All fencing happens within a scope. */
+    scope: string;
+    /** What the effect is: `reply`, `refund`, `create_ticket`. */
+    intent: string;
+    /**
+     * The business identity of the effect, hashed into the key. Use what makes it the same
+     * action (the inbound message being answered, the order being refunded), never
+     * model-generated text or a model tool-call id.
+     */
+    payload?: unknown;
+}
+type Reconciler = (entry: EffectRecord) => Promise<ReconcileVerdict>;
+interface ReplyOnceOptions {
+    store: Store;
+    /** How long a claim may stay pending before it is treated as abandoned (ambiguous). Default 15 min. */
+    pendingTtlMs?: number;
+    /** Attempts per key, counting only attempts known not to have applied. Default 3. */
+    maxAttempts?: number;
+    /** How long settled effects and ended runs are remembered. Default 7 days. */
+    retentionMs?: number;
+    /** Run lease length; renewed on every claim and heartbeat. Default 60 s. */
+    leaseTtlMs?: number;
+    /** Decide whether a thrown error means "did not happen" or "might have happened". */
+    classifyError?: (err: unknown) => ErrorClass;
+    /** Ask the outside world what happened to an ambiguous effect. */
+    reconcile?: Reconciler;
+    onEvent?: (event: ReplyOnceEvent) => void;
+    clock?: () => number;
+}
+interface OnceOptions {
+    /** Short human-readable description, shown to other runs in conflict reports. */
+    summary?: string;
+    classifyError?: (err: unknown) => ErrorClass;
+    reconcile?: Reconciler;
+    /** Wait for an in-flight duplicate to settle instead of returning `in_flight` immediately. */
+    wait?: {
+        timeoutMs: number;
+        intervalMs?: number;
+    };
+}
+interface RunOnceOptions extends OnceOptions {
+    /**
+     * `any` (default): refuse if another run wrote anything on this scope since this run last
+     * looked. `same-intent`: only effects with the same intent conflict. `none`: per-key
+     * idempotency and supersession only.
+     */
+    conflict?: ConflictMode;
+    /** Record that this run has now seen the conflicts, so its next attempt can proceed. Default true. */
+    ack?: boolean;
+}
+interface CheckResult {
+    /** `true` only when the effect is known to have happened. */
+    done: boolean;
+    status: EffectStatus | 'none';
+    entry: EffectRecord | null;
+}
+interface BeginOptions {
+    /** Stable id for this unit of work. Reuse it on redelivery (for example the queue job id). */
+    runId?: string;
+    mode?: RunMode;
+    leaseTtlMs?: number;
+    /**
+     * Epoch ms when this run's context (the conversation it will act on) was read, for
+     * example when the webhook payload was captured. Writes by other runs that landed
+     * after this point are reported as `conversation_changed`. Default: now.
+     */
+    contextAt?: number;
+}
+type Effect<T> = (ctx: EffectContext) => Promise<T> | T;
+declare class ReplyOnce {
+    readonly store: Store;
+    readonly policy: Policy;
+    readonly leaseTtlMs: number;
+    private readonly classify;
+    private readonly reconciler;
+    private readonly emit;
+    private readonly now;
+    constructor(options: ReplyOnceOptions);
+    /** Resolve key parts to the ledger key used for them. */
+    key(parts: KeyParts): string;
+    /**
+     * Run `effect` at most once for this key. A string key is its own scope; key parts give
+     * a scope (conversation) plus an intent and business identity.
+     */
+    once<T>(key: string | KeyParts, effect: Effect<T>, options?: OnceOptions): Promise<OnceResult<T>>;
+    /** "Was this already done?" — safe to expose to a model as a read-only tool. */
+    check(key: string | KeyParts): Promise<CheckResult>;
+    /** Every effect recorded on a scope, oldest first. */
+    history(scope: string): Promise<EffectRecord[]>;
+    /** Record what an operator or reconciler found out about an ambiguous effect. */
+    resolve(key: string | KeyParts, verdict: {
+        outcome: 'committed';
+        result?: Json;
+    } | {
+        outcome: 'not_applied';
+    }): Promise<EffectRecord | null>;
+    /**
+     * Start (or, with the same `runId`, resume) a unit of work on a scope. The run gets a
+     * fencing token; its writes are refused once a newer run owns the scope.
+     */
+    begin(scope: string, options?: BeginOptions): Promise<Run>;
+    /** Cancel a run: its future writes are refused with `run_cancelled`. */
+    cancel(scope: string, runId: string): Promise<boolean>;
+    /** @internal */
+    renewRun(scope: string, runId: string, token: number, leaseTtlMs: number): Promise<boolean>;
+    /** @internal */
+    endRun(scope: string, runId: string, token: number, reason: RunEndReason): Promise<void>;
+    /** @internal */
+    resolveKey(key: string | KeyParts): {
+        scope: string;
+        ledgerKey: string;
+        intent: string;
+    };
+    /** @internal */
+    execute<T>(scope: string, key: string, intent: string, run: {
+        runId: string;
+        token: number;
+        leaseTtlMs: number;
+    } | null, effect: Effect<T>, options: RunOnceOptions): Promise<OnceResult<T>>;
+    private runAcquired;
+    private settleWithRetry;
+    private waitForSettle;
+}
+type RunState = BeginOutcome['state'];
+/** A unit of agent work on one scope, holding a fencing token. */
+declare class Run {
+    readonly scope: string;
+    readonly runId: string;
+    /** `new`, `resumed` (same runId seen before), `superseded`, `ended`, or `busy` (exclusive mode). */
+    readonly state: RunState;
+    /** Monotonic per scope. `null` when the run could not start (`busy`). */
+    readonly fencingToken: number | null;
+    /** Effects this runId already claimed before (non-empty on redelivery). */
+    readonly priorEffects: EffectRecord[];
+    readonly busyHolder: {
+        runId: string;
+        token: number;
+        leaseExpiresAt: number;
+    } | null;
+    private readonly ro;
+    private readonly leaseTtlMs;
+    constructor(ro: ReplyOnce, scope: string, runId: string, leaseTtlMs: number, outcome: BeginOutcome);
+    /** `true` when this run may write: it is new or resumed, not superseded, ended or busy. */
+    get canWrite(): boolean;
+    /**
+     * `true` when a previous delivery of this run already claimed a write that may have
+     * reached the outside world (pending, committed or ambiguous).
+     */
+    get alreadyWrote(): boolean;
+    /** Run `effect` at most once per (scope, intent, payload), fenced to this run. */
+    once<T>(intent: string, payload: unknown, effect: Effect<T>, options?: RunOnceOptions): Promise<OnceResult<T>>;
+    check(intent: string, payload?: unknown): Promise<CheckResult>;
+    history(): Promise<EffectRecord[]>;
+    /**
+     * Renew the lease. `false` means stop: the run was superseded (by a newer run or a later
+     * delivery of this one), cancelled or ended.
+     */
+    heartbeat(): Promise<boolean>;
+    /** Mark the run finished. A no-op if a later delivery of the same run has taken over. */
+    end(reason?: RunEndReason): Promise<void>;
+}
+declare function createReplyOnce(options: ReplyOnceOptions): ReplyOnce;
+/** Return the value of a successful result, or throw a `ReplyOnceError` describing why not. */
+declare function unwrap<T>(result: OnceResult<T>): T;
+declare class ReplyOnceError extends Error {
+    readonly result: Exclude<OnceResult<unknown>, {
+        ok: true;
+    }>;
+    constructor(result: Exclude<OnceResult<unknown>, {
+        ok: true;
+    }>);
+}
+
+export { NotApplied as N, Run as R, ReplyOnce as a, ReplyOnceError as d, createReplyOnce as h, defaultClassifyError as i, unwrap as u };
+export type { BeginOptions as B, ConflictMode as C, Effect as E, KeyParts as K, OnceOptions as O, CheckResult as b, Reconciler as c, ReplyOnceOptions as e, RunOnceOptions as f, RunState as g };

package/dist/replyonce-DNRS4FWY.d.ts

@@ -0,0 +1,209 @@
+import { i as RunRecord, b as EffectRecord, S as Store, d as ErrorClass, e as ReconcileVerdict, g as ReplyOnceEvent, E as EffectContext, O as OnceResult, c as EffectStatus, J as Json, R as RunMode, h as RunEndReason } from './types-Dn7TSEnu.js';
+
+/**
+ * The replyonce state machine. Every function here is pure: it takes a scope's state and
+ * returns the next state plus a decision. Stores only make each call atomic.
+ */
+interface Policy {
+    pendingTtlMs: number;
+    maxAttempts: number;
+    retentionMs: number;
+}
+type ConflictMode = 'any' | 'same-intent' | 'none';
+type BeginOutcome = {
+    state: 'new' | 'resumed' | 'superseded' | 'ended';
+    run: RunRecord;
+    priorEffects: EffectRecord[];
+} | {
+    state: 'busy';
+    holder: {
+        runId: string;
+        token: number;
+        leaseExpiresAt: number;
+    };
+};
+
+/** Throw this (or anything with `replyonce: 'not_applied'`) when the effect definitely did not happen. */
+declare class NotApplied extends Error {
+    readonly replyonce: "not_applied";
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+declare function defaultClassifyError(err: unknown): ErrorClass;
+interface KeyParts {
+    /** Usually the conversation or thread id. All fencing happens within a scope. */
+    scope: string;
+    /** What the effect is: `reply`, `refund`, `create_ticket`. */
+    intent: string;
+    /**
+     * The business identity of the effect, hashed into the key. Use what makes it the same
+     * action (the inbound message being answered, the order being refunded), never
+     * model-generated text or a model tool-call id.
+     */
+    payload?: unknown;
+}
+type Reconciler = (entry: EffectRecord) => Promise<ReconcileVerdict>;
+interface ReplyOnceOptions {
+    store: Store;
+    /** How long a claim may stay pending before it is treated as abandoned (ambiguous). Default 15 min. */
+    pendingTtlMs?: number;
+    /** Attempts per key, counting only attempts known not to have applied. Default 3. */
+    maxAttempts?: number;
+    /** How long settled effects and ended runs are remembered. Default 7 days. */
+    retentionMs?: number;
+    /** Run lease length; renewed on every claim and heartbeat. Default 60 s. */
+    leaseTtlMs?: number;
+    /** Decide whether a thrown error means "did not happen" or "might have happened". */
+    classifyError?: (err: unknown) => ErrorClass;
+    /** Ask the outside world what happened to an ambiguous effect. */
+    reconcile?: Reconciler;
+    onEvent?: (event: ReplyOnceEvent) => void;
+    clock?: () => number;
+}
+interface OnceOptions {
+    /** Short human-readable description, shown to other runs in conflict reports. */
+    summary?: string;
+    classifyError?: (err: unknown) => ErrorClass;
+    reconcile?: Reconciler;
+    /** Wait for an in-flight duplicate to settle instead of returning `in_flight` immediately. */
+    wait?: {
+        timeoutMs: number;
+        intervalMs?: number;
+    };
+}
+interface RunOnceOptions extends OnceOptions {
+    /**
+     * `any` (default): refuse if another run wrote anything on this scope since this run last
+     * looked. `same-intent`: only effects with the same intent conflict. `none`: per-key
+     * idempotency and supersession only.
+     */
+    conflict?: ConflictMode;
+    /** Record that this run has now seen the conflicts, so its next attempt can proceed. Default true. */
+    ack?: boolean;
+}
+interface CheckResult {
+    /** `true` only when the effect is known to have happened. */
+    done: boolean;
+    status: EffectStatus | 'none';
+    entry: EffectRecord | null;
+}
+interface BeginOptions {
+    /** Stable id for this unit of work. Reuse it on redelivery (for example the queue job id). */
+    runId?: string;
+    mode?: RunMode;
+    leaseTtlMs?: number;
+    /**
+     * Epoch ms when this run's context (the conversation it will act on) was read, for
+     * example when the webhook payload was captured. Writes by other runs that landed
+     * after this point are reported as `conversation_changed`. Default: now.
+     */
+    contextAt?: number;
+}
+type Effect<T> = (ctx: EffectContext) => Promise<T> | T;
+declare class ReplyOnce {
+    readonly store: Store;
+    readonly policy: Policy;
+    readonly leaseTtlMs: number;
+    private readonly classify;
+    private readonly reconciler;
+    private readonly emit;
+    private readonly now;
+    constructor(options: ReplyOnceOptions);
+    /** Resolve key parts to the ledger key used for them. */
+    key(parts: KeyParts): string;
+    /**
+     * Run `effect` at most once for this key. A string key is its own scope; key parts give
+     * a scope (conversation) plus an intent and business identity.
+     */
+    once<T>(key: string | KeyParts, effect: Effect<T>, options?: OnceOptions): Promise<OnceResult<T>>;
+    /** "Was this already done?" — safe to expose to a model as a read-only tool. */
+    check(key: string | KeyParts): Promise<CheckResult>;
+    /** Every effect recorded on a scope, oldest first. */
+    history(scope: string): Promise<EffectRecord[]>;
+    /** Record what an operator or reconciler found out about an ambiguous effect. */
+    resolve(key: string | KeyParts, verdict: {
+        outcome: 'committed';
+        result?: Json;
+    } | {
+        outcome: 'not_applied';
+    }): Promise<EffectRecord | null>;
+    /**
+     * Start (or, with the same `runId`, resume) a unit of work on a scope. The run gets a
+     * fencing token; its writes are refused once a newer run owns the scope.
+     */
+    begin(scope: string, options?: BeginOptions): Promise<Run>;
+    /** Cancel a run: its future writes are refused with `run_cancelled`. */
+    cancel(scope: string, runId: string): Promise<boolean>;
+    /** @internal */
+    renewRun(scope: string, runId: string, token: number, leaseTtlMs: number): Promise<boolean>;
+    /** @internal */
+    endRun(scope: string, runId: string, token: number, reason: RunEndReason): Promise<void>;
+    /** @internal */
+    resolveKey(key: string | KeyParts): {
+        scope: string;
+        ledgerKey: string;
+        intent: string;
+    };
+    /** @internal */
+    execute<T>(scope: string, key: string, intent: string, run: {
+        runId: string;
+        token: number;
+        leaseTtlMs: number;
+    } | null, effect: Effect<T>, options: RunOnceOptions): Promise<OnceResult<T>>;
+    private runAcquired;
+    private settleWithRetry;
+    private waitForSettle;
+}
+type RunState = BeginOutcome['state'];
+/** A unit of agent work on one scope, holding a fencing token. */
+declare class Run {
+    readonly scope: string;
+    readonly runId: string;
+    /** `new`, `resumed` (same runId seen before), `superseded`, `ended`, or `busy` (exclusive mode). */
+    readonly state: RunState;
+    /** Monotonic per scope. `null` when the run could not start (`busy`). */
+    readonly fencingToken: number | null;
+    /** Effects this runId already claimed before (non-empty on redelivery). */
+    readonly priorEffects: EffectRecord[];
+    readonly busyHolder: {
+        runId: string;
+        token: number;
+        leaseExpiresAt: number;
+    } | null;
+    private readonly ro;
+    private readonly leaseTtlMs;
+    constructor(ro: ReplyOnce, scope: string, runId: string, leaseTtlMs: number, outcome: BeginOutcome);
+    /** `true` when this run may write: it is new or resumed, not superseded, ended or busy. */
+    get canWrite(): boolean;
+    /**
+     * `true` when a previous delivery of this run already claimed a write that may have
+     * reached the outside world (pending, committed or ambiguous).
+     */
+    get alreadyWrote(): boolean;
+    /** Run `effect` at most once per (scope, intent, payload), fenced to this run. */
+    once<T>(intent: string, payload: unknown, effect: Effect<T>, options?: RunOnceOptions): Promise<OnceResult<T>>;
+    check(intent: string, payload?: unknown): Promise<CheckResult>;
+    history(): Promise<EffectRecord[]>;
+    /**
+     * Renew the lease. `false` means stop: the run was superseded (by a newer run or a later
+     * delivery of this one), cancelled or ended.
+     */
+    heartbeat(): Promise<boolean>;
+    /** Mark the run finished. A no-op if a later delivery of the same run has taken over. */
+    end(reason?: RunEndReason): Promise<void>;
+}
+declare function createReplyOnce(options: ReplyOnceOptions): ReplyOnce;
+/** Return the value of a successful result, or throw a `ReplyOnceError` describing why not. */
+declare function unwrap<T>(result: OnceResult<T>): T;
+declare class ReplyOnceError extends Error {
+    readonly result: Exclude<OnceResult<unknown>, {
+        ok: true;
+    }>;
+    constructor(result: Exclude<OnceResult<unknown>, {
+        ok: true;
+    }>);
+}
+
+export { NotApplied as N, Run as R, ReplyOnce as a, ReplyOnceError as d, createReplyOnce as h, defaultClassifyError as i, unwrap as u };
+export type { BeginOptions as B, ConflictMode as C, Effect as E, KeyParts as K, OnceOptions as O, CheckResult as b, Reconciler as c, ReplyOnceOptions as e, RunOnceOptions as f, RunState as g };