@loomwork/event-runtime 0.0.0-stage → 0.1.0

package/dist/leases.js

@@ -0,0 +1,142 @@
+"use strict";
+// ── Durable ownership of a running execution (#380) ───────────────────────────
+//
+// A `running` execution owned by a healthy node is byte-identical, in the log, to one
+// orphaned by a dead one: the difference is a fact about the cluster, not about the
+// execution, so no fold can see it. That is why `recoverAbandoned` demands a predicate — and
+// why a double dispatch today is merely SAFE rather than avoided. Fencing (K9.4) rejects the
+// loser's write; both runs still executed, and both still paid for their effects.
+//
+// A lease is the missing fact: ownership with an expiry, written where both nodes can see it.
+//
+// Deliberately shaped like `TimerStore`: a small store with a polling service above it, no
+// coordination protocol, and nothing required of a deployment that does not want it. Unwired,
+// every path behaves byte-identically (G2).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryLeaseStore = exports.LEASE_STORE_SPI_VERSION = void 0;
+exports.assertTtl = assertTtl;
+exports.assertSteal = assertSteal;
+exports.assertNoBatchSteal = assertNoBatchSteal;
+/**
+ * SPI version for the {@link LeaseStore} contract. Pinned by `runLeaseStoreConformance`.
+ *
+ * 2.0.0 (L28): `expired`'s `now` became optional and MUST default to the store's stamping clock.
+ * MAJOR, not additive: a 1.x store written `expired(now: number)` still type-checks against the
+ * new signature but, handed `undefined`, returns `[]` — recovery silently recovers nothing.
+ *
+ * 2.1.0 (L29): optional `storeNow()` — the store's own clock. Additive: a store without it behaves
+ * exactly as before, and a caller with no `storeNow()` falls back to `Date.now()`.
+ *
+ * 2.2.0 (ADR 0130 D11, heartbeat leases): optional `scope` (who can see this store's leases:
+ * "process" | "host" | "cluster"; absent = unknown, treated as NOT cluster-visible), optional `acquireMany` / `renewMany` (returns the HELD
+ * set) / `releaseMany`, and the `steal` option on `acquire`. Additive: a store without them is
+ * driven through the single-id methods by the caller (correct, just slower). A store that claims
+ * 2.2.0 implements all three batch methods and the steal gate; one that claims 2.1.0 is not asked.
+ */
+exports.LEASE_STORE_SPI_VERSION = "2.2.0";
+/**
+ * Map-backed {@link LeaseStore} — the browser-safe / test reference implementation beside the
+ * durable backends. Behaviour is pinned by `runLeaseStoreConformance`.
+ */
+class InMemoryLeaseStore {
+    scope = "process";
+    leases = new Map();
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+    }
+    async acquire(executionId, owner, ttlMs, now = this.now(), options) {
+        assertTtl(ttlMs);
+        const steal = assertSteal(options);
+        const held = this.leases.get(executionId);
+        // Someone else's, and still alive (unless the caller proved it may take it).
+        if (held !== undefined && held.owner !== owner && held.expiresAt > now && !steal)
+            return null;
+        const lease = { executionId, owner, expiresAt: now + ttlMs };
+        this.leases.set(executionId, lease);
+        return { ...lease };
+    }
+    async acquireMany(executionIds, owner, ttlMs, now = this.now(), options) {
+        assertTtl(ttlMs);
+        assertNoBatchSteal(options);
+        const out = [];
+        for (const id of new Set(executionIds)) {
+            const lease = await this.acquire(id, owner, ttlMs, now);
+            if (lease !== null)
+                out.push(lease);
+        }
+        return out;
+    }
+    async renewMany(executionIds, owner, ttlMs, now = this.now()) {
+        assertTtl(ttlMs);
+        const held = [];
+        for (const id of new Set(executionIds))
+            if (await this.renew(id, owner, ttlMs, now))
+                held.push(id);
+        return held;
+    }
+    async releaseMany(executionIds, owner) {
+        for (const id of new Set(executionIds))
+            await this.release(id, owner);
+    }
+    async renew(executionId, owner, ttlMs, now = this.now()) {
+        assertTtl(ttlMs);
+        const held = this.leases.get(executionId);
+        if (held === undefined || held.owner !== owner)
+            return false;
+        held.expiresAt = now + ttlMs;
+        return true;
+    }
+    async expired(now = this.now(), limit = 100) {
+        return [...this.leases.values()]
+            .filter((l) => l.expiresAt <= now)
+            .sort((a, b) => a.expiresAt - b.expiresAt)
+            .slice(0, limit)
+            .map((l) => ({ ...l }));
+    }
+    async get(executionId) {
+        const held = this.leases.get(executionId);
+        return held !== undefined ? { ...held } : null;
+    }
+    /** The store's own (injectable) clock: the one `expiresAt` is stamped and judged on (SPI 2.1.0). */
+    async storeNow() {
+        return this.now();
+    }
+    async release(executionId, owner) {
+        const held = this.leases.get(executionId);
+        if (held?.owner === owner)
+            this.leases.delete(executionId);
+    }
+    async close() {
+        this.leases.clear();
+    }
+}
+exports.InMemoryLeaseStore = InMemoryLeaseStore;
+/** A zero or negative TTL would make a lease expired on arrival — refuse it at every backend. */
+function assertTtl(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new RangeError(`lease ttlMs must be a positive number of milliseconds, got ${ttlMs}`);
+    }
+}
+/**
+ * The `steal` gate every backend applies BEFORE touching storage: `true` only for a real
+ * {@link StealProof}; `undefined` options or no `steal` is `false`; anything else THROWS
+ * `TypeError` (a flag is never a proof).
+ */
+function assertSteal(options) {
+    const steal = options?.steal;
+    if (steal === undefined)
+        return false;
+    const fence = steal?.fence;
+    if (typeof fence !== "number" || !Number.isSafeInteger(fence) || fence < 1) {
+        throw new TypeError("lease steal requires a conditional-fence proof: { steal: { fence: <positive integer> } }");
+    }
+    return true;
+}
+/** `acquireMany` takes no `steal`: a fence belongs to one execution. THROWS `TypeError`, changing nothing. */
+function assertNoBatchSteal(options) {
+    if (options?.steal !== undefined) {
+        throw new TypeError("acquireMany does not accept `steal`: a fence belongs to one execution; steal through acquire()");
+    }
+}
+//# sourceMappingURL=leases.js.map

package/dist/leases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leases.js","sourceRoot":"","sources":["../src/leases.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,EAAE;AACF,sFAAsF;AACtF,oFAAoF;AACpF,6FAA6F;AAC7F,6FAA6F;AAC7F,kFAAkF;AAClF,EAAE;AACF,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,8FAA8F;AAC9F,4CAA4C;;;AAoR5C,8BAIC;AAOD,kCAUC;AAGD,gDAMC;AAhTD;;;;;;;;;;;;;;;GAeG;AACU,QAAA,uBAAuB,GAAG,OAAO,CAAC;AAwJ/C;;;GAGG;AACH,MAAa,kBAAkB;IACpB,KAAK,GAAG,SAAkB,CAAC;IACnB,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAClC,GAAG,CAAe;IAEnC,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,OAAO,CACX,WAAmB,EACnB,KAAa,EACb,KAAa,EACb,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAChB,OAAwB;QAExB,SAAS,CAAC,KAAK,CAAC,CAAC;QACjB,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,6EAA6E;QAC7E,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,IAAI,CAAC,SAAS,GAAG,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAC9F,MAAM,KAAK,GAAU,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,GAAG,KAAK,EAAE,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACpC,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,WAAW,CACf,YAA+B,EAC/B,KAAa,EACb,KAAa,EACb,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAChB,OAAwB;QAExB,SAAS,CAAC,KAAK,CAAC,CAAC;QACjB,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAY,EAAE,CAAC;QACxB,KAAK,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YACxD,IAAI,KAAK,KAAK,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,SAAS,CACb,YAA+B,EAC/B,KAAa,EACb,KAAa,EACb,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAEhB,SAAS,CAAC,KAAK,CAAC,CAAC;QACjB,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC;YACpC,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,YAA+B,EAAE,KAAa;QAC9D,KAAK,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,KAAK,CACT,WAAmB,EACnB,KAAa,EACb,KAAa,EACb,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAEhB,SAAS,CAAC,KAAK,CAAC,CAAC;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;QAC7D,IAAI,CAAC,SAAS,GAAG,GAAG,GAAG,KAAK,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,GAAG,GAAG;QACzC,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;aACjC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;aACzC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;aACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAAmB;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IAED,oGAAoG;IACpG,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,KAAa;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,IAAI,EAAE,KAAK,KAAK,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF;AAnGD,gDAmGC;AAED,iGAAiG;AACjG,SAAgB,SAAS,CAAC,KAAa;IACrC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,8DAA8D,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,OAAmC;IAC7D,MAAM,KAAK,GAAG,OAAO,EAAE,KAAgB,CAAC;IACxC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAI,KAAoC,EAAE,KAAK,CAAC;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,SAAS,CACjB,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8GAA8G;AAC9G,SAAgB,kBAAkB,CAAC,OAAmC;IACpE,IAAK,OAAO,EAAE,KAAiB,KAAK,SAAS,EAAE,CAAC;QAC9C,MAAM,IAAI,SAAS,CACjB,gGAAgG,CACjG,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/payloadShredded.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The realm-safe brand of the erasure outcome (ADR 0039, amendment 2026-10-17 (c)). A crypto-shredded
+ * payload is recognised by THIS symbol, never by the error's `name` alone: any store decorator, third
+ * party store or app code can throw an `Error` that merely NAMES itself `PayloadShreddedError`, and on
+ * the authorization path "proven erasure" means "unknown owner", which `unknownOwner: "allow"` admits.
+ *
+ * `Symbol.for` (the global registry) makes the brand survive duplicated package copies (dual CJS/ESM
+ * builds, two installs), where `instanceof` does not. A store that cannot extend the crypto plugin's
+ * class sets the brand on its own error with {@link brandPayloadShredded}.
+ */
+export declare const PAYLOAD_SHREDDED_BRAND: unique symbol;
+/**
+ * Mark `err` as the erasure outcome (non-enumerable, so serialization and logging are unchanged) and
+ * return it. Idempotent. The error's `name` and message are untouched.
+ *
+ * Brand BEFORE freezing: a frozen or otherwise non-extensible object cannot take the brand, and
+ * throwing here would replace the erasure with a TypeError. For such an object this returns a branded
+ * WRAPPER instead (a new `Error` with the same name, message, own fields and stack, `cause` = the
+ * original), so the erasure is still recognised.
+ */
+export declare function brandPayloadShredded<T extends object>(err: T): T;
+/**
+ * True when `err` carries the {@link PAYLOAD_SHREDDED_BRAND} as an OWN property (an inherited brand,
+ * e.g. from a shared prototype, does not count). The ONE definition every consumer uses.
+ * A plain object or `Error` that only has `name === "PayloadShreddedError"` is NOT shredded, and a
+ * value that crossed a process boundary (JSON) has lost the brand: such a boundary must re-establish
+ * trust explicitly (e.g. by checking the log's own `PAYLOAD_SHREDDED` tombstone).
+ */
+export declare function isPayloadShredded(err: unknown): boolean;
+//# sourceMappingURL=payloadShredded.d.ts.map

package/dist/payloadShredded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadShredded.d.ts","sourceRoot":"","sources":["../src/payloadShredded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,OAAO,MAAoD,CAAC;AAEjG;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAyBhE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOvD"}

package/dist/payloadShredded.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYLOAD_SHREDDED_BRAND = void 0;
+exports.brandPayloadShredded = brandPayloadShredded;
+exports.isPayloadShredded = isPayloadShredded;
+/**
+ * The realm-safe brand of the erasure outcome (ADR 0039, amendment 2026-10-17 (c)). A crypto-shredded
+ * payload is recognised by THIS symbol, never by the error's `name` alone: any store decorator, third
+ * party store or app code can throw an `Error` that merely NAMES itself `PayloadShreddedError`, and on
+ * the authorization path "proven erasure" means "unknown owner", which `unknownOwner: "allow"` admits.
+ *
+ * `Symbol.for` (the global registry) makes the brand survive duplicated package copies (dual CJS/ESM
+ * builds, two installs), where `instanceof` does not. A store that cannot extend the crypto plugin's
+ * class sets the brand on its own error with {@link brandPayloadShredded}.
+ */
+exports.PAYLOAD_SHREDDED_BRAND = Symbol.for("loom.payloadShredded");
+/**
+ * Mark `err` as the erasure outcome (non-enumerable, so serialization and logging are unchanged) and
+ * return it. Idempotent. The error's `name` and message are untouched.
+ *
+ * Brand BEFORE freezing: a frozen or otherwise non-extensible object cannot take the brand, and
+ * throwing here would replace the erasure with a TypeError. For such an object this returns a branded
+ * WRAPPER instead (a new `Error` with the same name, message, own fields and stack, `cause` = the
+ * original), so the erasure is still recognised.
+ */
+function brandPayloadShredded(err) {
+    if (!Object.isExtensible(err)) {
+        const src = err;
+        const wrapper = new Error(typeof src.message === "string" ? src.message : "", { cause: err });
+        for (const key of Object.getOwnPropertyNames(src)) {
+            if (key === "cause")
+                continue;
+            const d = Object.getOwnPropertyDescriptor(src, key);
+            if (d !== undefined)
+                Object.defineProperty(wrapper, key, { ...d, configurable: true });
+        }
+        if (!Object.prototype.hasOwnProperty.call(src, "name") && typeof src.name === "string") {
+            Object.defineProperty(wrapper, "name", {
+                value: src.name,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return brandPayloadShredded(wrapper);
+    }
+    Object.defineProperty(err, exports.PAYLOAD_SHREDDED_BRAND, {
+        value: true,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+    return err;
+}
+/**
+ * True when `err` carries the {@link PAYLOAD_SHREDDED_BRAND} as an OWN property (an inherited brand,
+ * e.g. from a shared prototype, does not count). The ONE definition every consumer uses.
+ * A plain object or `Error` that only has `name === "PayloadShreddedError"` is NOT shredded, and a
+ * value that crossed a process boundary (JSON) has lost the brand: such a boundary must re-establish
+ * trust explicitly (e.g. by checking the log's own `PAYLOAD_SHREDDED` tombstone).
+ */
+function isPayloadShredded(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        Object.prototype.hasOwnProperty.call(err, exports.PAYLOAD_SHREDDED_BRAND) &&
+        err[exports.PAYLOAD_SHREDDED_BRAND] === true);
+}
+//# sourceMappingURL=payloadShredded.js.map

package/dist/payloadShredded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadShredded.js","sourceRoot":"","sources":["../src/payloadShredded.ts"],"names":[],"mappings":";;;AAqBA,oDAyBC;AASD,8CAOC;AA9DD;;;;;;;;;GASG;AACU,QAAA,sBAAsB,GAAkB,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAU,CAAC;AAEjG;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAAmB,GAAM;IAC3D,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAyC,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAClD,IAAI,GAAG,KAAK,OAAO;gBAAE,SAAS;YAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,wBAAwB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACpD,IAAI,CAAC,KAAK,SAAS;gBAAE,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvF,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE;gBACrC,KAAK,EAAE,GAAG,CAAC,IAAI;gBACf,YAAY,EAAE,IAAI;gBAClB,QAAQ,EAAE,IAAI;aACf,CAAC,CAAC;QACL,CAAC;QACD,OAAO,oBAAoB,CAAC,OAAO,CAAiB,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,8BAAsB,EAAE;QACjD,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,8BAAsB,CAAC;QAChE,GAA+B,CAAC,8BAAsB,CAAC,KAAK,IAAI,CAClE,CAAC;AACJ,CAAC"}

package/dist/scaleDecorators.bench.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scaleDecorators.bench.d.ts.map

package/dist/scaleDecorators.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaleDecorators.bench.d.ts","sourceRoot":"","sources":["../src/scaleDecorators.bench.ts"],"names":[],"mappings":""}

package/dist/scaleDecorators.bench.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const CoalescingEventStore_1 = require("./CoalescingEventStore");
+const InMemoryAsyncEventStore_1 = require("./InMemoryAsyncEventStore");
+const ShardedEventStore_1 = require("./ShardedEventStore");
+// ── What the scale-out decorators cost and buy (ADR 0074) ────────────────────
+//
+// `scaleDecorators.test.ts` already proves round-trips are SAVED — it counts them. What a
+// count cannot say is what that is worth, because the answer depends entirely on what one
+// round-trip costs: over a free in-memory store, coalescing is pure overhead, and over a
+// network backend it is the difference between 18k and 78k events/sec (`docs/benchmarks.md`,
+// measured against real Postgres).
+//
+// So this bench prices a round-trip EXPLICITLY, spinning rather than sleeping — a timer
+// would put scheduler granularity into a measurement whose whole point is the number of
+// calls. `ROUND_TRIP_US` is the one assumption; every result below is a function of it, and
+// a reader who thinks their backend is cheaper or dearer can move it and re-run.
+//
+// The second half is the honest counterweight: what the decorators cost when there is
+// nothing to save. A decorator that is free on a free backend is a decorator that can be
+// left in place.
+const ROUND_TRIP_US = 20;
+const evt = (executionId, sequence) => ({
+    id: `${executionId}-${sequence}`,
+    workflowId: "wf",
+    executionId,
+    eventType: "STEP_COMPLETED",
+    sequence,
+    timestamp: 1000 + sequence,
+    payload: { sequence },
+});
+/** Burn `us` microseconds of CPU. Deterministic; no timer, no scheduler. */
+function spin(us) {
+    const until = performance.now() + us / 1000;
+    while (performance.now() < until) {
+        /* deliberately empty */
+    }
+}
+/**
+ * A backend that charges `ROUND_TRIP_US` per CALL, not per envelope — which is what a
+ * network backend does, and the entire reason batching exists. It keeps nothing: the
+ * measurement is the round-trips, not the storage.
+ */
+function pricedStore() {
+    return {
+        append: async () => {
+            spin(ROUND_TRIP_US);
+        },
+        appendBatch: async () => {
+            spin(ROUND_TRIP_US);
+        },
+        read: async () => [],
+        readFrom: async () => [],
+        subscribe: async () => () => { },
+        close: async () => { },
+    };
+}
+/** One envelope from each of N distinct executions, appended concurrently — the real shape:
+ *  N journals, each holding a single pending envelope, all flushing into one turn. */
+const N = 512;
+const wave = Array.from({ length: N }, (_, i) => evt(`x${i}`, 0));
+async function appendAll(store) {
+    await Promise.all(wave.map((e) => store.append(e)));
+}
+(0, vitest_1.describe)(`${N} cross-execution appends, one round-trip priced at ${ROUND_TRIP_US}µs`, () => {
+    (0, vitest_1.bench)("per-event append (no decorator)", async () => {
+        await appendAll(pricedStore());
+    });
+    (0, vitest_1.bench)("CoalescingEventStore (default maxBatch: 16)", async () => {
+        await appendAll(new CoalescingEventStore_1.CoalescingEventStore(pricedStore(), { maxBatch: 16 }));
+    });
+    (0, vitest_1.bench)("CoalescingEventStore (maxBatch: 64)", async () => {
+        await appendAll(new CoalescingEventStore_1.CoalescingEventStore(pricedStore(), { maxBatch: 64 }));
+    });
+});
+(0, vitest_1.describe)(`${N} cross-execution appends against a FREE backend (what the decorators cost)`, () => {
+    // The counterweight. Over an in-memory store there are no round-trips worth saving, so
+    // these numbers are the price of leaving a decorator wired where it buys nothing.
+    (0, vitest_1.bench)("InMemoryAsyncEventStore (no decorator)", async () => {
+        await appendAll(new InMemoryAsyncEventStore_1.InMemoryAsyncEventStore());
+    });
+    (0, vitest_1.bench)("CoalescingEventStore over in-memory", async () => {
+        await appendAll(new CoalescingEventStore_1.CoalescingEventStore(new InMemoryAsyncEventStore_1.InMemoryAsyncEventStore(), { maxBatch: 16 }));
+    });
+    (0, vitest_1.bench)("ShardedEventStore over 4 in-memory shards", async () => {
+        // Routing only — hash the id, pick a shard, delegate. What sharding actually buys is
+        // parallelism across backends, which a single-process bench cannot show and this
+        // deliberately does not claim.
+        await appendAll(new ShardedEventStore_1.ShardedEventStore(Array.from({ length: 4 }, () => new InMemoryAsyncEventStore_1.InMemoryAsyncEventStore())));
+    });
+});
+//# sourceMappingURL=scaleDecorators.bench.js.map

package/dist/scaleDecorators.bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaleDecorators.bench.js","sourceRoot":"","sources":["../src/scaleDecorators.bench.ts"],"names":[],"mappings":";;AACA,mCAAyC;AACzC,iEAA8D;AAC9D,uEAAoE;AACpE,2DAAwD;AAGxD,gFAAgF;AAChF,EAAE;AACF,0FAA0F;AAC1F,0FAA0F;AAC1F,yFAAyF;AACzF,6FAA6F;AAC7F,mCAAmC;AACnC,EAAE;AACF,wFAAwF;AACxF,wFAAwF;AACxF,4FAA4F;AAC5F,iFAAiF;AACjF,EAAE;AACF,sFAAsF;AACtF,yFAAyF;AACzF,iBAAiB;AAEjB,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,MAAM,GAAG,GAAG,CAAC,WAAmB,EAAE,QAAgB,EAAiB,EAAE,CAAC,CAAC;IACrE,EAAE,EAAE,GAAG,WAAW,IAAI,QAAQ,EAAE;IAChC,UAAU,EAAE,IAAI;IAChB,WAAW;IACX,SAAS,EAAE,gBAAgB;IAC3B,QAAQ;IACR,SAAS,EAAE,IAAI,GAAG,QAAQ;IAC1B,OAAO,EAAE,EAAE,QAAQ,EAAE;CACtB,CAAC,CAAC;AAEH,4EAA4E;AAC5E,SAAS,IAAI,CAAC,EAAU;IACtB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC5C,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;QACjC,wBAAwB;IAC1B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW;IAClB,OAAO;QACL,MAAM,EAAE,KAAK,IAAI,EAAE;YACjB,IAAI,CAAC,aAAa,CAAC,CAAC;QACtB,CAAC;QACD,WAAW,EAAE,KAAK,IAAI,EAAE;YACtB,IAAI,CAAC,aAAa,CAAC,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;QACpB,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;QACxB,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QAC/B,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;KACtB,CAAC;AACJ,CAAC;AAED;sFACsF;AACtF,MAAM,CAAC,GAAG,GAAG,CAAC;AACd,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AAElE,KAAK,UAAU,SAAS,CAAC,KAAiB;IACxC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,IAAA,iBAAQ,EAAC,GAAG,CAAC,sDAAsD,aAAa,IAAI,EAAE,GAAG,EAAE;IACzF,IAAA,cAAK,EAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAClD,MAAM,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,SAAS,CAAC,IAAI,2CAAoB,CAAC,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,SAAS,CAAC,IAAI,2CAAoB,CAAC,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAA,iBAAQ,EAAC,GAAG,CAAC,4EAA4E,EAAE,GAAG,EAAE;IAC9F,uFAAuF;IACvF,kFAAkF;IAClF,IAAA,cAAK,EAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,SAAS,CAAC,IAAI,iDAAuB,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,SAAS,CAAC,IAAI,2CAAoB,CAAC,IAAI,iDAAuB,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7F,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QAC5D,qFAAqF;QACrF,iFAAiF;QACjF,+BAA+B;QAC/B,MAAM,SAAS,CACb,IAAI,qCAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,iDAAuB,EAAE,CAAC,CAAC,CACtF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/sequenceRange.bench.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sequenceRange.bench.d.ts.map

package/dist/sequenceRange.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequenceRange.bench.d.ts","sourceRoot":"","sources":["../src/sequenceRange.bench.ts"],"names":[],"mappings":""}

package/dist/sequenceRange.bench.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const InMemoryAsyncEventStore_1 = require("./InMemoryAsyncEventStore");
+const sequenceRange_1 = require("./sequenceRange");
+// The fork/materialize hot path: extract a bounded [from..to] window from a long,
+// sequence-sorted log. The baselines are the previous O(n) shapes (a `.filter`, and
+// read()+sort()+filter) so the binary-search win is visible on a large history.
+function ev(sequence) {
+    return {
+        id: `e-${sequence}`,
+        workflowId: "wf",
+        executionId: "x",
+        eventType: "STEP_STARTED",
+        sequence,
+        timestamp: sequence,
+        payload: {},
+    };
+}
+const N = 100_000;
+const events = Array.from({ length: N }, (_, i) => ev(i));
+// Fork early in the history — the pathological case for a full scan.
+const FROM = 100;
+const TO = 200;
+(0, vitest_1.describe)("bounded range over a 100k-event log", () => {
+    (0, vitest_1.bench)("filter baseline (previous shape)", () => {
+        events.filter((e) => e.sequence >= FROM && e.sequence <= TO);
+    });
+    (0, vitest_1.bench)("sliceBySequence (binary search)", () => {
+        (0, sequenceRange_1.sliceBySequence)(events, FROM, TO);
+    });
+});
+(0, vitest_1.describe)("InMemoryAsyncEventStore range read (100k events)", () => {
+    const store = new InMemoryAsyncEventStore_1.InMemoryAsyncEventStore();
+    // Prime the store once outside the measured loop.
+    for (let i = 0; i < N; i++)
+        void store.append(ev(i));
+    (0, vitest_1.bench)("read()+sort()+filter baseline (previous shape)", async () => {
+        const all = [...(await store.read("x"))].sort((a, b) => a.sequence - b.sequence);
+        all.filter((e) => e.sequence >= FROM && e.sequence <= TO);
+    });
+    (0, vitest_1.bench)("readRange (binary search, no sort)", async () => {
+        await store.readRange("x", FROM, TO);
+    });
+});
+//# sourceMappingURL=sequenceRange.bench.js.map

package/dist/sequenceRange.bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequenceRange.bench.js","sourceRoot":"","sources":["../src/sequenceRange.bench.ts"],"names":[],"mappings":";;AACA,mCAAyC;AACzC,uEAAoE;AACpE,mDAAkD;AAElD,kFAAkF;AAClF,oFAAoF;AACpF,gFAAgF;AAEhF,SAAS,EAAE,CAAC,QAAgB;IAC1B,OAAO;QACL,EAAE,EAAE,KAAK,QAAQ,EAAE;QACnB,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,GAAG;QAChB,SAAS,EAAE,cAAc;QACzB,QAAQ;QACR,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,GAAG,OAAO,CAAC;AAClB,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,qEAAqE;AACrE,MAAM,IAAI,GAAG,GAAG,CAAC;AACjB,MAAM,EAAE,GAAG,GAAG,CAAC;AAEf,IAAA,iBAAQ,EAAC,qCAAqC,EAAE,GAAG,EAAE;IACnD,IAAA,cAAK,EAAC,kCAAkC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,iCAAiC,EAAE,GAAG,EAAE;QAC5C,IAAA,+BAAe,EAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAA,iBAAQ,EAAC,kDAAkD,EAAE,GAAG,EAAE;IAChE,MAAM,KAAK,GAAG,IAAI,iDAAuB,EAAE,CAAC;IAC5C,kDAAkD;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,KAAK,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,IAAA,cAAK,EAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjF,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;QACrD,MAAM,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/sequenceRange.d.ts

@@ -0,0 +1,10 @@
+import type { EventEnvelope } from "@loomwork/core";
+/** First index whose event.sequence >= `seq` (i.e. events.length if none). */
+export declare function lowerBoundBySequence(events: readonly EventEnvelope[], seq: number): number;
+/**
+ * Events with `fromSequence <= sequence <= toSequence`, assuming `events` is
+ * sorted ascending by sequence. O(log n) to locate the bounds + O(k) to copy the
+ * k in-range events — no full scan.
+ */
+export declare function sliceBySequence(events: readonly EventEnvelope[], fromSequence: number, toSequence: number): EventEnvelope[];
+//# sourceMappingURL=sequenceRange.d.ts.map

package/dist/sequenceRange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequenceRange.d.ts","sourceRoot":"","sources":["../src/sequenceRange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQpD,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,aAAa,EAAE,CAKjB"}

package/dist/sequenceRange.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lowerBoundBySequence = lowerBoundBySequence;
+exports.sliceBySequence = sliceBySequence;
+// Binary-search helpers over an event array that is sorted ascending by
+// `sequence` — the invariant every EventStore preserves (the per-execution
+// sequencer assigns strictly increasing sequences, and `copyPrefix` copies in
+// order). They turn range reads on an in-memory log from O(n) filters into
+// O(log n + k) slices, and back the workflow-runtime fork/materialize path.
+/** First index whose event.sequence >= `seq` (i.e. events.length if none). */
+function lowerBoundBySequence(events, seq) {
+    let lo = 0;
+    let hi = events.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (events[mid].sequence < seq)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/**
+ * Events with `fromSequence <= sequence <= toSequence`, assuming `events` is
+ * sorted ascending by sequence. O(log n) to locate the bounds + O(k) to copy the
+ * k in-range events — no full scan.
+ */
+function sliceBySequence(events, fromSequence, toSequence) {
+    if (toSequence < fromSequence)
+        return [];
+    const start = lowerBoundBySequence(events, fromSequence);
+    const end = lowerBoundBySequence(events, toSequence + 1);
+    return events.slice(start, end);
+}
+//# sourceMappingURL=sequenceRange.js.map

package/dist/sequenceRange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequenceRange.js","sourceRoot":"","sources":["../src/sequenceRange.ts"],"names":[],"mappings":";;AASA,oDASC;AAOD,0CASC;AAhCD,wEAAwE;AACxE,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAE5E,8EAA8E;AAC9E,SAAgB,oBAAoB,CAAC,MAAgC,EAAE,GAAW;IAChF,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;IACvB,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAK,MAAM,CAAC,GAAG,CAAmB,CAAC,QAAQ,GAAG,GAAG;YAAE,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;;YAC3D,EAAE,GAAG,GAAG,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAC7B,MAAgC,EAChC,YAAoB,EACpB,UAAkB;IAElB,IAAI,UAAU,GAAG,YAAY;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/timers.d.ts

@@ -0,0 +1,87 @@
+export interface TimerRecord {
+    executionId: string;
+    /** Absolute wake time (epoch ms) — matches the logged `condition.wakeAt`. */
+    wakeAt: number;
+    /**
+     * ADR 0118 D4 — marks a RE-DRIVE row: a backed-off retry of a resume that hit `contended`
+     * (`attempt` counts the tries so far), not the wake of a timed suspend. `TimerService.fire` does
+     * NOT judge it by `suspendedOn.wakeAt` (which would retire it as obsolete); it hands it to the
+     * registered re-drivers. Optional and additive: a plain wake carries none.
+     *
+     * `schedule` UPSERTS it: re-scheduling an existing `(executionId, wakeAt)` never clears a flag
+     * already set (a redrive row is never downgraded to a plain wake), and a record that carries one
+     * sets it on a row that had none. A store must keep a `redrive` row distinguishable from a plain
+     * one through `due`.
+     */
+    redrive?: {
+        attempt: number;
+    };
+    /**
+     * ADR 0130 D10 - marks a REPLAY-REFUSAL row: a node that could not open a sealed recorded answer
+     * refused to run a `running` execution and left this row so a node that CAN picks it up. `head` is
+     * the execution's log head at the refusal; the timer poll re-drives only while the log still sits
+     * there. `wakeAt` is an ordinary instant (when the poll should look next), never an encoded stamp.
+     * Optional and additive: a plain wake carries none. A node that predates the field reads the row
+     * as a plain wake it can never match to a park and retires it as obsolete (fail safe: never re-driven).
+     *
+     * `holds` (optional, absent = 0) counts how many times a poller has HELD the row (rescheduled it
+     * to a later instant because it could not act yet). It is part of the row's own data so the next
+     * instant is a DETERMINISTIC function of the row (`wakeAt` + back-off(holds + 1), no node-local
+     * jitter): N pollers that read the same row all write the SAME successor key, so concurrent
+     * holders converge on one row instead of multiplying it.
+     *
+     * `schedule` UPSERTS it like `redrive`: re-scheduling an existing `(executionId, wakeAt)` never
+     * clears a stamp already set, and a record that carries one sets it. On a same-key upsert the
+     * stored stamp keeps the MAX `head` and the MAX `holds` of the two (never last-writer-wins: two
+     * nodes writing in the same millisecond must not move a head backwards). A store must keep a
+     * `refused` row distinguishable from a plain one through `due`.
+     */
+    refused?: {
+        head: number;
+        holds?: number;
+    };
+}
+export interface TimerStore {
+    /** Idempotent per (executionId, wakeAt): re-scheduling the same wake is a no-op. */
+    schedule(timer: TimerRecord): Promise<void>;
+    /**
+     * Timers with `wakeAt <= now`, ordered soonest-first.
+     *
+     * `options.redrive === false` (ADR 0118 D4) EXCLUDES re-drive rows BEFORE the limit applies: a
+     * node with no re-driver registered would otherwise see a batch full of rows it cannot judge and
+     * starve every plain wake behind them. A store that ignores the option is still correct (the
+     * service skips such rows itself); it only keeps that starvation window.
+     *
+     * `options.inbox === false` (ADR 0110) likewise EXCLUDES the inbox wake row (a NON-re-drive row at `wakeAt === -1`,
+     * `INBOX_WAKE_AT`) before the limit: a node with the inbox flag off cannot run the notify path
+     * and must leave those rows for a node that can, but they sort first (instant -1), so a batch of
+     * them would starve every real timer behind it. The sentinel is -1, an instant no timed
+     * park uses, so a flag-off node still fires every real timer (including `ctx.sleep(0)` at clock 0).
+     *
+     * `options.refused === false` (ADR 0130 D10) EXCLUDES replay-refusal rows BEFORE the limit: a node
+     * with no abandonment evidence configured (or no inbox) cannot act on them, and must not fetch
+     * - let alone read the execution of - one per row. A store that ignores the option is still
+     * correct (the service skips such rows itself); it only keeps that starvation window.
+     */
+    due(now: number, limit?: number, options?: {
+        redrive?: boolean;
+        inbox?: boolean;
+        refused?: boolean;
+    }): Promise<TimerRecord[]>;
+    /** Remove a fired (or obsolete) timer. Unknown timers are a no-op. */
+    complete(executionId: string, wakeAt: number): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class InMemoryTimerStore implements TimerStore {
+    private readonly timers;
+    private key;
+    schedule(timer: TimerRecord): Promise<void>;
+    due(now: number, limit?: number, options?: {
+        redrive?: boolean;
+        inbox?: boolean;
+        refused?: boolean;
+    }): Promise<TimerRecord[]>;
+    complete(executionId: string, wakeAt: number): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=timers.d.ts.map

package/dist/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAClE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiBD,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD,OAAO,CAAC,GAAG;IAIL,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3C,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,SAAM,EACX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAClE,OAAO,CAAC,WAAW,EAAE,CAAC;IAkBnB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}