@loomwork/event-runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,8 @@
+Loom
+Copyright 2026 Sushil Chhetri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this project except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @loomwork/event-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The durable log's contract (`EventStore`, SPI 2.6.0), an in-memory implementation, and the decorators
+that scale or scope any backend. The kernel appends every fact to an `EventStore` and rebuilds state by
+folding it, so this is the interface a storage backend implements. You use the package directly to
+compose stores for `defineConfig`, to write your own backend, or to write a decorator. The durable
+backends live in `@loomwork/plugin-sqlite` and `@loomwork/plugin-postgres`.
+
+```ts
+import { defineConfig } from "@loomwork/app";
+import {
+  CoalescingEventStore,
+  InMemoryAsyncEventStore,
+  ShardedEventStore,
+  TenantScopedEventStore,
+  appendBatchOf,
+  headOf,
+} from "@loomwork/event-runtime";
+
+// Order from ADR 0074: sharding outermost, then coalescing, then tenant scoping, then the backend.
+const shard = () =>
+  new CoalescingEventStore(new TenantScopedEventStore(new InMemoryAsyncEventStore(), "acme"), {
+    maxBatch: 32,
+  });
+const events = new ShardedEventStore([shard(), shard()]);
+
+const app = defineConfig({ storage: { kind: "custom", eventStore: events } });
+
+// Optional methods may be absent on a backend: call them through the helpers, which fall back.
+export async function tipOf(executionId: string) {
+  await appendBatchOf(events, []); // empty input is a no-op
+  return headOf(events, executionId); // null when the execution has no events
+}
+```
+
+## Surface
+
+- **The SPI.** Required: `append`, `read`, `readFrom`, `subscribe`, `close`. Optional, each added in a
+  MINOR version: `appendBatch`, `readRange`, `head`, `acquireFence` / `acquireFenceIf`,
+  `appendIfUnchanged`, `storeNow`, `copyPrefix`, `deleteExecution`, `deleteThrough`, `truncatePrefix` /
+  `truncatePrefixKeeping`, `listExecutions` / `listExecutionsPage`, plus the sealing methods
+  `sealingCapability` and `readAtRest`. Callers use `appendBatchOf`, `readRangeOf`, `headOf` and
+  `iterateExecutionIds`, which fall back when a method is missing.
+- **Stores.** `InMemoryAsyncEventStore` (also importable from `@loomwork/event-runtime/memory`, which pulls
+  in no native modules) and `InMemoryArchiveStore`, `InMemoryLeaseStore`, `InMemoryBranchRegistry`,
+  `InMemoryTimerStore`. All are process-local and lose everything on exit.
+- **Decorators.** `CoalescingEventStore` (many concurrent appends, one `appendBatch`),
+  `ShardedEventStore` + `ShardPlan` (route an execution to one of N stores, rebalance with
+  `migrateExecution`), `TenantScopedEventStore` (prefix every id with a tenant), and
+  `ProfilingEventStore` (write-side timing, `writeProfile()`).
+- **Writing a decorator.** `installOptional` and `DecoratorPlan` make you forward, override or refuse
+  every optional method; a plan that omits one does not compile.
+- **Errors and reserved ids.** `StaleFenceError`, `DuplicateSequenceError`, `DuplicateEnvelopeIdError`;
+  `isReservedStream` and the `__loom_*` stream prefixes.
+
+## Behaviour that surprises people
+
+- **Two uniqueness rules.** A backend must reject a repeated `(executionId, sequence)` with
+  `DuplicateSequenceError` and a repeated envelope `id` within an execution with
+  `DuplicateEnvelopeIdError`. Neither may be reported as the other, and neither overwrites.
+- **`subscribe` can lose a cross-node wake-up.** A local append is delivered synchronously, but a
+  wake-up from another node (a dropped listener, a full Postgres NOTIFY queue) is not re-sent. The log
+  stays complete. A subscriber that must see a final event re-reads the log on its own timer, as
+  `@loomwork/live-query` does.
+- **Batching is atomic per execution, not across executions.** `appendBatch` is equivalent to `append`
+  in array order. If a backend omits it, `appendBatchOf` falls back to a sequential loop that is not
+  atomic. `CoalescingEventStore` resolves an append only after its batch commits, and one rejected
+  envelope (a stale fence, for example) rejects every writer in that batch. It also needs
+  `appendBatch` on every layer below it to get the atomicity.
+- **Composition order matters.** A decorator that drops an optional method silently takes that
+  capability away from everything above it (the original `Coalescing(TenantScoped(...))` batched
+  nothing). `runEventStoreDecoratorConformance` in `@loomwork/conformance` checks yours.
+- **Tenant scoping is by key prefix.** `TenantScopedEventStore` throws `TypeError` for an empty tenant
+  or one containing `:`. It scopes ids the store sees; it is not encryption.
+- **`ShardedEventStore` needs a stable `shardOf`** (the default is a fixed hash), and it advertises an
+  optional method only if every shard has it. It throws `ShardSealingMismatchError` when shards
+  disagree about sealing. Changing the shard count without a `ShardPlan` re-routes executions.
+- **Listing order is part of the SPI.** `listExecutionsPage` pages in Unicode code point order with an
+  executionId as the cursor (SPI 2.0.0, ADR 0108).
+- **Erasure is signalled by a branded error.** A store that crypto-shreds must throw an error
+  recognised by `isPayloadShredded`; any other failure is treated as retryable, not as proof of erasure.
+
+## See also
+
+- API reference: section "`@loomwork/event-runtime` — the durable log" in
+  [docs/api-reference.org](../../docs/api-reference.org).
+- Guides: [log and read models](../../docs/user-guide/log-and-read-models.md),
+  [scaling](../../docs/scaling.md).
+- ADRs: [0033 SPI conformance](../../docs/adr/0033-spi-conformance-contracts.md),
+  [0074 scale-out decorators](../../docs/adr/0074-storage-scale-out-decorators.md),
+  [0075 shard rebalancing](../../docs/adr/0075-shard-rebalancing.md),
+  [0108 execution-id order](../../docs/adr/0108-execution-id-order-and-fail-soft-migrations.md).
+
+## Install
+
+Unpublished for now: inside this repo use `workspace:*`; from a sibling checkout use a `link:` override (see [AGENTS.md](../../AGENTS.md)).

package/dist/BranchRegistry.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Git-style branching for event-sourced executions — branch only, no merge.
+ *
+ * A {@link BranchRef} is a movable pointer (like a git branch) naming the head
+ * execution of a line of work. A {@link LineageRecord} is an immutable edge in
+ * the fork DAG (child → parent at a sequence). Together they let speculative
+ * agent executions fork from any point, run independently, and be selected with
+ * `promote()` ("pick-a-winner"). There is deliberately no merge/rebase: two
+ * divergent ExecutionStates have no principled join, so we don't fake one.
+ */
+/**
+ * SPI version for the {@link BranchRegistry} contract (ADR 0033). Pinned by
+ * `runBranchRegistryConformance` in `@loomwork/testing`.
+ *
+ * **2.0.0 (L21, ADR 0108 addendum, MAJOR):** `listRefs` orders names in Unicode **code
+ * point** order — the same order `EventStore.listExecutionsPage` pins (ADR 0108, SPI
+ * 2.0.0): UTF-8 byte order, SQL `COLLATE "C"`, SQLite BINARY, and `compareExecutionIds`
+ * (`@loomwork/event-runtime`) as the reference comparator. Not a database's default collation,
+ * and not `String.prototype.localeCompare` — both can disagree with code point order, and
+ * `localeCompare` can return 0 for two DISTINCT, canonically-equivalent names (an NFC "é"
+ * and its NFD decomposition). `after` may be **any string**, not only a name a previous
+ * `listRefs` call returned, and the page holds the names strictly after it. Before this, the
+ * three backends ordered `listRefs` three different ways (Postgres: database collation;
+ * SQLite: BINARY, already conforming; in-memory: `localeCompare`), so a cursor produced by
+ * one order and consumed by another skipped or repeated refs at a page boundary — the same
+ * failure mode ADR 0108 fixed for execution ids. MAJOR because a store conforming to 1.x
+ * (any order, an opaque cursor) can fail the new conformance case (the ADR 0091 rule); no
+ * method was added or removed.
+ */
+export declare const BRANCH_REGISTRY_SPI_VERSION = "2.0.0";
+/** A named, movable pointer to an execution head. */
+export interface BranchRef {
+    /** Branch name, e.g. "main" or "spec/scale-replicas". Unique. */
+    name: string;
+    /** The execution this ref currently points at. */
+    executionId: string;
+    /** Latest known sequence on that execution (advanced via `moveTip`). */
+    tip: number;
+    /** If this branch was created by a fork, the execution it forked from. */
+    parentExecutionId?: string;
+    /** If this branch was created by a fork, the sequence it forked at. */
+    forkSequence?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** An immutable edge in the fork DAG: `executionId` forked from `parentExecutionId` at `forkSequence`. */
+export interface LineageRecord {
+    executionId: string;
+    parentExecutionId: string;
+    forkSequence: number;
+    createdAt: number;
+}
+/** Paging for {@link BranchRegistry.listRefs}. Keyset, because refs are unique and name-ordered. */
+export interface ListRefsOptions {
+    /** Max rows to return. Must be a positive integer — an unbounded page is not a default. */
+    limit?: number;
+    /**
+     * Return refs whose name sorts strictly AFTER this one, in Unicode CODE POINT order
+     * (SPI 2.0.0, ADR 0108 addendum / L21 — {@link BRANCH_REGISTRY_SPI_VERSION}). May be ANY
+     * string, not only a name a previous `listRefs` call returned — pass the last name of the
+     * previous page.
+     */
+    after?: string;
+}
+/** Options for {@link BranchRegistry.promote}. */
+export interface PromoteOptions {
+    /**
+     * Compare-and-set. The executionId `toName` is expected to name right now, or `null` for
+     * "must not exist yet". The repoint happens only if the expectation holds; otherwise it
+     * throws {@link BranchPromotionConflictError} and **nothing moves**.
+     *
+     * Without it, `promote` is last-write-wins: two nodes promoting different winners onto
+     * `main` both succeed and the loser silently wins. That is the 1.0.0 behaviour, preserved
+     * byte-identically when `expect` is omitted.
+     */
+    expect?: string | null;
+}
+/**
+ * A compare-and-set {@link BranchRegistry.promote} lost: `toName` does not name what the
+ * caller expected, so the promotion was refused. The registry is untouched — re-read the ref
+ * and decide, rather than retrying blind.
+ */
+export declare class BranchPromotionConflictError extends Error {
+    readonly toName: string;
+    readonly expected: string | null;
+    readonly actual: string | null;
+    constructor(toName: string, expected: string | null, actual: string | null);
+}
+/**
+ * Refuse a nonsense page size before it reaches a backend. SQLite treats `LIMIT -1` as "no
+ * limit", so an unvalidated negative silently returns the whole table — the opposite of what
+ * a caller asking for a page wants.
+ */
+export declare function assertListRefsLimit(limit: number | undefined): void;
+export interface BranchRegistry {
+    /** Create or move a ref (upsert by name). */
+    putRef(ref: BranchRef): Promise<void>;
+    getRef(name: string): Promise<BranchRef | null>;
+    /**
+     * Refs in name order — Unicode CODE POINT order (SPI 2.0.0, see
+     * {@link BRANCH_REGISTRY_SPI_VERSION}), never a database collation or
+     * `String.prototype.localeCompare`. Unpaged by default; pass `limit`/`after` to walk a
+     * registry that has grown — forking is cheap, so the ref table is unbounded by design.
+     */
+    listRefs(options?: ListRefsOptions): Promise<BranchRef[]>;
+    /** Advance a ref's tip as its execution grows. No-op if the ref is absent. */
+    moveTip(name: string, tip: number): Promise<void>;
+    /**
+     * Pick-a-winner: repoint `toName` onto the execution `fromName` currently
+     * names, adopting its (executionId, tip). This is the entire "merge"
+     * replacement — a pointer move, no history rewrite, no state reconciliation.
+     * The losing execution remains immutable and independently resumable.
+     * Throws if `fromName` does not exist. Pass `options.expect` to make it a compare-and-set
+     * (see {@link PromoteOptions}) — without it, a concurrent promotion is a silent overwrite.
+     */
+    promote(fromName: string, toName: string, options?: PromoteOptions): Promise<void>;
+    deleteRef(name: string): Promise<void>;
+    /** Record a fork edge in the DAG. */
+    recordLineage(rec: Omit<LineageRecord, "createdAt">): Promise<void>;
+    getLineage(executionId: string): Promise<LineageRecord | null>;
+    /**
+     * OPTIONAL: forget one fork edge — the child's edge to its parent.
+     *
+     * Lineage is the alternatives-considered audit trail and must outlive a branch's own
+     * life. It must NOT outlive the executions it describes: once retention has reclaimed a
+     * branch, its edge points at data that no longer exists, and keeping a permanent index of
+     * deleted executions contradicts the retention policy that deleted them. It also costs —
+     * `LogLifecycle` walks `children()` on every sweep, so dead edges make retention slower
+     * forever, in proportion to every fork ever taken.
+     *
+     * Called by `LogLifecycle` at the moment an execution is deleted, which is the only point
+     * where the id is known and the data is provably gone. A store that omits it simply keeps
+     * its edges (today's behaviour, byte-identically).
+     */
+    removeLineage?(executionId: string): Promise<void>;
+    /** Direct children forked from `executionId`. */
+    children(executionId: string): Promise<LineageRecord[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=BranchRegistry.d.ts.map

package/dist/BranchRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchRegistry.d.ts","sourceRoot":"","sources":["../src/BranchRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,UAAU,CAAC;AAEnD,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;gBAFrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,GAAG,IAAI;CAQjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKnE;AAED,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1D,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,qCAAqC;IACrC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC/D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAExD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/BranchRegistry.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Git-style branching for event-sourced executions — branch only, no merge.
+ *
+ * A {@link BranchRef} is a movable pointer (like a git branch) naming the head
+ * execution of a line of work. A {@link LineageRecord} is an immutable edge in
+ * the fork DAG (child → parent at a sequence). Together they let speculative
+ * agent executions fork from any point, run independently, and be selected with
+ * `promote()` ("pick-a-winner"). There is deliberately no merge/rebase: two
+ * divergent ExecutionStates have no principled join, so we don't fake one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchPromotionConflictError = exports.BRANCH_REGISTRY_SPI_VERSION = void 0;
+exports.assertListRefsLimit = assertListRefsLimit;
+/**
+ * SPI version for the {@link BranchRegistry} contract (ADR 0033). Pinned by
+ * `runBranchRegistryConformance` in `@loomwork/testing`.
+ *
+ * **2.0.0 (L21, ADR 0108 addendum, MAJOR):** `listRefs` orders names in Unicode **code
+ * point** order — the same order `EventStore.listExecutionsPage` pins (ADR 0108, SPI
+ * 2.0.0): UTF-8 byte order, SQL `COLLATE "C"`, SQLite BINARY, and `compareExecutionIds`
+ * (`@loomwork/event-runtime`) as the reference comparator. Not a database's default collation,
+ * and not `String.prototype.localeCompare` — both can disagree with code point order, and
+ * `localeCompare` can return 0 for two DISTINCT, canonically-equivalent names (an NFC "é"
+ * and its NFD decomposition). `after` may be **any string**, not only a name a previous
+ * `listRefs` call returned, and the page holds the names strictly after it. Before this, the
+ * three backends ordered `listRefs` three different ways (Postgres: database collation;
+ * SQLite: BINARY, already conforming; in-memory: `localeCompare`), so a cursor produced by
+ * one order and consumed by another skipped or repeated refs at a page boundary — the same
+ * failure mode ADR 0108 fixed for execution ids. MAJOR because a store conforming to 1.x
+ * (any order, an opaque cursor) can fail the new conformance case (the ADR 0091 rule); no
+ * method was added or removed.
+ */
+exports.BRANCH_REGISTRY_SPI_VERSION = "2.0.0";
+/**
+ * A compare-and-set {@link BranchRegistry.promote} lost: `toName` does not name what the
+ * caller expected, so the promotion was refused. The registry is untouched — re-read the ref
+ * and decide, rather than retrying blind.
+ */
+class BranchPromotionConflictError extends Error {
+    toName;
+    expected;
+    actual;
+    constructor(toName, expected, actual) {
+        super(`promote onto "${toName}" refused: expected it to name ${expected === null ? "nothing" : `"${expected}"`}, but it names ${actual === null ? "nothing" : `"${actual}"`}`);
+        this.toName = toName;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "BranchPromotionConflictError";
+        Object.setPrototypeOf(this, BranchPromotionConflictError.prototype);
+    }
+}
+exports.BranchPromotionConflictError = BranchPromotionConflictError;
+/**
+ * Refuse a nonsense page size before it reaches a backend. SQLite treats `LIMIT -1` as "no
+ * limit", so an unvalidated negative silently returns the whole table — the opposite of what
+ * a caller asking for a page wants.
+ */
+function assertListRefsLimit(limit) {
+    if (limit === undefined)
+        return;
+    if (!Number.isInteger(limit) || limit <= 0) {
+        throw new RangeError(`listRefs: limit must be a positive integer, got ${limit}`);
+    }
+}
+//# sourceMappingURL=BranchRegistry.js.map

package/dist/BranchRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchRegistry.js","sourceRoot":"","sources":["../src/BranchRegistry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAkGH,kDAKC;AArGD;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,2BAA2B,GAAG,OAAO,CAAC;AAqDnD;;;;GAIG;AACH,MAAa,4BAA6B,SAAQ,KAAK;IAE1C;IACA;IACA;IAHX,YACW,MAAc,EACd,QAAuB,EACvB,MAAqB;QAE9B,KAAK,CACH,iBAAiB,MAAM,kCAAkC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,kBAAkB,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,EAAE,CACxK,CAAC;QANO,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAe;QACvB,WAAM,GAAN,MAAM,CAAe;QAK9B,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,4BAA4B,CAAC,SAAS,CAAC,CAAC;IACtE,CAAC;CACF;AAZD,oEAYC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,KAAyB;IAC3D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,UAAU,CAAC,mDAAmD,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;AACH,CAAC"}

package/dist/CoalescingEventStore.d.ts

@@ -0,0 +1,97 @@
+import type { EventEnvelope } from "@loomwork/core";
+import { type EventStore } from "./types";
+export interface CoalescingEventStoreOptions {
+    /**
+     * Flush once this many envelopes are queued. The measured knee is ~16; past ~64 both
+     * throughput and tail latency regress. Default 16.
+     */
+    maxBatch?: number;
+    /**
+     * Upper bound in milliseconds on how long the FIRST envelope of a batch waits for
+     * company. Default 0 — flush on the next microtask, which under concurrency already
+     * collects everything enqueued in the same turn without adding measurable latency.
+     * Raise it only if you are deliberately trading latency for batch size.
+     */
+    maxLingerMs?: number;
+}
+/**
+ * Merges concurrent appends **across executions** into one `appendBatch` (ADR 0074 D2).
+ *
+ * Why a decorator and not the journal: `ExecutionJournal` is per-execution, so a
+ * journal-side batcher can only ever hold one execution's envelopes — a 1-step flow emits
+ * four, and with a realistic slow effect the serial tail drains between `STEP_STARTED` and
+ * `STEP_COMPLETED`, so it collects one. Measured; it is ADR 0065's own gate-2 case. A store
+ * decorator sees every live execution at once and can actually fill a batch.
+ *
+ * **Ordering.** Each `ExecutionJournal` still serializes its own execution (D3 unchanged) —
+ * it awaits each `append` before issuing the next, so this store never holds two envelopes
+ * of one execution concurrently through the normal path. Should it anyway (a second writer,
+ * a caller not using the journal), the queue is FIFO and `appendBatch` is specified to
+ * apply in array order, so arrival order is preserved regardless.
+ *
+ * **Durability.** An `append` promise resolves only once its batch has committed. Nothing
+ * resolves early, so every `drain()` barrier keeps exactly the meaning it has today. This
+ * is the property that distinguishes coalescing from the durability classes ADR 0065
+ * rejected on invariants.
+ *
+ * **Failure.** A batch rejection rejects every caller in that batch, so a partial write can
+ * never look like success. Combined with `appendBatch`'s all-or-nothing contract, a failed
+ * flush leaves the log untouched and every writer informed — **but only when the inner store
+ * implements `appendBatch`**. Over a store without it, `appendBatchOf` falls back to a
+ * sequential `append` loop, which is not atomic: envelopes ahead of the failing one are
+ * already durable while their writers are told the batch failed. Every decorator between
+ * this one and the backend must therefore carry `appendBatch` down (ADR 0074 Amendment —
+ * `runEventStoreDecoratorConformance` checks it).
+ *
+ * **Blast radius.** One stale-fence zombie in a batch rejects the whole batch, so every
+ * healthy writer coalesced with it is told "failed" too (nothing of theirs lands; they abort
+ * and recovery re-drives them from the log). Coalescing widens a fencing rejection from one
+ * execution to up to `maxBatch` of them — a price worth paying while fencing is rare.
+ *
+ * Inert unless wired: compose it explicitly in `storage`, outermost-but-one (sharding
+ * outside it, since routing must pick a shard before a batch is formed for that shard).
+ */
+export declare class CoalescingEventStore implements EventStore {
+    private readonly inner;
+    readonly head?: NonNullable<EventStore["head"]>;
+    readonly readRange?: NonNullable<EventStore["readRange"]>;
+    readonly acquireFence?: NonNullable<EventStore["acquireFence"]>;
+    readonly acquireFenceIf?: NonNullable<EventStore["acquireFenceIf"]>;
+    readonly appendIfUnchanged?: NonNullable<EventStore["appendIfUnchanged"]>;
+    readonly storeNow?: NonNullable<EventStore["storeNow"]>;
+    readonly sealingCapability?: NonNullable<EventStore["sealingCapability"]>;
+    readonly readAtRest?: NonNullable<EventStore["readAtRest"]>;
+    readonly copyPrefix?: NonNullable<EventStore["copyPrefix"]>;
+    readonly deleteExecution?: NonNullable<EventStore["deleteExecution"]>;
+    readonly deleteThrough?: NonNullable<EventStore["deleteThrough"]>;
+    readonly truncatePrefix?: NonNullable<EventStore["truncatePrefix"]>;
+    readonly truncatePrefixKeeping?: NonNullable<EventStore["truncatePrefixKeeping"]>;
+    readonly listExecutions?: NonNullable<EventStore["listExecutions"]>;
+    readonly listExecutionsPage?: NonNullable<EventStore["listExecutionsPage"]>;
+    private readonly maxBatch;
+    private readonly maxLingerMs;
+    private queue;
+    private flushScheduled;
+    private timer;
+    /** Serializes flushes so two batches can never be in flight against the inner store. */
+    private tail;
+    private closed;
+    constructor(inner: EventStore, options?: CoalescingEventStoreOptions);
+    append(envelope: EventEnvelope): Promise<void>;
+    /**
+     * A caller that already has a batch skips the queue entirely — it is by definition
+     * already coalesced, and threading it through the queue would only risk splitting it.
+     */
+    appendBatch(envelopes: readonly EventEnvelope[]): Promise<void>;
+    private scheduleFlush;
+    private flushNow;
+    /** Chain onto the serial tail so batches commit one at a time, in enqueue order. */
+    private enqueueFlush;
+    read(executionId: string): Promise<EventEnvelope[]>;
+    readFrom(executionId: string, fromSequence: number): Promise<EventEnvelope[]>;
+    subscribe(executionId: string, handler: (event: EventEnvelope) => void): Promise<() => void>;
+    /** Flush anything queued and wait for in-flight batches. Safe to call repeatedly. */
+    drain(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=CoalescingEventStore.d.ts.map

package/dist/CoalescingEventStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoalescingEventStore.d.ts","sourceRoot":"","sources":["../src/CoalescingEventStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,KAAK,UAAU,EAAgD,MAAM,SAAS,CAAC;AAExF,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,oBAAqB,YAAW,UAAU;IA2BnD,OAAO,CAAC,QAAQ,CAAC,KAAK;IA1BxB,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAE5E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,KAAK,CAA4C;IACzD,wFAAwF;IACxF,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,MAAM,CAAS;gBAGJ,KAAK,EAAE,UAAU,EAClC,OAAO,GAAE,2BAAgC;IAgC3C,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/D,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,QAAQ;IA0BhB,oFAAoF;IACpF,OAAO,CAAC,YAAY;IAUpB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAInD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAI7E,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAI5F,qFAAqF;IAC/E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}