replyonce 0.0.0-stage → 0.1.1

package/dist/types-Dn7TSEnu.d.cts

@@ -0,0 +1,209 @@
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Lifecycle of one effect in the ledger.
+ *
+ * - `pending`: an attempt claimed the key and may be executing right now.
+ * - `committed`: the effect is known to have happened. It is never run again.
+ * - `failed`: the effect is known NOT to have happened. A later call may retry.
+ * - `ambiguous`: it may or may not have happened (timeout, crash, unknown error).
+ *   It is never retried blindly; it must be reconciled.
+ */
+type EffectStatus = 'pending' | 'committed' | 'failed' | 'ambiguous';
+interface EffectRecord {
+    key: string;
+    scope: string;
+    intent: string;
+    status: EffectStatus;
+    attempt: number;
+    attemptId: string;
+    runId: string | null;
+    token: number | null;
+    summary: string | null;
+    result?: Json;
+    error: string | null;
+    createdAt: number;
+    claimedAt: number;
+    settledAt: number | null;
+    /** Scope sequence number of the claim and of the last settlement (logical clock). */
+    claimSeq: number;
+    settleSeq: number | null;
+}
+/**
+ * `supersede`: the newest run on a scope owns it; older runs are refused at write time.
+ * `exclusive`: one live lease holder at a time; a second `begin` is told the scope is busy
+ *   until the lease expires.
+ */
+type RunMode = 'supersede' | 'exclusive';
+type RunEndReason = 'completed' | 'failed' | 'cancelled';
+interface RunRecord {
+    runId: string;
+    token: number;
+    mode: RunMode;
+    startedAt: number;
+    /** Supersession order: when this run's context was read. Newer context owns the scope. */
+    orderAt: number;
+    leaseExpiresAt: number;
+    /** The run has seen every write settled at or before this scope sequence number. */
+    seenSeq: number;
+    /** Wall-clock time of the same moment, used only against TTL-based abandonment. */
+    seenAt: number;
+    /** Until the run's first claim or ack: writes settled at or after this time are unseen. */
+    contextAt: number | null;
+    /** The run's original context, restored when a redelivery takes the run over. */
+    baseSeq: number;
+    baseContextAt: number | null;
+    wrote: boolean;
+    endedAt: number | null;
+    endReason: RunEndReason | null;
+}
+/** Everything replyonce knows about one scope (usually one conversation or thread). */
+interface ScopeState {
+    v: 1;
+    /** Logical clock, incremented on every change to the scope. */
+    seq: number;
+    tokenSeq: number;
+    runs: Record<string, RunRecord>;
+    effects: Record<string, EffectRecord>;
+}
+interface TransactResult<T> {
+    /** New state to persist, or `null` to leave the stored state unchanged. */
+    next: ScopeState | null;
+    result: T;
+}
+/**
+ * A store gives atomic read-modify-write over one scope's state. That is the only
+ * primitive replyonce needs; all decision logic lives in the library.
+ */
+interface Store {
+    /**
+     * Atomically apply `fn` to the scope's current state. `fn` is synchronous and pure,
+     * and a store may call it more than once (optimistic retries).
+     */
+    transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T>;
+    read(scope: string): Promise<ScopeState | null>;
+}
+type RefusalReason = 'superseded' | 'run_cancelled' | 'run_ended' | 'unknown_run' | 'busy' | 'conversation_changed' | 'exhausted';
+interface ConflictInfo {
+    key: string;
+    intent: string;
+    status: EffectStatus;
+    runId: string | null;
+    summary: string | null;
+    at: number;
+}
+interface EffectContext {
+    key: string;
+    scope: string;
+    intent: string;
+    attempt: number;
+    /** Stable across attempts and workers. Pass it to providers that accept an idempotency key. */
+    idempotencyKey: string;
+    /** Fencing token of the run that claimed this effect, or `null` outside a run. */
+    fencingToken: number | null;
+    /** Aborts when the claim would be treated as abandoned (`pendingTtlMs`). */
+    signal: AbortSignal;
+}
+type OnceResult<T> = {
+    status: 'executed';
+    ok: true;
+    value: T;
+    key: string;
+    attempt: number;
+    lateSettle?: true;
+} | {
+    status: 'replayed';
+    ok: true;
+    value: T;
+    key: string;
+    entry: EffectRecord;
+} | {
+    status: 'in_flight';
+    ok: false;
+    key: string;
+    entry: EffectRecord;
+} | {
+    status: 'ambiguous';
+    ok: false;
+    key: string;
+    entry: EffectRecord;
+    error?: unknown;
+} | {
+    status: 'failed';
+    ok: false;
+    key: string;
+    attempt: number;
+    error: unknown;
+    retryable: boolean;
+} | {
+    status: 'refused';
+    ok: false;
+    key: string;
+    reason: RefusalReason;
+    conflicts?: ConflictInfo[];
+    entry?: EffectRecord;
+};
+type ReconcileVerdict = {
+    outcome: 'committed';
+    result?: Json;
+} | {
+    outcome: 'not_applied';
+} | {
+    outcome: 'unknown';
+};
+type ErrorClass = 'not_applied' | 'ambiguous';
+type ReplyOnceEvent = {
+    type: 'claimed';
+    scope: string;
+    key: string;
+    attempt: number;
+    runId: string | null;
+} | {
+    type: 'committed';
+    scope: string;
+    key: string;
+    attempt: number;
+    runId: string | null;
+} | {
+    type: 'replayed';
+    scope: string;
+    key: string;
+} | {
+    type: 'in_flight';
+    scope: string;
+    key: string;
+} | {
+    type: 'failed';
+    scope: string;
+    key: string;
+    attempt: number;
+    error: unknown;
+} | {
+    type: 'ambiguous';
+    scope: string;
+    key: string;
+    error?: unknown;
+} | {
+    type: 'refused';
+    scope: string;
+    key: string;
+    reason: RefusalReason;
+    runId: string | null;
+} | {
+    type: 'reconciled';
+    scope: string;
+    key: string;
+    outcome: ReconcileVerdict['outcome'];
+} | {
+    type: 'late_settle';
+    scope: string;
+    key: string;
+    attempt: number;
+} | {
+    type: 'unserializable_result';
+    scope: string;
+    key: string;
+};
+
+export type { ConflictInfo as C, EffectContext as E, Json as J, OnceResult as O, RunMode as R, Store as S, TransactResult as T, ScopeState as a, EffectRecord as b, EffectStatus as c, ErrorClass as d, ReconcileVerdict as e, RefusalReason as f, ReplyOnceEvent as g, RunEndReason as h, RunRecord as i };

package/dist/types-Dn7TSEnu.d.ts

@@ -0,0 +1,209 @@
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Lifecycle of one effect in the ledger.
+ *
+ * - `pending`: an attempt claimed the key and may be executing right now.
+ * - `committed`: the effect is known to have happened. It is never run again.
+ * - `failed`: the effect is known NOT to have happened. A later call may retry.
+ * - `ambiguous`: it may or may not have happened (timeout, crash, unknown error).
+ *   It is never retried blindly; it must be reconciled.
+ */
+type EffectStatus = 'pending' | 'committed' | 'failed' | 'ambiguous';
+interface EffectRecord {
+    key: string;
+    scope: string;
+    intent: string;
+    status: EffectStatus;
+    attempt: number;
+    attemptId: string;
+    runId: string | null;
+    token: number | null;
+    summary: string | null;
+    result?: Json;
+    error: string | null;
+    createdAt: number;
+    claimedAt: number;
+    settledAt: number | null;
+    /** Scope sequence number of the claim and of the last settlement (logical clock). */
+    claimSeq: number;
+    settleSeq: number | null;
+}
+/**
+ * `supersede`: the newest run on a scope owns it; older runs are refused at write time.
+ * `exclusive`: one live lease holder at a time; a second `begin` is told the scope is busy
+ *   until the lease expires.
+ */
+type RunMode = 'supersede' | 'exclusive';
+type RunEndReason = 'completed' | 'failed' | 'cancelled';
+interface RunRecord {
+    runId: string;
+    token: number;
+    mode: RunMode;
+    startedAt: number;
+    /** Supersession order: when this run's context was read. Newer context owns the scope. */
+    orderAt: number;
+    leaseExpiresAt: number;
+    /** The run has seen every write settled at or before this scope sequence number. */
+    seenSeq: number;
+    /** Wall-clock time of the same moment, used only against TTL-based abandonment. */
+    seenAt: number;
+    /** Until the run's first claim or ack: writes settled at or after this time are unseen. */
+    contextAt: number | null;
+    /** The run's original context, restored when a redelivery takes the run over. */
+    baseSeq: number;
+    baseContextAt: number | null;
+    wrote: boolean;
+    endedAt: number | null;
+    endReason: RunEndReason | null;
+}
+/** Everything replyonce knows about one scope (usually one conversation or thread). */
+interface ScopeState {
+    v: 1;
+    /** Logical clock, incremented on every change to the scope. */
+    seq: number;
+    tokenSeq: number;
+    runs: Record<string, RunRecord>;
+    effects: Record<string, EffectRecord>;
+}
+interface TransactResult<T> {
+    /** New state to persist, or `null` to leave the stored state unchanged. */
+    next: ScopeState | null;
+    result: T;
+}
+/**
+ * A store gives atomic read-modify-write over one scope's state. That is the only
+ * primitive replyonce needs; all decision logic lives in the library.
+ */
+interface Store {
+    /**
+     * Atomically apply `fn` to the scope's current state. `fn` is synchronous and pure,
+     * and a store may call it more than once (optimistic retries).
+     */
+    transact<T>(scope: string, fn: (state: ScopeState | null) => TransactResult<T>): Promise<T>;
+    read(scope: string): Promise<ScopeState | null>;
+}
+type RefusalReason = 'superseded' | 'run_cancelled' | 'run_ended' | 'unknown_run' | 'busy' | 'conversation_changed' | 'exhausted';
+interface ConflictInfo {
+    key: string;
+    intent: string;
+    status: EffectStatus;
+    runId: string | null;
+    summary: string | null;
+    at: number;
+}
+interface EffectContext {
+    key: string;
+    scope: string;
+    intent: string;
+    attempt: number;
+    /** Stable across attempts and workers. Pass it to providers that accept an idempotency key. */
+    idempotencyKey: string;
+    /** Fencing token of the run that claimed this effect, or `null` outside a run. */
+    fencingToken: number | null;
+    /** Aborts when the claim would be treated as abandoned (`pendingTtlMs`). */
+    signal: AbortSignal;
+}
+type OnceResult<T> = {
+    status: 'executed';
+    ok: true;
+    value: T;
+    key: string;
+    attempt: number;
+    lateSettle?: true;
+} | {
+    status: 'replayed';
+    ok: true;
+    value: T;
+    key: string;
+    entry: EffectRecord;
+} | {
+    status: 'in_flight';
+    ok: false;
+    key: string;
+    entry: EffectRecord;
+} | {
+    status: 'ambiguous';
+    ok: false;
+    key: string;
+    entry: EffectRecord;
+    error?: unknown;
+} | {
+    status: 'failed';
+    ok: false;
+    key: string;
+    attempt: number;
+    error: unknown;
+    retryable: boolean;
+} | {
+    status: 'refused';
+    ok: false;
+    key: string;
+    reason: RefusalReason;
+    conflicts?: ConflictInfo[];
+    entry?: EffectRecord;
+};
+type ReconcileVerdict = {
+    outcome: 'committed';
+    result?: Json;
+} | {
+    outcome: 'not_applied';
+} | {
+    outcome: 'unknown';
+};
+type ErrorClass = 'not_applied' | 'ambiguous';
+type ReplyOnceEvent = {
+    type: 'claimed';
+    scope: string;
+    key: string;
+    attempt: number;
+    runId: string | null;
+} | {
+    type: 'committed';
+    scope: string;
+    key: string;
+    attempt: number;
+    runId: string | null;
+} | {
+    type: 'replayed';
+    scope: string;
+    key: string;
+} | {
+    type: 'in_flight';
+    scope: string;
+    key: string;
+} | {
+    type: 'failed';
+    scope: string;
+    key: string;
+    attempt: number;
+    error: unknown;
+} | {
+    type: 'ambiguous';
+    scope: string;
+    key: string;
+    error?: unknown;
+} | {
+    type: 'refused';
+    scope: string;
+    key: string;
+    reason: RefusalReason;
+    runId: string | null;
+} | {
+    type: 'reconciled';
+    scope: string;
+    key: string;
+    outcome: ReconcileVerdict['outcome'];
+} | {
+    type: 'late_settle';
+    scope: string;
+    key: string;
+    attempt: number;
+} | {
+    type: 'unserializable_result';
+    scope: string;
+    key: string;
+};
+
+export type { ConflictInfo as C, EffectContext as E, Json as J, OnceResult as O, RunMode as R, Store as S, TransactResult as T, ScopeState as a, EffectRecord as b, EffectStatus as c, ErrorClass as d, ReconcileVerdict as e, RefusalReason as f, ReplyOnceEvent as g, RunEndReason as h, RunRecord as i };

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "replyonce",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Stop your agent from replying, refunding or ticketing twice. Idempotency keys, per-conversation write fencing and an effect ledger for tool-calling agents, webhook handlers and queue workers.",
+  "license": "Apache-2.0",
+  "author": "Sarosh Hussain (https://github.com/shmindmaster)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shmindmaster/replyonce.git"
+  },
+  "homepage": "https://github.com/shmindmaster/replyonce#readme",
+  "bugs": {
+    "url": "https://github.com/shmindmaster/replyonce/issues"
+  },
+  "keywords": [
+    "idempotency",
+    "exactly-once",
+    "ai-agents",
+    "llm",
+    "tool-calling",
+    "side-effects",
+    "webhooks",
+    "bullmq",
+    "fencing-token",
+    "outbox",
+    "postgres",
+    "redis"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./postgres": {
+      "import": {
+        "types": "./dist/postgres.d.ts",
+        "default": "./dist/postgres.js"
+      },
+      "require": {
+        "types": "./dist/postgres.d.cts",
+        "default": "./dist/postgres.cjs"
+      }
+    },
+    "./redis": {
+      "import": {
+        "types": "./dist/redis.d.ts",
+        "default": "./dist/redis.js"
+      },
+      "require": {
+        "types": "./dist/redis.d.cts",
+        "default": "./dist/redis.cjs"
+      }
+    },
+    "./adapters": {
+      "import": {
+        "types": "./dist/adapters.d.ts",
+        "default": "./dist/adapters.js"
+      },
+      "require": {
+        "types": "./dist/adapters.d.cts",
+        "default": "./dist/adapters.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "replyonce": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node test/smoke.mjs && node test/smoke.cjs",
+    "demo": "node dist/cli.js demo",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test && npm run smoke"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "bullmq": "^5.81.5",
+    "ioredis": "^5.4.0",
+    "pg": "^8.13.0",
+    "tsup": "^9.0.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}