replyonce 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,999 @@
+#!/usr/bin/env node
+
+// src/key.ts
+import { createHash } from "crypto";
+function canonicalJson(value) {
+  return JSON.stringify(normalize(value, /* @__PURE__ */ new Set()));
+}
+function normalize(value, seen) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value !== "object") {
+    if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+    if (typeof value === "function" || typeof value === "symbol") return null;
+    return value;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (seen.has(value)) throw new TypeError("replyonce: cannot hash a circular payload");
+  seen.add(value);
+  let out;
+  if (Array.isArray(value)) {
+    out = value.map((v) => normalize(v, seen));
+  } else {
+    const obj = {};
+    for (const k of Object.keys(value).sort()) {
+      const v = value[k];
+      if (v === void 0) continue;
+      obj[k] = normalize(v, seen);
+    }
+    out = obj;
+  }
+  seen.delete(value);
+  return out;
+}
+function sha256Hex(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function hashPayload(payload) {
+  return sha256Hex(canonicalJson(payload)).slice(0, 32);
+}
+var SAFE_INTENT = /^[A-Za-z0-9_.:-]{1,100}$/;
+function effectKey(intent, payload) {
+  if (!SAFE_INTENT.test(intent)) {
+    throw new TypeError(
+      `replyonce: intent must match ${SAFE_INTENT} (got ${JSON.stringify(intent)})`
+    );
+  }
+  return payload === void 0 ? intent : `${intent}:${hashPayload(payload)}`;
+}
+function providerIdempotencyKey(scope, key) {
+  return `ro_${sha256Hex(`${scope}\0${key}`).slice(0, 40)}`;
+}
+
+// src/replyonce.ts
+import { randomUUID } from "crypto";
+
+// src/logic.ts
+var SUMMARY_MAX = 2e3;
+function emptyState() {
+  return { v: 1, seq: 0, tokenSeq: 0, runs: {}, effects: {} };
+}
+function load(state, now, policy) {
+  const s = state ? structuredClone(state) : emptyState();
+  if (s.v !== 1) throw new Error(`replyonce: unsupported state version ${String(s.v)}`);
+  const horizon = now - policy.retentionMs;
+  for (const [k, e] of Object.entries(s.effects)) {
+    if ((e.status === "committed" || e.status === "failed") && (e.settledAt ?? e.claimedAt) < horizon) {
+      delete s.effects[k];
+    }
+  }
+  for (const [id, r] of Object.entries(s.runs)) {
+    if ((r.endedAt ?? r.leaseExpiresAt) < horizon) delete s.runs[id];
+  }
+  return s;
+}
+function tick(s) {
+  s.seq += 1;
+  return s.seq;
+}
+function isAbandoned(e, now, policy) {
+  return e.status === "pending" && now - e.claimedAt >= policy.pendingTtlMs;
+}
+function effectiveStatus(e, now, policy) {
+  return isAbandoned(e, now, policy) ? "ambiguous" : e.status;
+}
+function isLive(r, now) {
+  return r.endedAt === null && r.leaseExpiresAt > now;
+}
+function isNewer(a, b) {
+  if (a.mode === "exclusive" && b.mode === "exclusive") return a.token > b.token;
+  if (a.orderAt !== b.orderAt) return a.orderAt > b.orderAt;
+  if (a.baseContextAt !== null || b.baseContextAt !== null) return false;
+  return a.baseSeq > b.baseSeq;
+}
+function supersedingRun(s, run, now) {
+  let best = null;
+  for (const r of Object.values(s.runs)) {
+    if (r.runId === run.runId || r.endReason === "cancelled" || !isNewer(r, run)) continue;
+    if (r.wrote || isLive(r, now)) {
+      if (!best || isNewer(r, best)) best = r;
+    }
+  }
+  return best;
+}
+function markSeen(run, seq, now) {
+  run.seenSeq = Math.max(run.seenSeq, seq);
+  run.seenAt = Math.max(run.seenAt, now);
+  run.contextAt = null;
+}
+function begin(state, input, policy) {
+  const { now } = input;
+  const s = load(state, now, policy);
+  const existing = s.runs[input.runId];
+  if (existing) {
+    const priorEffects = Object.values(s.effects).filter((e) => e.runId === input.runId);
+    if (existing.endedAt !== null) {
+      return { next: null, result: { state: "ended", run: existing, priorEffects } };
+    }
+    existing.leaseExpiresAt = Math.max(existing.leaseExpiresAt, now + input.leaseTtlMs);
+    tick(s);
+    s.tokenSeq += 1;
+    existing.token = s.tokenSeq;
+    existing.seenSeq = existing.baseSeq;
+    existing.seenAt = existing.baseContextAt ?? existing.startedAt;
+    existing.contextAt = existing.baseContextAt;
+    if (input.contextAt !== void 0 && input.contextAt > existing.seenAt) {
+      const fresh = Math.min(input.contextAt, now);
+      for (const e of Object.values(s.effects)) {
+        if (e.settleSeq !== null && e.settledAt !== null && e.settledAt < fresh) {
+          existing.seenSeq = Math.max(existing.seenSeq, e.settleSeq);
+        }
+      }
+      existing.seenAt = fresh;
+      existing.contextAt = fresh;
+    }
+    const newer2 = supersedingRun(s, existing, now);
+    return { next: s, result: { state: newer2 ? "superseded" : "resumed", run: existing, priorEffects } };
+  }
+  if (input.mode === "exclusive") {
+    let holder;
+    for (const r of Object.values(s.runs)) {
+      if (isLive(r, now) && (!holder || r.token > holder.token)) holder = r;
+    }
+    if (holder) {
+      return {
+        next: null,
+        result: {
+          state: "busy",
+          holder: { runId: holder.runId, token: holder.token, leaseExpiresAt: holder.leaseExpiresAt }
+        }
+      };
+    }
+  }
+  const seq = tick(s);
+  s.tokenSeq += 1;
+  const contextAt = input.contextAt === void 0 ? null : Math.min(input.contextAt, now);
+  const run = {
+    runId: input.runId,
+    token: s.tokenSeq,
+    mode: input.mode,
+    startedAt: now,
+    orderAt: input.mode === "exclusive" ? now : contextAt ?? now,
+    leaseExpiresAt: now + input.leaseTtlMs,
+    seenSeq: seq,
+    seenAt: contextAt ?? now,
+    contextAt,
+    baseSeq: seq,
+    baseContextAt: contextAt,
+    wrote: false,
+    endedAt: null,
+    endReason: null
+  };
+  s.runs[input.runId] = run;
+  const newer = supersedingRun(s, run, now);
+  return { next: s, result: { state: newer ? "superseded" : "new", run, priorEffects: [] } };
+}
+function renew(state, input, policy) {
+  const s = load(state, input.now, policy);
+  const r = s.runs[input.runId];
+  if (!r) return { next: null, result: { ok: false, reason: "unknown_run" } };
+  if (r.token !== input.token) return { next: null, result: { ok: false, reason: "superseded" } };
+  if (r.endReason === "cancelled") return { next: null, result: { ok: false, reason: "run_cancelled" } };
+  if (r.endedAt !== null) return { next: null, result: { ok: false, reason: "run_ended" } };
+  if (supersedingRun(s, r, input.now)) return { next: null, result: { ok: false, reason: "superseded" } };
+  r.leaseExpiresAt = Math.max(r.leaseExpiresAt, input.now + input.leaseTtlMs);
+  tick(s);
+  return { next: s, result: { ok: true, run: r } };
+}
+function endRun(state, input, policy) {
+  const s = load(state, input.now, policy);
+  const r = s.runs[input.runId];
+  if (!r) return { next: null, result: null };
+  if (input.token !== void 0 && r.token !== input.token) return { next: null, result: null };
+  if (r.endedAt !== null && !(input.reason === "cancelled" && r.endReason !== "cancelled")) {
+    return { next: null, result: r };
+  }
+  r.endedAt = r.endedAt ?? input.now;
+  r.endReason = input.reason;
+  tick(s);
+  return { next: s, result: r };
+}
+function conflictsFor(s, run, key, intent, mode, now, policy) {
+  if (mode === "none") return [];
+  const out = [];
+  for (const e of Object.values(s.effects)) {
+    if (e.key === key) continue;
+    if (e.runId === run.runId) {
+      if (e.token === run.token || e.intent !== intent) continue;
+    }
+    if (mode === "same-intent" && e.intent !== intent) continue;
+    const abandoned = isAbandoned(e, now, policy);
+    let conflict = false;
+    if (e.status === "pending" && !abandoned) {
+      conflict = true;
+    } else if (abandoned) {
+      conflict = e.claimedAt + policy.pendingTtlMs >= run.seenAt;
+    } else if (e.status === "committed" || e.status === "ambiguous") {
+      conflict = (e.settleSeq ?? 0) > run.seenSeq || run.contextAt !== null && (e.settledAt ?? 0) >= run.contextAt;
+    }
+    if (conflict) {
+      out.push({
+        key: e.key,
+        intent: e.intent,
+        status: abandoned ? "ambiguous" : e.status,
+        runId: e.runId,
+        summary: e.summary,
+        at: e.settledAt ?? e.claimedAt
+      });
+    }
+  }
+  return out.sort((a, b) => a.at - b.at).slice(0, 10);
+}
+function claim(state, scope, input, policy) {
+  const { now } = input;
+  const s = load(state, now, policy);
+  const prior = s.effects[input.key];
+  if (prior) {
+    if (prior.status === "committed") return { next: null, result: { kind: "replay", entry: prior } };
+    if (prior.status === "pending") {
+      if (!isAbandoned(prior, now, policy)) {
+        return { next: null, result: { kind: "in_flight", entry: prior } };
+      }
+      const seq2 = tick(s);
+      prior.status = "ambiguous";
+      prior.settledAt = prior.claimedAt + policy.pendingTtlMs;
+      prior.settleSeq = seq2;
+      prior.error = prior.error ?? "abandoned: not settled within pendingTtlMs";
+      return { next: s, result: { kind: "ambiguous", entry: prior } };
+    }
+    if (prior.status === "ambiguous") return { next: null, result: { kind: "ambiguous", entry: prior } };
+    if (prior.attempt >= policy.maxAttempts) {
+      return { next: null, result: { kind: "refused", reason: "exhausted", entry: prior } };
+    }
+  }
+  let run;
+  if (input.runId !== null) {
+    run = s.runs[input.runId];
+    if (!run) return { next: null, result: { kind: "refused", reason: "unknown_run" } };
+    if (run.endReason === "cancelled") return { next: null, result: { kind: "refused", reason: "run_cancelled" } };
+    if (run.endedAt !== null) return { next: null, result: { kind: "refused", reason: "run_ended" } };
+    if (input.token !== null && run.token !== input.token || supersedingRun(s, run, now)) {
+      return { next: null, result: { kind: "refused", reason: "superseded" } };
+    }
+    const conflicts = conflictsFor(s, run, input.key, input.intent, input.conflict, now, policy);
+    if (conflicts.length > 0) {
+      if (!input.ack) {
+        return { next: null, result: { kind: "refused", reason: "conversation_changed", conflicts } };
+      }
+      markSeen(run, tick(s), now);
+      return { next: s, result: { kind: "refused", reason: "conversation_changed", conflicts } };
+    }
+  }
+  const seq = tick(s);
+  const entry = {
+    key: input.key,
+    scope,
+    intent: input.intent,
+    status: "pending",
+    attempt: (prior?.attempt ?? 0) + 1,
+    attemptId: input.attemptId,
+    runId: input.runId,
+    token: run?.token ?? null,
+    summary: input.summary === null ? null : input.summary.slice(0, SUMMARY_MAX),
+    error: null,
+    createdAt: prior?.createdAt ?? now,
+    claimedAt: now,
+    settledAt: null,
+    claimSeq: seq,
+    settleSeq: null
+  };
+  s.effects[input.key] = entry;
+  if (run) {
+    run.wrote = true;
+    run.leaseExpiresAt = Math.max(run.leaseExpiresAt, now + input.leaseTtlMs);
+  }
+  return { next: s, result: { kind: "acquired", entry } };
+}
+function settle(state, input, policy) {
+  const s = load(state, input.now, policy);
+  const e = s.effects[input.key];
+  const lateTruth = e?.status === "failed" && input.outcome === "committed";
+  if (!e || e.attemptId !== input.attemptId || e.status !== "pending" && e.status !== "ambiguous" && !lateTruth) {
+    return { next: null, result: { kind: "stale", entry: e ?? null } };
+  }
+  const wasAbandoned = e.status !== "pending" || isAbandoned(e, input.now, policy);
+  e.status = input.outcome;
+  e.settledAt = input.now;
+  e.settleSeq = tick(s);
+  e.error = input.error ?? null;
+  if (input.outcome === "committed" && input.result !== void 0) e.result = input.result;
+  return { next: s, result: { kind: "settled", entry: e, wasAbandoned } };
+}
+function resolve(state, input, policy) {
+  const s = load(state, input.now, policy);
+  const e = s.effects[input.key];
+  if (!e) return { next: null, result: null };
+  if (input.attemptId !== void 0 && e.attemptId !== input.attemptId) return { next: null, result: null };
+  if (effectiveStatus(e, input.now, policy) !== "ambiguous") return { next: null, result: null };
+  e.settledAt = input.now;
+  e.settleSeq = tick(s);
+  if (input.outcome === "committed") {
+    e.status = "committed";
+    e.error = null;
+    if (input.result !== void 0) e.result = input.result;
+  } else {
+    e.status = "failed";
+    e.error = "reconciled: not applied";
+  }
+  return { next: s, result: e };
+}
+
+// src/replyonce.ts
+var NotApplied = class extends Error {
+  replyonce = "not_applied";
+  constructor(message = "effect not applied", options) {
+    super(message);
+    this.name = "NotApplied";
+    if (options && "cause" in options) this.cause = options.cause;
+  }
+};
+function defaultClassifyError(err) {
+  if (err instanceof NotApplied) return "not_applied";
+  if (err && typeof err === "object" && err.replyonce === "not_applied") {
+    return "not_applied";
+  }
+  return "ambiguous";
+}
+var MAX_ROUNDS = 5;
+var ReplyOnce = class {
+  store;
+  policy;
+  leaseTtlMs;
+  classify;
+  reconciler;
+  emit;
+  now;
+  constructor(options) {
+    if (!options || !options.store) throw new TypeError("replyonce: a store is required");
+    this.store = options.store;
+    this.policy = {
+      pendingTtlMs: options.pendingTtlMs ?? 15 * 6e4,
+      maxAttempts: options.maxAttempts ?? 3,
+      retentionMs: options.retentionMs ?? 7 * 24 * 36e5
+    };
+    if (this.policy.pendingTtlMs <= 0 || this.policy.maxAttempts < 1 || this.policy.retentionMs <= 0) {
+      throw new RangeError("replyonce: pendingTtlMs, maxAttempts and retentionMs must be positive");
+    }
+    this.leaseTtlMs = options.leaseTtlMs ?? 6e4;
+    this.classify = options.classifyError ?? defaultClassifyError;
+    this.reconciler = options.reconcile;
+    const onEvent = options.onEvent;
+    this.emit = onEvent ? (e) => {
+      try {
+        onEvent(e);
+      } catch {
+      }
+    } : () => {
+    };
+    this.now = options.clock ?? Date.now;
+  }
+  /** Resolve key parts to the ledger key used for them. */
+  key(parts) {
+    return effectKey(parts.intent, parts.payload);
+  }
+  /**
+   * 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(key, effect, options = {}) {
+    const { scope, ledgerKey, intent } = this.resolveKey(key);
+    return this.execute(scope, ledgerKey, intent, null, effect, { ...options, conflict: "none", ack: false });
+  }
+  /** "Was this already done?" — safe to expose to a model as a read-only tool. */
+  async check(key) {
+    const { scope, ledgerKey } = this.resolveKey(key);
+    const state = await this.store.read(scope);
+    const entry = state?.effects[ledgerKey] ?? null;
+    if (!entry) return { done: false, status: "none", entry: null };
+    const status = effectiveStatus(entry, this.now(), this.policy);
+    return { done: status === "committed", status, entry };
+  }
+  /** Every effect recorded on a scope, oldest first. */
+  async history(scope) {
+    const state = await this.store.read(scope);
+    if (!state) return [];
+    const now = this.now();
+    return Object.values(state.effects).map((e) => ({ ...e, status: effectiveStatus(e, now, this.policy) })).sort((a, b) => a.createdAt - b.createdAt);
+  }
+  /** Record what an operator or reconciler found out about an ambiguous effect. */
+  async resolve(key, verdict) {
+    const { scope, ledgerKey } = this.resolveKey(key);
+    const result = "result" in verdict ? verdict.result : void 0;
+    const now = this.now();
+    const entry = await this.store.transact(
+      scope,
+      (s) => resolve(s, { key: ledgerKey, outcome: verdict.outcome, result, now }, this.policy)
+    );
+    if (entry) this.emit({ type: "reconciled", scope, key: ledgerKey, outcome: verdict.outcome });
+    return entry;
+  }
+  /**
+   * 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.
+   */
+  async begin(scope, options = {}) {
+    assertScope(scope);
+    const runId = options.runId ?? randomUUID();
+    const leaseTtlMs = options.leaseTtlMs ?? this.leaseTtlMs;
+    const now = this.now();
+    const outcome = await this.store.transact(
+      scope,
+      (s) => begin(
+        s,
+        {
+          runId,
+          mode: options.mode ?? "supersede",
+          leaseTtlMs,
+          now,
+          ...options.contextAt !== void 0 ? { contextAt: options.contextAt } : {}
+        },
+        this.policy
+      )
+    );
+    return new Run(this, scope, runId, leaseTtlMs, outcome);
+  }
+  /** Cancel a run: its future writes are refused with `run_cancelled`. */
+  async cancel(scope, runId) {
+    const now = this.now();
+    const r = await this.store.transact(
+      scope,
+      (s) => endRun(s, { runId, reason: "cancelled", now }, this.policy)
+    );
+    return r !== null;
+  }
+  /** @internal */
+  async renewRun(scope, runId, token, leaseTtlMs) {
+    const now = this.now();
+    const r = await this.store.transact(
+      scope,
+      (s) => renew(s, { runId, token, leaseTtlMs, now }, this.policy)
+    );
+    return r.ok;
+  }
+  /** @internal */
+  async endRun(scope, runId, token, reason) {
+    const now = this.now();
+    await this.store.transact(scope, (s) => endRun(s, { runId, token, reason, now }, this.policy));
+  }
+  /** @internal */
+  resolveKey(key) {
+    if (typeof key === "string") {
+      assertScope(key);
+      return { scope: key, ledgerKey: key, intent: "once" };
+    }
+    assertScope(key.scope);
+    return { scope: key.scope, ledgerKey: effectKey(key.intent, key.payload), intent: key.intent };
+  }
+  /** @internal */
+  async execute(scope, key, intent, run, effect, options) {
+    const runId = run?.runId ?? null;
+    const token = run?.token ?? null;
+    const classify = options.classifyError ?? this.classify;
+    const reconcile = options.reconcile ?? this.reconciler;
+    const waitUntil = options.wait ? this.now() + options.wait.timeoutMs : 0;
+    let reconciledOnce = false;
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      const attemptId = randomUUID();
+      const now = this.now();
+      const claimed = await this.store.transact(
+        scope,
+        (s) => claim(
+          s,
+          scope,
+          {
+            key,
+            intent,
+            summary: options.summary ?? null,
+            runId,
+            token,
+            attemptId,
+            conflict: options.conflict ?? "any",
+            ack: options.ack ?? true,
+            leaseTtlMs: run?.leaseTtlMs ?? this.leaseTtlMs,
+            now
+          },
+          this.policy
+        )
+      );
+      switch (claimed.kind) {
+        case "replay":
+          this.emit({ type: "replayed", scope, key });
+          return { status: "replayed", ok: true, value: claimed.entry.result, key, entry: claimed.entry };
+        case "refused":
+          this.emit({ type: "refused", scope, key, reason: claimed.reason, runId });
+          return {
+            status: "refused",
+            ok: false,
+            key,
+            reason: claimed.reason,
+            ...claimed.conflicts ? { conflicts: claimed.conflicts } : {},
+            ...claimed.entry ? { entry: claimed.entry } : {}
+          };
+        case "in_flight": {
+          if (options.wait && this.now() < waitUntil) {
+            await this.waitForSettle(scope, key, waitUntil, options.wait.intervalMs ?? 100);
+            continue;
+          }
+          this.emit({ type: "in_flight", scope, key });
+          return { status: "in_flight", ok: false, key, entry: claimed.entry };
+        }
+        case "ambiguous": {
+          if (reconcile && !reconciledOnce) {
+            reconciledOnce = true;
+            let verdict;
+            try {
+              verdict = await reconcile(claimed.entry);
+            } catch {
+              verdict = { outcome: "unknown" };
+            }
+            if (verdict.outcome !== "unknown") {
+              const at = this.now();
+              const resolved = await this.store.transact(
+                scope,
+                (s) => resolve(
+                  s,
+                  {
+                    key,
+                    outcome: verdict.outcome,
+                    result: verdict.outcome === "committed" ? verdict.result : void 0,
+                    attemptId: claimed.entry.attemptId,
+                    now: at
+                  },
+                  this.policy
+                )
+              );
+              if (resolved) this.emit({ type: "reconciled", scope, key, outcome: verdict.outcome });
+              continue;
+            }
+          }
+          this.emit({ type: "ambiguous", scope, key });
+          return { status: "ambiguous", ok: false, key, entry: claimed.entry };
+        }
+        case "acquired":
+          return this.runAcquired(scope, key, claimed.entry, effect, classify);
+      }
+    }
+    const entry = (await this.store.read(scope))?.effects[key];
+    if (entry && entry.status === "committed") {
+      return { status: "replayed", ok: true, value: entry.result, key, entry };
+    }
+    if (entry) {
+      this.emit({ type: "in_flight", scope, key });
+      return { status: "in_flight", ok: false, key, entry };
+    }
+    throw new Error("replyonce: could not claim key after several rounds");
+  }
+  async runAcquired(scope, key, entry, effect, classify) {
+    const { attempt, attemptId, runId } = entry;
+    this.emit({ type: "claimed", scope, key, attempt, runId });
+    const remaining = Math.max(1, entry.claimedAt + this.policy.pendingTtlMs - this.now());
+    const ctx = {
+      key,
+      scope,
+      intent: entry.intent,
+      attempt,
+      idempotencyKey: providerIdempotencyKey(scope, key),
+      fencingToken: entry.token,
+      signal: AbortSignal.timeout(remaining)
+    };
+    let value;
+    try {
+      value = await effect(ctx);
+    } catch (error) {
+      const cls = safeClassify(classify, error);
+      const outcome = cls === "not_applied" ? "failed" : "ambiguous";
+      await this.settleWithRetry(scope, {
+        key,
+        attemptId,
+        outcome,
+        error: describeError(error),
+        now: 0
+      }).catch(() => void 0);
+      if (outcome === "failed") {
+        this.emit({ type: "failed", scope, key, attempt, error });
+        return {
+          status: "failed",
+          ok: false,
+          key,
+          attempt,
+          error,
+          retryable: attempt < this.policy.maxAttempts
+        };
+      }
+      this.emit({ type: "ambiguous", scope, key, error });
+      const current = (await this.store.read(scope).catch(() => null))?.effects[key] ?? entry;
+      return { status: "ambiguous", ok: false, key, entry: current, error };
+    }
+    let stored;
+    try {
+      stored = value === void 0 ? null : JSON.parse(JSON.stringify(value));
+    } catch {
+      stored = null;
+      this.emit({ type: "unserializable_result", scope, key });
+    }
+    try {
+      const settled = await this.settleWithRetry(scope, {
+        key,
+        attemptId,
+        outcome: "committed",
+        result: stored,
+        now: 0
+      });
+      this.emit({ type: "committed", scope, key, attempt, runId });
+      if (settled.kind === "stale" || settled.wasAbandoned) {
+        this.emit({ type: "late_settle", scope, key, attempt });
+        return { status: "executed", ok: true, value, key, attempt, lateSettle: true };
+      }
+    } catch {
+      this.emit({ type: "late_settle", scope, key, attempt });
+      return { status: "executed", ok: true, value, key, attempt, lateSettle: true };
+    }
+    return { status: "executed", ok: true, value, key, attempt };
+  }
+  async settleWithRetry(scope, input) {
+    let lastError;
+    for (let i = 0; i < 4; i++) {
+      try {
+        const now = this.now();
+        return await this.store.transact(scope, (s) => settle(s, { ...input, now }, this.policy));
+      } catch (err) {
+        lastError = err;
+        await sleep(25 * 4 ** i);
+      }
+    }
+    throw lastError;
+  }
+  async waitForSettle(scope, key, until, intervalMs) {
+    while (this.now() < until) {
+      await sleep(Math.min(intervalMs, Math.max(1, until - this.now())));
+      const e = (await this.store.read(scope))?.effects[key];
+      if (!e || effectiveStatus(e, this.now(), this.policy) !== "pending") return;
+    }
+  }
+};
+var Run = class {
+  scope;
+  runId;
+  /** `new`, `resumed` (same runId seen before), `superseded`, `ended`, or `busy` (exclusive mode). */
+  state;
+  /** Monotonic per scope. `null` when the run could not start (`busy`). */
+  fencingToken;
+  /** Effects this runId already claimed before (non-empty on redelivery). */
+  priorEffects;
+  busyHolder;
+  ro;
+  leaseTtlMs;
+  constructor(ro, scope, runId, leaseTtlMs, outcome) {
+    this.ro = ro;
+    this.scope = scope;
+    this.runId = runId;
+    this.leaseTtlMs = leaseTtlMs;
+    this.state = outcome.state;
+    if (outcome.state === "busy") {
+      this.fencingToken = null;
+      this.priorEffects = [];
+      this.busyHolder = outcome.holder;
+    } else {
+      this.fencingToken = outcome.run.token;
+      this.priorEffects = outcome.priorEffects;
+      this.busyHolder = null;
+    }
+  }
+  /** `true` when this run may write: it is new or resumed, not superseded, ended or busy. */
+  get canWrite() {
+    return this.state === "new" || this.state === "resumed";
+  }
+  /**
+   * `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() {
+    return this.priorEffects.some((e) => e.status !== "failed");
+  }
+  /** Run `effect` at most once per (scope, intent, payload), fenced to this run. */
+  once(intent, payload, effect, options = {}) {
+    const key = effectKey(intent, payload);
+    if (this.fencingToken === null) {
+      return Promise.resolve({ status: "refused", ok: false, key, reason: "busy" });
+    }
+    const self = { runId: this.runId, token: this.fencingToken, leaseTtlMs: this.leaseTtlMs };
+    return this.ro.execute(this.scope, key, intent, self, effect, options);
+  }
+  check(intent, payload) {
+    return this.ro.check({ scope: this.scope, intent, payload });
+  }
+  history() {
+    return this.ro.history(this.scope);
+  }
+  /**
+   * 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() {
+    if (this.fencingToken === null) return Promise.resolve(false);
+    return this.ro.renewRun(this.scope, this.runId, this.fencingToken, this.leaseTtlMs);
+  }
+  /** Mark the run finished. A no-op if a later delivery of the same run has taken over. */
+  end(reason = "completed") {
+    if (this.fencingToken === null) return Promise.resolve();
+    return this.ro.endRun(this.scope, this.runId, this.fencingToken, reason);
+  }
+};
+function createReplyOnce(options) {
+  return new ReplyOnce(options);
+}
+function assertScope(scope) {
+  if (typeof scope !== "string" || scope.length === 0 || scope.length > 512) {
+    throw new TypeError("replyonce: scope must be a non-empty string of at most 512 characters");
+  }
+}
+function safeClassify(classify, err) {
+  try {
+    return classify(err) === "not_applied" ? "not_applied" : "ambiguous";
+  } catch {
+    return "ambiguous";
+  }
+}
+function describeError(err) {
+  const text = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+  return text.slice(0, 500);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/stores/memory.ts
+var MemoryStore = class {
+  data = /* @__PURE__ */ new Map();
+  async transact(scope, fn) {
+    const raw = this.data.get(scope);
+    const { next, result } = fn(raw === void 0 ? null : JSON.parse(raw));
+    if (next) this.data.set(scope, JSON.stringify(next));
+    return result;
+  }
+  async read(scope) {
+    const raw = this.data.get(scope);
+    return raw === void 0 ? null : JSON.parse(raw);
+  }
+  /** Number of scopes held. */
+  get size() {
+    return this.data.size;
+  }
+  clear() {
+    this.data.clear();
+  }
+};
+
+// src/demo.ts
+var TimeoutError = class extends Error {
+  constructor() {
+    super("provider timed out");
+    this.name = "TimeoutError";
+  }
+};
+function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = a;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var hang = () => new Promise(() => {
+});
+function answered(world, conv) {
+  const s = /* @__PURE__ */ new Set();
+  for (const r of world.sent) if (r.conv === conv) r.answers.forEach((a) => s.add(a));
+  return s;
+}
+async function providerSend(world, reply) {
+  await sleep2(1 + world.rand() * 4);
+  const roll = world.rand();
+  if (roll < 0.15) {
+    world.sent.push(reply);
+    world.faults.timeoutAfterSend = (world.faults.timeoutAfterSend ?? 0) + 1;
+    throw new TimeoutError();
+  }
+  if (roll < 0.25) {
+    world.faults.timeoutBeforeSend = (world.faults.timeoutBeforeSend ?? 0) + 1;
+    throw new TimeoutError();
+  }
+  world.sent.push(reply);
+}
+function naiveAgent(world) {
+  return async (job, crash) => {
+    await sleep2(2 + world.rand() * 10);
+    const todo = job.inboundAtEnqueue.filter((m) => !job.answeredAtEnqueue.has(m));
+    if (todo.length === 0) return;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        await providerSend(world, { conv: job.conv, answers: todo, idem: null });
+        if (crash) await hang();
+        return;
+      } catch {
+      }
+    }
+  };
+}
+function guardedAgent(world, store) {
+  const ro = createReplyOnce({
+    store,
+    pendingTtlMs: 2e3,
+    maxAttempts: 6,
+    leaseTtlMs: 5e3,
+    // A settle after the claim was given up on means pendingTtlMs was too short for this host.
+    onEvent: (e) => {
+      if (e.type === "late_settle") world.faults.lateSettle = (world.faults.lateSettle ?? 0) + 1;
+    },
+    // Look the message up on the provider by the idempotency key it was sent with.
+    reconcile: async (entry) => {
+      const idem = providerIdempotencyKey(entry.scope, entry.key);
+      return world.sent.some((r) => r.idem === idem) ? { outcome: "committed" } : { outcome: "not_applied" };
+    }
+  });
+  return async (job, crash) => {
+    await sleep2(2 + world.rand() * 10);
+    const run = await ro.begin(job.conv, { runId: job.id, contextAt: job.contextAt });
+    if (!run.canWrite) return;
+    let inbound = job.inboundAtEnqueue;
+    let done = job.answeredAtEnqueue;
+    const giveUpAt = Date.now() + 15e3;
+    while (Date.now() < giveUpAt) {
+      const todo = inbound.filter((m) => !done.has(m));
+      if (todo.length === 0) break;
+      const identity = { answers: todo };
+      const res = await run.once(
+        "reply",
+        identity,
+        async (ctx) => {
+          await providerSend(world, { conv: job.conv, answers: todo, idem: ctx.idempotencyKey });
+          if (crash) await hang();
+        },
+        { summary: `reply to ${todo.join(", ")}`, wait: { timeoutMs: 5e3, intervalMs: 10 } }
+      );
+      if (res.ok) break;
+      if (res.status === "refused" && res.reason === "conversation_changed") {
+        await sleep2(res.conflicts?.some((c) => c.status === "pending") ? 25 : 5);
+        inbound = world.inbound.get(job.conv) ?? [];
+        done = answered(world, job.conv);
+        continue;
+      }
+      if (res.status === "refused") break;
+      await sleep2(10);
+    }
+    await run.end();
+  };
+}
+async function simulate(conversations, seed, makeAgent) {
+  const world = { inbound: /* @__PURE__ */ new Map(), sent: [], faults: {}, rand: rng(seed) };
+  const agent = makeAgent(world);
+  const tasks = [];
+  let jobSeq = 0;
+  const deliver = (job) => {
+    const r = world.rand();
+    const crash = r < 0.1;
+    const duplicate = r >= 0.1 && r < 0.25;
+    if (crash) {
+      world.faults.workerCrash = (world.faults.workerCrash ?? 0) + 1;
+      void agent(job, true);
+      tasks.push(sleep2(60 + world.rand() * 60).then(() => agent(job, false)));
+      return;
+    }
+    tasks.push(agent(job, false));
+    if (duplicate) {
+      world.faults.duplicateDelivery = (world.faults.duplicateDelivery ?? 0) + 1;
+      tasks.push(sleep2(world.rand() * 8).then(() => agent(job, false)));
+    }
+  };
+  const enqueue = (conv, msgId) => {
+    const list = world.inbound.get(conv) ?? [];
+    list.push(msgId);
+    world.inbound.set(conv, list);
+    deliver({
+      id: `job-${++jobSeq}`,
+      conv,
+      msgId,
+      answeredAtEnqueue: answered(world, conv),
+      inboundAtEnqueue: [...list],
+      contextAt: Date.now()
+    });
+  };
+  const ns = Math.random().toString(36).slice(2, 10);
+  for (let i = 0; i < conversations; i++) {
+    const conv = `demo-${ns}-conversation-${i}`;
+    enqueue(conv, `${conv}/m1`);
+    if (world.rand() < 0.25) {
+      world.faults.customerBurst = (world.faults.customerBurst ?? 0) + 1;
+      tasks.push(sleep2(1 + world.rand() * 12).then(() => enqueue(conv, `${conv}/m2`)));
+    }
+  }
+  for (let n = 0; n !== tasks.length; ) {
+    n = tasks.length;
+    await Promise.all(tasks.slice());
+  }
+  await sleep2(50);
+  let duplicateAnswers = 0;
+  let unanswered = 0;
+  let customerMessages = 0;
+  for (const [conv, msgs] of world.inbound) {
+    for (const m of msgs) {
+      customerMessages++;
+      const count = world.sent.filter((r) => r.conv === conv && r.answers.includes(m)).length;
+      if (count === 0) unanswered++;
+      if (count > 1) duplicateAnswers += count - 1;
+    }
+  }
+  return {
+    conversations,
+    customerMessages,
+    repliesSent: world.sent.length,
+    duplicateAnswers,
+    unanswered,
+    faults: world.faults
+  };
+}
+async function runDemo(options = {}) {
+  const conversations = options.conversations ?? 100;
+  const seed = options.seed ?? 7;
+  const { faults: withoutFaults, ...without } = await simulate(conversations, seed, naiveAgent);
+  const store = options.store ?? new MemoryStore();
+  const { faults: withFaults, ...guarded } = await simulate(conversations, seed, (w) => guardedAgent(w, store));
+  return { without, with: guarded, faults: { without: withoutFaults, with: withFaults } };
+}
+function formatReport(r) {
+  const row = (label, s) => `  ${label.padEnd(16)} ${String(s.customerMessages).padStart(8)} ${String(s.repliesSent).padStart(7)} ${String(s.duplicateAnswers).padStart(10)} ${String(s.unanswered).padStart(11)}`;
+  const faults = (f) => Object.entries(f).map(([k, v]) => `${k}=${v}`).join(", ");
+  return [
+    `replyonce demo: ${r.without.conversations} simulated support conversations under injected faults`,
+    `  without: ${faults(r.faults.without)}`,
+    `  with:    ${faults(r.faults.with)}`,
+    "",
+    `  ${"".padEnd(16)} ${"messages".padStart(8)} ${"replies".padStart(7)} ${"duplicates".padStart(10)} ${"unanswered".padStart(11)}`,
+    row("without", r.without),
+    row("with replyonce", r.with),
+    "",
+    r.with.duplicateAnswers === 0 ? "  No customer message was answered twice with replyonce." : r.faults.with.lateSettle ? "  Duplicates happened after this host stalled past pendingTtlMs (see lateSettle): the limit described in the README." : "  Duplicates remained with replyonce. Please report this: https://github.com/shmindmaster/replyonce/issues"
+  ].join("\n");
+}
+
+// src/cli.ts
+var HELP = `Usage: replyonce demo [--conversations N] [--seed N]
+
+Runs a chaos simulation of a support agent with and without replyonce and prints
+how many customer messages were answered twice.`;
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command !== "demo") {
+    console.log(HELP);
+    return command === void 0 || command === "--help" || command === "-h" ? 0 : 1;
+  }
+  const opt = (name, fallback, min) => {
+    const i = rest.indexOf(`--${name}`);
+    const v = i >= 0 ? Number(rest[i + 1]) : fallback;
+    if (!Number.isInteger(v) || v < min) throw new Error(`--${name} must be an integer >= ${min}`);
+    return v;
+  };
+  const report = await runDemo({ conversations: opt("conversations", 100, 1), seed: opt("seed", 7, 0) });
+  console.log(formatReport(report));
+  return report.with.duplicateAnswers === 0 ? 0 : 2;
+}
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+);