@blokjs/runner 0.4.0 → 0.6.0

package/dist/scheduling/DebounceCoordinator.js

@@ -1,6 +1,40 @@
+/**
+ * Tier 2 #7 — debounce coordinator. Tier C #1 — cross-process awareness.
+ *
+ * Coalesces rapid same-key triggers into a single delayed run. Modes:
+ *
+ * - `"trailing"` (default): each ping resets a timer; the run fires
+ *   after `delayMs` of silence. Latest payload wins (within a single
+ *   owning process). `maxDelayMs` bounds tail latency — even with
+ *   continuous pings, the run fires after `maxDelayMs` from the FIRST
+ *   ping.
+ * - `"leading"`: the first ping fires immediately. Subsequent pings
+ *   within `delayMs` are dropped. Window resets after `delayMs` of
+ *   silence.
+ *
+ * Process-wide singleton. **Default**: in-memory only — fast,
+ * synchronous internally. **Cross-process mode (Tier C #1)**: install a
+ * `DebounceBackend` via `setBackend()` and the coordinator routes
+ * register/cancel through the backend with the same outcome surface,
+ * keeping a local timer + closure for the OWNING process. The
+ * `register()` API is async — callers must `await` it.
+ *
+ * Latest-payload semantics in cross-process mode: **owner-local**.
+ * Pings from a non-owning process bump pingCount + push scheduledAt in
+ * the shared doc but do NOT contribute their payload — only the
+ * owning process's captured `onFire` closure fires. Cross-process
+ * latest-payload-wins is deferred (would require persisting each
+ * ping's payload to the shared doc; tracked in BACKLOG).
+ */
+import { randomUUID } from "node:crypto";
+const DEFAULT_OWNER_LEASE_MS = 60_000;
 export class DebounceCoordinator {
     static instance = null;
     states = new Map();
+    backend = null;
+    /** Process identity for cross-process owner-lease attribution. Stable for the lifetime of the singleton. */
+    processId = randomUUID();
+    ownerLeaseMs = DEFAULT_OWNER_LEASE_MS;
     static getInstance() {
         if (!DebounceCoordinator.instance) {
             DebounceCoordinator.instance = new DebounceCoordinator();
@@ -12,10 +46,41 @@ export class DebounceCoordinator {
         DebounceCoordinator.instance?.clear();
         DebounceCoordinator.instance = null;
     }
+    /**
+     * Install a cross-process backend. Set via `HttpTrigger.listen()` /
+     * `WorkerTrigger.listen()` when `BLOK_DEBOUNCE_BACKEND` is configured.
+     * Pass `null` to revert to the in-memory fast path.
+     */
+    setBackend(backend) {
+        this.backend = backend;
+    }
+    getBackend() {
+        return this.backend;
+    }
+    /**
+     * Override the owner-lease duration. Used by `HttpTrigger.listen()` /
+     * `WorkerTrigger.listen()` to apply `BLOK_DEBOUNCE_OWNER_LEASE_MS`.
+     */
+    setOwnerLeaseMs(ms) {
+        if (Number.isFinite(ms) && ms > 0) {
+            this.ownerLeaseMs = ms;
+        }
+    }
     bucket(workflowName, debounceKey) {
         return `${workflowName}\x1f${debounceKey}`;
     }
-    register(opts) {
+    async register(opts) {
+        if (this.backend) {
+            return this.registerCrossProcess(opts);
+        }
+        return this.registerLocal(opts);
+    }
+    /**
+     * In-memory fast path — preserved exactly from the v1 single-process
+     * implementation. Synchronous internally; the outer signature is
+     * async so callers don't need to discriminate.
+     */
+    registerLocal(opts) {
         const now = opts.__now ?? Date.now();
         const bucketKey = this.bucket(opts.workflowName, opts.debounceKey);
         const existing = this.states.get(bucketKey);
@@ -66,7 +131,7 @@ export class DebounceCoordinator {
             const naiveDeadline = now + opts.delayMs;
             const dispatchAt = existing.maxDelayDeadline !== undefined ? Math.min(naiveDeadline, existing.maxDelayDeadline) : naiveDeadline;
             const wait = Math.max(0, dispatchAt - now);
-            existing.timer = setTimeout(() => this.fireTrailing(bucketKey), wait);
+            existing.timer = setTimeout(() => this.fireTrailingLocal(bucketKey), wait);
             return {
                 outcome: "coalesce",
                 activeRunId: existing.activeRunId,
@@ -90,7 +155,7 @@ export class DebounceCoordinator {
         const naiveDeadline = now + opts.delayMs;
         const dispatchAt = state.maxDelayDeadline !== undefined ? Math.min(naiveDeadline, state.maxDelayDeadline) : naiveDeadline;
         const wait = Math.max(0, dispatchAt - now);
-        state.timer = setTimeout(() => this.fireTrailing(bucketKey), wait);
+        state.timer = setTimeout(() => this.fireTrailingLocal(bucketKey), wait);
         this.states.set(bucketKey, state);
         return {
             outcome: "schedule-trailing",
@@ -99,7 +164,7 @@ export class DebounceCoordinator {
             pingCount: 1,
         };
     }
-    fireTrailing(bucketKey) {
+    fireTrailingLocal(bucketKey) {
         const state = this.states.get(bucketKey);
         if (!state)
             return;
@@ -110,26 +175,182 @@ export class DebounceCoordinator {
             });
         }
     }
+    /**
+     * Cross-process path — delegates ownership to the backend and uses
+     * a local timer + closure for the OWNING process.
+     *
+     * Three outcomes from the backend:
+     *  - `owner-new`: this process is the new owner. Start a local timer
+     *    + closure; on fire, atomically finalize via the backend.
+     *  - `owner-extend`: this process is already the owner. Cancel +
+     *    restart the local timer at the new scheduledAt; refresh closure.
+     *  - `coalesce`: another process owns the window. Just return.
+     *
+     * Leading mode: `owner-new` translates to `fire-immediate` (caller
+     * fires synchronously); `owner-extend`/`coalesce` translate to
+     * `coalesce`.
+     */
+    async registerCrossProcess(opts) {
+        const backend = this.backend;
+        if (!backend)
+            return this.registerLocal(opts);
+        const now = opts.__now ?? Date.now();
+        const bucketKey = this.bucket(opts.workflowName, opts.debounceKey);
+        let res;
+        try {
+            res = await backend.registerPing({
+                workflowName: opts.workflowName,
+                debounceKey: opts.debounceKey,
+                mode: opts.mode,
+                delayMs: opts.delayMs,
+                maxDelayMs: opts.maxDelayMs,
+                runId: opts.runId,
+                processId: this.processId,
+                ownerLeaseMs: this.ownerLeaseMs,
+                now,
+            });
+        }
+        catch (err) {
+            // Fail-open — fall back to local in-memory window. Same posture
+            // as the concurrency-backend fail-fast path (deny-on-error) but
+            // debounce isn't a safety gate — better to admit the ping than
+            // drop it on a transient broker outage.
+            console.warn(`[blok][scheduling] debounce backend registerPing failed for ${bucketKey}: ${err instanceof Error ? err.message : String(err)}; falling back to in-memory window`);
+            return this.registerLocal(opts);
+        }
+        // === Leading mode ===
+        if (opts.mode === "leading") {
+            if (res.outcome === "owner-new") {
+                // Caller fires synchronously; we don't keep a local timer for
+                // leading mode (the backend's owner-lease IS the window).
+                return { outcome: "fire-immediate", activeRunId: opts.runId, pingCount: res.pingCount };
+            }
+            return { outcome: "coalesce", activeRunId: res.activeRunId, pingCount: res.pingCount };
+        }
+        // === Trailing mode ===
+        if (res.outcome === "owner-new") {
+            // New trailing window owned by this process. Capture the closure +
+            // start a local timer to fire at backend-decided scheduledAt.
+            this.installOwnerTimer(bucketKey, opts, res.scheduledAt, now);
+            return {
+                outcome: "schedule-trailing",
+                activeRunId: opts.runId,
+                scheduledAt: res.scheduledAt,
+                pingCount: res.pingCount,
+            };
+        }
+        if (res.outcome === "owner-extend") {
+            // We still own. Replace the captured closure (latest payload
+            // wins within this process) + reschedule.
+            this.installOwnerTimer(bucketKey, opts, res.scheduledAt, now);
+            return {
+                outcome: "coalesce",
+                activeRunId: res.activeRunId,
+                scheduledAt: res.scheduledAt,
+                pingCount: res.pingCount,
+            };
+        }
+        // outcome === "coalesce" — another process owns. Do not install a
+        // local timer; the owning process drives the fire.
+        return {
+            outcome: "coalesce",
+            activeRunId: res.activeRunId,
+            scheduledAt: res.scheduledAt,
+            pingCount: res.pingCount,
+        };
+    }
+    installOwnerTimer(bucketKey, opts, scheduledAt, now) {
+        const existing = this.states.get(bucketKey);
+        if (existing?.timer)
+            clearTimeout(existing.timer);
+        const state = {
+            bucketKey,
+            mode: opts.mode,
+            delayMs: opts.delayMs,
+            maxDelayMs: opts.maxDelayMs,
+            firstPingAt: existing?.firstPingAt ?? now,
+            lastPingAt: now,
+            pingCount: (existing?.pingCount ?? 0) + 1,
+            activeRunId: opts.runId,
+            maxDelayDeadline: existing?.maxDelayDeadline ?? (opts.maxDelayMs !== undefined ? now + opts.maxDelayMs : undefined),
+            onFire: opts.onFire,
+        };
+        const wait = Math.max(0, scheduledAt - now);
+        state.timer = setTimeout(() => {
+            void this.fireTrailingCrossProcess(bucketKey, opts.workflowName, opts.debounceKey, opts.runId);
+        }, wait);
+        this.states.set(bucketKey, state);
+    }
+    async fireTrailingCrossProcess(bucketKey, workflowName, debounceKey, runId) {
+        const backend = this.backend;
+        const state = this.states.get(bucketKey);
+        if (!backend || !state)
+            return;
+        const now = Date.now();
+        let result;
+        try {
+            result = await backend.finalize(workflowName, debounceKey, runId, now);
+        }
+        catch (err) {
+            // Treat as abandoned — owner-lease will eventually expire and
+            // another process can take over. Don't fire to avoid duplicate
+            // dispatch.
+            console.warn(`[blok][scheduling] debounce backend finalize failed for ${bucketKey}: ${err instanceof Error ? err.message : String(err)}; abandoning local owner state`);
+            this.states.delete(bucketKey);
+            return;
+        }
+        if (result.finalize === "fire") {
+            this.states.delete(bucketKey);
+            if (state.onFire) {
+                void state.onFire().catch((err) => {
+                    console.error(`[blok][scheduling] DebounceCoordinator cross-process fire failed for key ${bucketKey}:`, err instanceof Error ? err.stack || err.message : err);
+                });
+            }
+            return;
+        }
+        if (result.finalize === "reschedule") {
+            // Coalesce pings from other processes pushed scheduledAt forward.
+            // Reschedule local timer; closure stays.
+            if (state.timer)
+                clearTimeout(state.timer);
+            const wait = Math.max(0, result.scheduledAt - now);
+            state.timer = setTimeout(() => {
+                void this.fireTrailingCrossProcess(bucketKey, workflowName, debounceKey, runId);
+            }, wait);
+            return;
+        }
+        // finalize === "abandoned" — lease expired; another process took
+        // over. Drop the closure silently.
+        this.states.delete(bucketKey);
+    }
     /** Cancel an active window without firing. Returns true if cancelled. */
-    cancel(workflowName, debounceKey) {
+    async cancel(workflowName, debounceKey) {
         const bucketKey = this.bucket(workflowName, debounceKey);
         const state = this.states.get(bucketKey);
-        if (!state)
-            return false;
-        if (state.timer)
+        if (state?.timer)
             clearTimeout(state.timer);
-        this.states.delete(bucketKey);
-        return true;
+        const hadLocal = this.states.delete(bucketKey);
+        if (this.backend) {
+            try {
+                const cancelled = await this.backend.cancel(workflowName, debounceKey);
+                return cancelled || hadLocal;
+            }
+            catch (err) {
+                console.warn(`[blok][scheduling] debounce backend cancel failed for ${bucketKey}: ${err instanceof Error ? err.message : String(err)}`);
+                return hadLocal;
+            }
+        }
+        return hadLocal;
     }
-    /** Number of active debounce windows. Tests + observability. */
+    /** Number of active LOCAL debounce windows. Tests + observability. Excludes cross-process windows owned by other processes. */
     size() {
         return this.states.size;
     }
-    /** True if a window is open for `(workflow, key)`. */
+    /** True if THIS process has a local window for `(workflow, key)`. Excludes windows owned by other processes. */
     has(workflowName, debounceKey) {
         return this.states.has(this.bucket(workflowName, debounceKey));
     }
-    /** Cancel everything without firing. */
+    /** Cancel everything without firing. Local state only — cross-process buckets fall back to lease-expiry. */
     clear() {
         for (const state of this.states.values()) {
             if (state.timer)

package/dist/scheduling/DebounceCoordinator.js.map

@@ -1 +1 @@
-{"version":3,"file":"DebounceCoordinator.js","sourceRoot":"","sources":["../../src/scheduling/DebounceCoordinator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DebounceCoordinator.js","sourceRoot":"","sources":["../../src/scheduling/DebounceCoordinator.ts"],"names":[],"mappings":"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"}

package/dist/scheduling/DeferredRunScheduler.d.ts

@@ -24,6 +24,18 @@ export interface DeferredScheduleOptions {
 export declare class DeferredRunScheduler {
     private static instance;
     private entries;
+    /**
+     * Tier C #2 — stable per-process identity used for claim ownership.
+     * Generated once per scheduler instance; surviving across resets is
+     * intentional (a "process restart" in production gets a fresh
+     * scheduler singleton and therefore a fresh processId — peers' stale
+     * claims expire after the lease).
+     */
+    private readonly processId;
+    /** Tier C #2 — running heartbeat timer; one per scheduler instance. */
+    private heartbeatTimer;
+    /** Tier C #2 — count of persisted entries currently registered. Heartbeat is only active when > 0. */
+    private persistedEntryCount;
     static getInstance(): DeferredRunScheduler;
     /** Test-only — reset the singleton. Cancels all pending timers. */
     static resetInstance(): void;
@@ -65,4 +77,20 @@ export declare class DeferredRunScheduler {
     drainAll(): Promise<void>;
     /** Cancel everything without dispatching. */
     clear(): void;
+    /**
+     * Stable per-process identity used for the claim API. Trigger boot
+     * recovery passes this to `RunStore.claimDispatches(processId, …)`
+     * so peers can recognize each other's claims.
+     */
+    getProcessId(): string;
+    private maybeStartHeartbeat;
+    private maybeStopHeartbeat;
+    private runHeartbeat;
 }
+/**
+ * Public helper that returns the operator-configured claim-lease in
+ * ms. Used by `HttpTrigger.recoverDispatches()` to pass the lease to
+ * `RunStore.claimDispatches()`. Centralized so the env var name is
+ * defined in one place.
+ */
+export declare function getSchedulerClaimLeaseMs(): number;

package/dist/scheduling/DeferredRunScheduler.js

@@ -1,15 +1,32 @@
 /**
  * Tier 2 #5 — in-memory scheduler for deferred workflow runs. Tier 2
  * #5+#7 follow-up adds optional sqlite-backed durability via the
- * {@link DeferredScheduleOptions.persist} parameter.
+ * {@link DeferredScheduleOptions.persist} parameter. Tier C #2 adds
+ * cross-process claim heartbeats so multi-process deployments sharing
+ * a PG store don't double-fire the same dispatch.
  *
  * Process-wide singleton; obtained via {@link DeferredRunScheduler.getInstance}.
  * Reset between tests via {@link DeferredRunScheduler.resetInstance}.
  */
+import { randomUUID } from "node:crypto";
 import { RunTracker } from "../tracing/RunTracker";
+const DEFAULT_CLAIM_LEASE_MS = 60_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 20_000;
 export class DeferredRunScheduler {
     static instance = null;
     entries = new Map();
+    /**
+     * Tier C #2 — stable per-process identity used for claim ownership.
+     * Generated once per scheduler instance; surviving across resets is
+     * intentional (a "process restart" in production gets a fresh
+     * scheduler singleton and therefore a fresh processId — peers' stale
+     * claims expire after the lease).
+     */
+    processId = randomUUID();
+    /** Tier C #2 — running heartbeat timer; one per scheduler instance. */
+    heartbeatTimer = null;
+    /** Tier C #2 — count of persisted entries currently registered. Heartbeat is only active when > 0. */
+    persistedEntryCount = 0;
     static getInstance() {
         if (!DeferredRunScheduler.instance) {
             DeferredRunScheduler.instance = new DeferredRunScheduler();
@@ -69,8 +86,11 @@ export class DeferredRunScheduler {
             this.entries.delete(runId);
             // Best-effort delete the persisted row before invoking dispatchFn —
             // dispatch will write the run's terminal status separately.
-            if (persisted)
+            if (persisted) {
                 this.deletePersistedRow(runId);
+                this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+                this.maybeStopHeartbeat();
+            }
             void dispatchFn().catch((err) => {
                 console.error(`[blok][scheduling] DeferredRunScheduler dispatch failed for run ${runId}:`, err instanceof Error ? err.stack || err.message : err);
             });
@@ -78,7 +98,20 @@ export class DeferredRunScheduler {
         // `Node` will keep the event loop alive for pending timers — that's
         // the desired behavior for delayed runs in long-running services.
         // `unref()` would be wrong here.
+        const wasPersisted = existing?.persisted === true;
         this.entries.set(runId, { runId, dispatchAt, timer, dispatchFn, persisted });
+        // Tier C #2 — track persisted entry count + manage heartbeat
+        // lifecycle. The heartbeat only runs while we have ≥1 persisted
+        // entry (otherwise there's nothing to keep claimed). Replace doesn't
+        // change the count.
+        if (persisted && !wasPersisted) {
+            this.persistedEntryCount++;
+            this.maybeStartHeartbeat();
+        }
+        else if (!persisted && wasPersisted) {
+            this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+            this.maybeStopHeartbeat();
+        }
     }
     /**
      * Cancel a pending dispatch. Returns true if the entry existed and
@@ -99,8 +132,11 @@ export class DeferredRunScheduler {
         }
         clearTimeout(entry.timer);
         this.entries.delete(runId);
-        if (entry.persisted)
+        if (entry.persisted) {
             this.deletePersistedRow(runId);
+            this.persistedEntryCount = Math.max(0, this.persistedEntryCount - 1);
+            this.maybeStopHeartbeat();
+        }
         return true;
     }
     deletePersistedRow(runId) {
@@ -149,6 +185,72 @@ export class DeferredRunScheduler {
         for (const entry of this.entries.values())
             clearTimeout(entry.timer);
         this.entries.clear();
+        this.persistedEntryCount = 0;
+        this.maybeStopHeartbeat();
     }
+    // === Tier C #2 — cross-process claim heartbeat ===
+    /**
+     * Stable per-process identity used for the claim API. Trigger boot
+     * recovery passes this to `RunStore.claimDispatches(processId, …)`
+     * so peers can recognize each other's claims.
+     */
+    getProcessId() {
+        return this.processId;
+    }
+    maybeStartHeartbeat() {
+        if (this.heartbeatTimer !== null)
+            return;
+        if (this.persistedEntryCount === 0)
+            return;
+        if (process.env.BLOK_SCHEDULER_CLAIM_DISABLED === "1")
+            return;
+        const intervalMs = readEnvInt("BLOK_SCHEDULER_HEARTBEAT_INTERVAL_MS", DEFAULT_HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer = setInterval(() => {
+            this.runHeartbeat();
+        }, intervalMs);
+        // Don't keep the event loop alive solely for the heartbeat —
+        // the persisted entries' timers already do that. `unref()`
+        // avoids blocking shutdown when no entries are pending.
+        this.heartbeatTimer.unref?.();
+    }
+    maybeStopHeartbeat() {
+        if (this.heartbeatTimer === null)
+            return;
+        if (this.persistedEntryCount > 0)
+            return;
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    runHeartbeat() {
+        const tracker = RunTracker.getInstance();
+        if (!tracker.active)
+            return;
+        try {
+            tracker.getStore().heartbeatClaims(this.processId, Date.now());
+        }
+        catch (err) {
+            // Heartbeat failures are non-fatal — the lease will expire if
+            // they continue, and a peer will take over. Log + continue.
+            console.warn(`[blok][scheduling] heartbeatClaims failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function readEnvInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw && /^\d+$/.test(raw)) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return fallback;
+}
+/**
+ * Public helper that returns the operator-configured claim-lease in
+ * ms. Used by `HttpTrigger.recoverDispatches()` to pass the lease to
+ * `RunStore.claimDispatches()`. Centralized so the env var name is
+ * defined in one place.
+ */
+export function getSchedulerClaimLeaseMs() {
+    return readEnvInt("BLOK_SCHEDULER_CLAIM_LEASE_MS", DEFAULT_CLAIM_LEASE_MS);
 }
 //# sourceMappingURL=DeferredRunScheduler.js.map

package/dist/scheduling/DeferredRunScheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredRunScheduler.js","sourceRoot":"","sources":["../../src/scheduling/DeferredRunScheduler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DeferredRunScheduler.js","sourceRoot":"","sources":["../../src/scheduling/DeferredRunScheduler.ts"],"names":[],"mappings":"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"}

package/dist/scheduling/NatsKvDebounceBackend.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tier C #1 · NATS KV-backed debounce backend.
+ *
+ * Coordinates per-(workflow, debounceKey) window state across processes
+ * via a single NATS JetStream KV value per bucket with revision-based
+ * compare-and-swap (OCC). Mirrors the storage model of
+ * `NatsKvConcurrencyBackend` but with a different document shape (one
+ * window per bucket, not a leases array).
+ *
+ * Acquire / extend / coalesce: a bounded CAS loop (10 retries) that
+ * reads → decides ownership → atomically writes. On retry exhaustion,
+ * fall back to admitting the ping as a `coalesce` against the current
+ * owner — debounce is not a safety gate, so we'd rather over-coalesce
+ * than drop pings on a contention spike.
+ *
+ * Finalize: same OCC pattern. The owning process atomically reads the
+ * doc, confirms it still owns AND `now >= scheduledAt`, and atomically
+ * deletes. On lease handoff, the owner discovers it no longer owns and
+ * abandons silently.
+ *
+ * **Owner-local payload**: this backend tracks `pingCount`,
+ * `lastPingAt`, and `scheduledAt` only — not the payload. Cross-process
+ * latest-payload-wins is a deferred follow-up.
+ */
+import type { DebounceBackend, DebounceFinalizeResult, DebounceRegisterBackendOpts, DebounceRegisterBackendResult } from "./DebounceBackend";
+export interface NatsKvDebounceConfig {
+    servers: string[];
+    token?: string;
+    user?: string;
+    pass?: string;
+    bucketName: string;
+}
+export declare function readNatsKvDebounceConfigFromEnv(): NatsKvDebounceConfig;
+export declare class NatsKvDebounceBackend implements DebounceBackend {
+    readonly name = "nats-kv";
+    private nc;
+    private kv;
+    private readonly config;
+    private connected;
+    constructor(config?: Partial<NatsKvDebounceConfig>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private bucketKey;
+    private encodeSegment;
+    private requireKv;
+    private computeScheduledAt;
+    registerPing(opts: DebounceRegisterBackendOpts): Promise<DebounceRegisterBackendResult>;
+    finalize(workflowName: string, debounceKey: string, runId: string, now: number): Promise<DebounceFinalizeResult>;
+    cancel(workflowName: string, debounceKey: string): Promise<boolean>;
+    purgeExpired(now: number): Promise<number>;
+    private safeGet;
+    private parseDoc;
+}