@loomwork/projection-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,65 @@
-# Temporary Holding Version
+# @loomwork/projection-runtime — in-memory read models folded from events
 
-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.
+A projection folds an execution's events into a small state object that a UI or another reader can
+query and subscribe to. This package holds the `Projection` and `ProjectionRuntime` types and the one
+implementation, `InMemoryProjectionRuntime`. `defineConfig` creates one for you when you do not pass
+`projectionRuntime`, registers your `projections`, and feeds it every event, so most apps use it through
+`@loomwork/app` and the renderers rather than constructing it. Reach for it directly in tests, or when you
+wire a surface of your own.
+
+```ts
+import { InMemoryProjectionRuntime } from "@loomwork/projection-runtime";
+import type { EventEnvelope } from "@loomwork/core";
+
+const runtime = new InMemoryProjectionRuntime({ coalesceNotifications: true });
+
+runtime.register<{ completed: number }>({
+  id: "progress",
+  version: "1", // bump when the fold's meaning changes (ADR 0095)
+  initialState: { completed: 0 },
+  handlers: { STEP_COMPLETED: (state) => ({ completed: state.completed + 1 }) },
+});
+
+declare const event: EventEnvelope; // normally from EventStore.subscribe, or defineConfig's feed
+runtime.handleEvent(event);
+
+const stop = runtime.subscribeSelector<{ completed: number }, number>(
+  "progress",
+  event.executionId,
+  (state) => state.completed,
+  (completed) => console.log("completed steps:", completed)
+);
+stop();
+```
+
+## Surface
+
+- **Types.** `Projection` (`id`, `initialState`, `handlers` or an event-type-gated `lazy` loader, optional
+  `version`) and `ProjectionRuntime`.
+- **Reads.** `getState(projectionId, executionId)` returns `initialState` for an execution it has seen no
+  events for, and throws for a projection that was never registered.
+- **Subscriptions.** `subscribe` fires on every change. `subscribeSelector` fires only when a selected
+  slice changes (`Object.is` by default, or your `isEqual`), and not on subscribe (ADR 0068).
+- **Feeding.** `handleEvent(event)` and `seedState(...)`. `forget(executionId)` drops a finished
+  execution's state and subscribers.
+
+## Behaviour that surprises people
+
+- **State lives in memory.** Nothing here persists it, and a new process starts from `initialState`.
+- **Retention is bounded.** `maxExecutions` (default 10,000) keeps the most recently touched executions.
+  An evicted execution reads as `initialState` again, but an execution with a live subscriber is skipped
+  by eviction (the scan gives up after 64 candidates, so the cap can be exceeded).
+- **Notifications are synchronous by default.** `coalesceNotifications: true` flushes once per
+  microtask with the latest state, so a burst of events reaches subscribers once.
+- **A lazy projection loads its fold code on the first matching event.** If that load fails, the
+  projection is abandoned and its buffered events are dropped; the buffer is capped at 10,000.
+
+## Status / See also
+
+Unpublished for now: inside this repo use `workspace:*`; from a sibling checkout use a `link:` override
+(see [AGENTS.md](../../AGENTS.md)).
+
+- [ADR 0068](../../docs/adr/0068-projection-selector-subscription.md): selector subscriptions.
+- [ADR 0095](../../docs/adr/0095-binding-semantics-pin.md): the declared `version` and pin checks.
+- API reference: section "`@loomwork/projection-runtime`" in [docs/api-reference.org](../../docs/api-reference.org).
+- Guides: [docs/user-guide.md](../../docs/user-guide.md), [docs/README.md](../../docs/README.md).

package/dist/InMemoryProjectionRuntime.d.ts

@@ -0,0 +1,70 @@
+import type { EventEnvelope } from "@loomwork/core";
+import type { Projection, ProjectionRuntime } from "./types";
+export interface InMemoryProjectionRuntimeConfig {
+    /**
+     * Coalesce subscriber notifications. When true, instead of notifying
+     * synchronously on every event, dirty keys are collected and flushed once per
+     * microtask with each projection's LATEST state. A streaming burst of N events
+     * (e.g. one LLM token per event) collapses from N subscriber calls to 1 per
+     * affected key, cutting downstream re-renders without changing final state.
+     *
+     * Off by default: notifications stay synchronous, preserving exact current
+     * semantics and adding zero overhead unless explicitly enabled.
+     */
+    coalesceNotifications?: boolean;
+    /**
+     * Bound how many distinct executions' projection states are retained (LRU by last touch).
+     * Prevents unbounded growth in a long-lived server: an execution evicted here reverts to
+     * `initialState` on the next `getState` (graceful). Default 10_000; set higher/lower to taste.
+     */
+    maxExecutions?: number;
+}
+export declare class InMemoryProjectionRuntime implements ProjectionRuntime {
+    private readonly projections;
+    private readonly states;
+    private readonly subscribers;
+    private readonly selectorSubscribers;
+    private readonly coalesce;
+    private readonly dirtyKeys;
+    private flushScheduled;
+    private readonly maxExecutions;
+    private readonly execOrder;
+    constructor(config?: InMemoryProjectionRuntimeConfig);
+    /** Drop all retained state + subscribers for an execution (e.g. after it completes). */
+    forget(executionId: string): void;
+    /** True if anything is currently subscribed to any projection of this execution. */
+    private hasSubscribers;
+    /**
+     * Drop an execution's retained STATE only — never its subscriber registries.
+     *
+     * The distinction is the whole point. `forget` is an explicit "this execution is done"
+     * from a caller who knows it; eviction is a cache decision the caller never made, and
+     * dropping a live subscriber's registry there does not degrade — it disconnects. The
+     * handler set is captured by closure in `subscribe`, so once the map entry is gone
+     * `notify` looks up a key that no longer exists and that subscriber never fires again.
+     */
+    private evictState;
+    private touch;
+    private stateKey;
+    register<TState>(projection: Projection<TState>): void;
+    getState<TState>(projectionId: string, executionId: string): TState;
+    subscribe<TState>(projectionId: string, executionId: string, handler: (state: TState) => void): () => void;
+    subscribeSelector<TState, TSlice>(projectionId: string, executionId: string, selector: (state: TState) => TSlice, handler: (slice: TSlice) => void, isEqual?: (a: TSlice, b: TSlice) => boolean): () => void;
+    private peekState;
+    handleEvent(event: EventEnvelope): void;
+    /** Fold one event into a projection's state via the matching handler, then notify. */
+    private apply;
+    seedState(projectionId: string, executionId: string, state: unknown): void;
+    /**
+     * ADR 0095 — the declared `version` of every registered projection that has one.
+     *
+     * Projections that declare nothing are ABSENT rather than present-and-empty: the caller
+     * compares this against what an artifact recorded, and a key mapped to `""` would compare
+     * equal to another empty declaration and read as a verified match.
+     */
+    pins(): Readonly<Record<string, string>>;
+    private notify;
+    private flush;
+    private emit;
+}
+//# sourceMappingURL=InMemoryProjectionRuntime.d.ts.map

package/dist/InMemoryProjectionRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryProjectionRuntime.d.ts","sourceRoot":"","sources":["../src/InMemoryProjectionRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAqB,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAkDhF,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoD;IAGhF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAE7E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAEzC,MAAM,CAAC,EAAE,+BAA+B;IAKpD,wFAAwF;IACxF,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAUjC,oFAAoF;IACpF,OAAO,CAAC,cAAc;IAQtB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,KAAK;IAqBb,OAAO,CAAC,QAAQ;IAIhB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI;IAkBtD,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAYnE,SAAS,CAAC,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/B,MAAM,IAAI;IAoBb,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAC9B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACnC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EAChC,OAAO,GAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAmB,GACrD,MAAM,IAAI;IA4Bb,OAAO,CAAC,SAAS;IAMjB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA4CvC,sFAAsF;IACtF,OAAO,CAAC,KAAK;IAsBb,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAM1E;;;;;;OAMG;IACH,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAUxC,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,IAAI;CAsBb"}

package/dist/InMemoryProjectionRuntime.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryProjectionRuntime = void 0;
+/**
+ * Cap on how many matching events a lazy projection buffers while its fold code loads. A local
+ * `import()` resolves in well under this window; exceeding it means the load is stuck or broken,
+ * so we stop buffering (the projection is a read-model, rebuildable from the log) rather than
+ * grow memory without bound. Generous so normal bursts never hit it.
+ */
+const LAZY_BUFFER_LIMIT = 10_000;
+/**
+ * How many least-recently-touched executions eviction will step over looking for an
+ * unsubscribed one. Bounds the per-event cost of `touch`; see its comment for why giving up
+ * (and sitting one entry over the cap) is the right failure direction.
+ */
+const EVICTION_SCAN_LIMIT = 64;
+class InMemoryProjectionRuntime {
+    projections = new Map();
+    states = new Map();
+    subscribers = new Map();
+    // Selector-subscribers, keyed like `subscribers`. Kept separate so whole-state
+    // subscription stays a zero-overhead fast path when no selector-subscribers exist.
+    selectorSubscribers = new Map();
+    coalesce;
+    dirtyKeys = new Set();
+    flushScheduled = false;
+    // Insertion order = LRU order over distinct executions, for the retention bound.
+    maxExecutions;
+    execOrder = new Map();
+    constructor(config) {
+        this.coalesce = config?.coalesceNotifications ?? false;
+        this.maxExecutions = config?.maxExecutions ?? 10_000;
+    }
+    /** Drop all retained state + subscribers for an execution (e.g. after it completes). */
+    forget(executionId) {
+        for (const projectionId of this.projections.keys()) {
+            const key = this.stateKey(projectionId, executionId);
+            this.states.delete(key);
+            this.subscribers.delete(key);
+            this.selectorSubscribers.delete(key);
+        }
+        this.execOrder.delete(executionId);
+    }
+    /** True if anything is currently subscribed to any projection of this execution. */
+    hasSubscribers(executionId) {
+        for (const projectionId of this.projections.keys()) {
+            const key = this.stateKey(projectionId, executionId);
+            if (this.subscribers.has(key) || this.selectorSubscribers.has(key))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Drop an execution's retained STATE only — never its subscriber registries.
+     *
+     * The distinction is the whole point. `forget` is an explicit "this execution is done"
+     * from a caller who knows it; eviction is a cache decision the caller never made, and
+     * dropping a live subscriber's registry there does not degrade — it disconnects. The
+     * handler set is captured by closure in `subscribe`, so once the map entry is gone
+     * `notify` looks up a key that no longer exists and that subscriber never fires again.
+     */
+    evictState(executionId) {
+        for (const projectionId of this.projections.keys()) {
+            this.states.delete(this.stateKey(projectionId, executionId));
+        }
+        this.execOrder.delete(executionId);
+    }
+    touch(executionId) {
+        this.execOrder.delete(executionId);
+        this.execOrder.set(executionId, true);
+        if (this.execOrder.size <= this.maxExecutions)
+            return;
+        // Evict least-recently-touched first, but SKIP anything with a live subscriber:
+        // evicting a state someone is folding into resets it to `initialState`, which is
+        // corruption rather than a cache miss (the same rule `AgentSurfaceRuntime` follows).
+        //
+        // The scan is bounded rather than exhaustive: if the oldest entries are all subscribed,
+        // giving up costs one over-cap entry, while scanning on would make `touch` — which runs
+        // once per event — O(retained). Over the cap is the safe direction; `forget` is the
+        // explicit remedy.
+        let examined = 0;
+        for (const candidate of this.execOrder.keys()) {
+            if (examined++ >= EVICTION_SCAN_LIMIT)
+                return;
+            if (this.hasSubscribers(candidate))
+                continue;
+            this.evictState(candidate);
+            return;
+        }
+    }
+    stateKey(projectionId, executionId) {
+        return `${projectionId}::${executionId}`;
+    }
+    register(projection) {
+        const active = {
+            id: projection.id,
+            initialState: projection.initialState,
+            ...(projection.version !== undefined && { version: projection.version }),
+            loading: false,
+            buffer: [],
+            ...(projection.handlers !== undefined && {
+                handlers: projection.handlers,
+            }),
+            ...(projection.lazy !== undefined && {
+                eventTypes: new Set(projection.lazy.eventTypes),
+                load: projection.lazy.load,
+            }),
+        };
+        this.projections.set(projection.id, active);
+    }
+    getState(projectionId, executionId) {
+        const key = this.stateKey(projectionId, executionId);
+        if (this.states.has(key)) {
+            return this.states.get(key);
+        }
+        const projection = this.projections.get(projectionId);
+        if (!projection) {
+            throw new Error(`Projection "${projectionId}" is not registered`);
+        }
+        return projection.initialState;
+    }
+    subscribe(projectionId, executionId, handler) {
+        const key = this.stateKey(projectionId, executionId);
+        if (!this.subscribers.has(key)) {
+            this.subscribers.set(key, new Set());
+        }
+        const handlers = this.subscribers.get(key);
+        const wrapper = (s) => handler(s);
+        handlers.add(wrapper);
+        return () => {
+            handlers.delete(wrapper);
+            // Only retire the map entry if it is still OUR set. After an explicit `forget`, a later
+            // subscriber installs a fresh set under the same key; without this identity check a
+            // stale unsubscribe would empty its own orphaned set and then delete the live one,
+            // silently disconnecting a subscriber that did nothing wrong.
+            if (handlers.size === 0 && this.subscribers.get(key) === handlers) {
+                this.subscribers.delete(key);
+            }
+        };
+    }
+    subscribeSelector(projectionId, executionId, selector, handler, isEqual = Object.is) {
+        const key = this.stateKey(projectionId, executionId);
+        let set = this.selectorSubscribers.get(key);
+        if (!set) {
+            set = new Set();
+            this.selectorSubscribers.set(key, set);
+        }
+        const sel = selector;
+        const entry = {
+            selector: sel,
+            isEqual: isEqual,
+            handler: handler,
+            // Seed from current state so change-only holds from the first event on.
+            last: sel(this.peekState(projectionId, executionId)),
+        };
+        set.add(entry);
+        return () => {
+            set.delete(entry);
+            // Same identity check as `subscribe` — never retire a set that is no longer ours.
+            if (set.size === 0 && this.selectorSubscribers.get(key) === set) {
+                this.selectorSubscribers.delete(key);
+            }
+        };
+    }
+    // Current state without throwing for an unregistered/unseen projection (unlike
+    // getState) — used to seed a selector-subscription's `last`. resolve-by-path
+    // selectors are null-safe, so an absent state seeds cleanly to `undefined`.
+    peekState(projectionId, executionId) {
+        const key = this.stateKey(projectionId, executionId);
+        if (this.states.has(key))
+            return this.states.get(key);
+        return this.projections.get(projectionId)?.initialState;
+    }
+    handleEvent(event) {
+        for (const [, projection] of this.projections) {
+            if (projection.handlers !== undefined) {
+                // Eager (or an already-loaded lazy) projection — fold synchronously as before.
+                this.apply(projection, projection.handlers, event);
+                continue;
+            }
+            // Lazy projection: gate on the compiler-recorded event types WITHOUT loading the
+            // fold code. A non-matching event never touches this projection (0 code loaded).
+            // A projection whose load already failed permanently is skipped (no buffer, no retry).
+            if (projection.loadFailed === true)
+                continue;
+            if (projection.eventTypes?.has(event.eventType) !== true)
+                continue;
+            // First matching event: buffer it (and any that arrive during load), kick the
+            // one-time import, and drain the buffer in arrival order once the code is ready.
+            // Bounded so a stuck/broken load can't grow the buffer without limit.
+            if (projection.buffer.length < LAZY_BUFFER_LIMIT)
+                projection.buffer.push(event);
+            if (!projection.loading) {
+                projection.loading = true;
+                projection.load()
+                    .then((handlers) => {
+                    projection.handlers = handlers;
+                    projection.eventTypes = undefined; // resolved — the eager path takes over
+                    projection.loading = false;
+                    const buffered = projection.buffer;
+                    projection.buffer = [];
+                    for (const buf of buffered)
+                        this.apply(projection, handlers, buf);
+                })
+                    .catch((err) => {
+                    // A chunk load failure is not transient (missing/broken module). Abandon the
+                    // projection: free the buffer and stop retrying, rather than leak memory and
+                    // re-import on every matching event. The read-model can be rebuilt from the log.
+                    projection.loading = false;
+                    projection.loadFailed = true;
+                    projection.buffer = [];
+                    console.warn(`[loom] projection "${projection.id}" failed to load its fold code — it will not update: ${String(err)}`);
+                });
+            }
+        }
+        this.touch(event.executionId);
+    }
+    /** Fold one event into a projection's state via the matching handler, then notify. */
+    apply(projection, handlers, event) {
+        // Own-key lookup: the fold map is user-authored and the event type is caller-controlled,
+        // so `handlers["__proto__"]` would resolve to `Object.prototype` — truthy, defeating the
+        // `!handler` guard, and then called as a function. Mirrors `getHandler` in @loomwork/replay-vm.
+        if (!Object.hasOwn(handlers, event.eventType))
+            return;
+        const handler = handlers[event.eventType];
+        if (typeof handler !== "function")
+            return;
+        const key = this.stateKey(projection.id, event.executionId);
+        // One `get` on the hot path (this runs per event per projection); `has` is consulted only
+        // in the rare case where the retained state is itself `undefined`.
+        const retained = this.states.get(key);
+        const currentState = retained !== undefined || this.states.has(key) ? retained : projection.initialState;
+        const nextState = handler(currentState, event);
+        this.states.set(key, nextState);
+        this.notify(key, nextState);
+    }
+    seedState(projectionId, executionId, state) {
+        const key = this.stateKey(projectionId, executionId);
+        this.states.set(key, state);
+        this.touch(executionId);
+    }
+    /**
+     * ADR 0095 — the declared `version` of every registered projection that has one.
+     *
+     * Projections that declare nothing are ABSENT rather than present-and-empty: the caller
+     * compares this against what an artifact recorded, and a key mapped to `""` would compare
+     * equal to another empty declaration and read as a verified match.
+     */
+    pins() {
+        // No prototype: a projection registered as `__proto__` would otherwise set one instead
+        // of adding a key, and vanish from every comparison without a finding.
+        const pins = Object.create(null);
+        for (const [id, projection] of this.projections) {
+            if (projection.version !== undefined)
+                pins[id] = projection.version;
+        }
+        return pins;
+    }
+    notify(key, state) {
+        if (!this.coalesce) {
+            this.emit(key, state);
+            return;
+        }
+        // Defer: mark dirty and flush once per microtask with the latest state.
+        this.dirtyKeys.add(key);
+        if (!this.flushScheduled) {
+            this.flushScheduled = true;
+            queueMicrotask(() => this.flush());
+        }
+    }
+    flush() {
+        this.flushScheduled = false;
+        const keys = Array.from(this.dirtyKeys);
+        this.dirtyKeys.clear();
+        for (const key of keys) {
+            // Read the current state so subscribers always see the latest value even
+            // when many events for the same key arrived within the batch.
+            this.emit(key, this.states.get(key));
+        }
+    }
+    emit(key, state) {
+        const handlers = this.subscribers.get(key);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(state);
+            }
+        }
+        // Selector-subscribers: recompute each slice against the latest state and fire
+        // only those whose slice actually changed — so an unrelated slice's update never
+        // wakes this subscriber. Snapshot the set so an unsubscribe during iteration
+        // (a handler tearing itself down) can't mutate the live set mid-loop.
+        const selectors = this.selectorSubscribers.get(key);
+        if (selectors) {
+            for (const entry of [...selectors]) {
+                const next = entry.selector(state);
+                if (!entry.isEqual(entry.last, next)) {
+                    entry.last = next;
+                    entry.handler(next);
+                }
+            }
+        }
+    }
+}
+exports.InMemoryProjectionRuntime = InMemoryProjectionRuntime;
+//# sourceMappingURL=InMemoryProjectionRuntime.js.map