@moltzap/client 2026.519.0 → 2026.519.1

package/dist/notification/stream.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Stream-returning constructors for `MoltZapWsClient.subscribe` and
+ * `MoltZapWsClient.subscribeAll` (Spec B, #596).
+ *
+ * Architect decision **AD1 — path (a)**: trust `Stream.async` cancellation
+ * to drive registry-stored `unregister` finalizer. The registry's
+ * `dispatch` snapshots `subsRef` at iteration start, so the spec #222
+ * §5.3 OQ-3 snapshot semantic is preserved by Ref atomicity without an
+ * additional per-sub cancelled-flag check (architect plan §3).
+ *
+ * Stream construction uses `Stream.async<DecodedNotification<D>, NotConnectedError>`
+ * with the registry storing typed callback references — NOT `Queue` of
+ * `Take` items combined with `Stream.fromQueue`/`Stream.flattenTake`,
+ * which codex empirically verified is racy under
+ * `Queue.offer(Take.fail); Queue.shutdown` and does not reliably propagate
+ * the typed failure to the consumer (architect plan §3.2, codex r4).
+ *
+ * Stream lifecycle (architect-mandated, spec §"Stream lifecycle contract"):
+ *   1. `subscribe(def)` returns a Stream value. Pure; no I/O, no scope.
+ *   2. Materialization opens the `Stream.async` source: `registry.register`
+ *      runs synchronously, callbacks are installed; consumer pulls suspend
+ *      until `emit.single` fires from dispatch.
+ *   3. Pre-`connect()` consumer pulls suspend inside `Stream.async`'s
+ *      internal queue. No `NotConnectedError` until terminal close.
+ *   4. Reconnect leaves registry callbacks intact; `subsRef` survives
+ *      transient disconnects (preserved invariant).
+ *   5. `MoltZapWsClient.close` invokes `SubscriberRegistry.closeAll`, which
+ *      calls each live `sub.onClose(new NotConnectedError(...))`. Each
+ *      `Stream.async`-backed consumer fails with `NotConnectedError`
+ *      via `emit.fail` deterministically (no Queue/shutdown race).
+ */
+import { Stream } from "effect";
+import { type AnyNotificationDefinition, type DecodedNotification, type NotConnectedError, type NotificationParamsOf } from "@moltzap/protocol";
+import type { SubscriberRegistry } from "../runtime/subscribers.js";
+/**
+ * Typed-payload subscribe. Returns a Stream of `DecodedNotification<D>`
+ * whose error channel is `NotConnectedError` and whose requirement set is
+ * `never` (the registry handle is bound at materialization time inside
+ * `Stream.async`'s register callback, so neither Scope nor any other
+ * requirement leaks to the consumer).
+ *
+ * `refinement` is a typed predicate over the definition's params. When the
+ * type-guard overload form is used, the Stream's payload narrows to
+ * `DecodedNotification<D, R>` via the optional `R` parameter on
+ * `DecodedNotification<D>`.
+ */
+export declare function subscribe<D extends AnyNotificationDefinition>(registry: SubscriberRegistry, definition: D, refinement?: (params: NotificationParamsOf<D>) => boolean): Stream.Stream<DecodedNotification<D>, NotConnectedError, never>;
+export declare function subscribe<D extends AnyNotificationDefinition, R extends NotificationParamsOf<D>>(registry: SubscriberRegistry, definition: D, refinement: (params: NotificationParamsOf<D>) => params is R): Stream.Stream<DecodedNotification<D, R>, NotConnectedError, never>;
+/**
+ * Broad-union escape hatch. The only intended in-tree consumer is
+ * `MoltZapService.connect`, which uses this to fan every inbound
+ * notification through `MoltZapService.handleNotification`. Payload
+ * narrowing is intentionally lost; callers wanting typed payloads use
+ * `subscribe(def, refinement?)`.
+ *
+ * The `subscribeAll` Stream uses a synthetic "match every definition"
+ * filter — implemented by the registry treating a `null` definition
+ * pointer as "match all", but for the Stream API we instead register
+ * one subscription per inbound frame's definition. Simpler: model
+ * "match all" by passing an in-band sentinel.
+ *
+ * Implementation: the registry has no native "match all" subscription
+ * shape (intentional — `subscribe<D>` is per-definition). To preserve
+ * the registry's typed dispatch surface, `subscribeAll` constructs a
+ * Stream that taps the registry via a per-arrival path: registering
+ * once with a sentinel definition would require a registry-level "match
+ * any" capability we deliberately avoid (would complicate the typed
+ * dispatch in subscribers.ts). Instead, the dispatcher feeds every
+ * frame to `subscribeAll`'s emit via a dedicated `subscribeAllRef`
+ * callback list maintained alongside `subsRef`.
+ *
+ * Architect-mandated code shape: per spec Goal #2 / plan §5.3, the
+ * surface returns a Stream value. Implementation passes the literal
+ * `AnyNotificationDefinition` sentinel via the registry's broad-union
+ * channel — see `notification/stream.ts → subscribeAllStream` below
+ * which registers via a new `SubscriberRegistry.registerAll` helper.
+ *
+ * To keep the registry minimal we route `subscribeAll` through a thin
+ * wrapper that the registry exposes as `registerAll(callbacks)` —
+ * identical lifecycle to `register(def, …)` but with no definition
+ * match (the dispatcher hits these callbacks for every inbound frame).
+ */
+export declare function subscribeAll(registry: SubscriberRegistry, refinement?: (notification: DecodedNotification<AnyNotificationDefinition>) => boolean): Stream.Stream<DecodedNotification<AnyNotificationDefinition>, NotConnectedError, never>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/notification/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/notification/stream.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,yBAAyB,EAC3D,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,CAAC,EACb,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,OAAO,GACxD,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;AACnE,wBAAgB,SAAS,CACvB,CAAC,SAAS,yBAAyB,EACnC,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,EAEjC,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,CAAC,EACb,UAAU,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,GAC3D,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;AAkCtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,CAAC,EAAE,CACX,YAAY,EAAE,mBAAmB,CAAC,yBAAyB,CAAC,KACzD,OAAO,GACX,MAAM,CAAC,MAAM,CACd,mBAAmB,CAAC,yBAAyB,CAAC,EAC9C,iBAAiB,EACjB,KAAK,CACN,CAmBA"}

package/dist/notification/stream.js

@@ -0,0 +1,106 @@
+/* eslint-disable jsdoc/text-escaping -- JSDoc references to generic types like `Stream.async<DecodedNotification<D>>` use the natural angle-bracket form (TS source style) inside backtick-fenced code spans; the lint rule's pre-render check fires false positives on these multi-line spans. Matches the precedent in filter-equivalence.test.ts. */
+/**
+ * Stream-returning constructors for `MoltZapWsClient.subscribe` and
+ * `MoltZapWsClient.subscribeAll` (Spec B, #596).
+ *
+ * Architect decision **AD1 — path (a)**: trust `Stream.async` cancellation
+ * to drive registry-stored `unregister` finalizer. The registry's
+ * `dispatch` snapshots `subsRef` at iteration start, so the spec #222
+ * §5.3 OQ-3 snapshot semantic is preserved by Ref atomicity without an
+ * additional per-sub cancelled-flag check (architect plan §3).
+ *
+ * Stream construction uses `Stream.async<DecodedNotification<D>, NotConnectedError>`
+ * with the registry storing typed callback references — NOT `Queue` of
+ * `Take` items combined with `Stream.fromQueue`/`Stream.flattenTake`,
+ * which codex empirically verified is racy under
+ * `Queue.offer(Take.fail); Queue.shutdown` and does not reliably propagate
+ * the typed failure to the consumer (architect plan §3.2, codex r4).
+ *
+ * Stream lifecycle (architect-mandated, spec §"Stream lifecycle contract"):
+ *   1. `subscribe(def)` returns a Stream value. Pure; no I/O, no scope.
+ *   2. Materialization opens the `Stream.async` source: `registry.register`
+ *      runs synchronously, callbacks are installed; consumer pulls suspend
+ *      until `emit.single` fires from dispatch.
+ *   3. Pre-`connect()` consumer pulls suspend inside `Stream.async`'s
+ *      internal queue. No `NotConnectedError` until terminal close.
+ *   4. Reconnect leaves registry callbacks intact; `subsRef` survives
+ *      transient disconnects (preserved invariant).
+ *   5. `MoltZapWsClient.close` invokes `SubscriberRegistry.closeAll`, which
+ *      calls each live `sub.onClose(new NotConnectedError(...))`. Each
+ *      `Stream.async`-backed consumer fails with `NotConnectedError`
+ *      via `emit.fail` deterministically (no Queue/shutdown race).
+ */
+import { Effect, Stream } from "effect";
+import {} from "@moltzap/protocol";
+export function subscribe(registry, definition, refinement) {
+    return Stream.async((emit) => {
+        // Synchronous registration — the registry stores the typed callbacks
+        // and returns an `unregister` Effect that the Stream's runtime will
+        // invoke as the cancellation finalizer. #ignore-sloppy-code[async-keyword]: comment references `Stream.async`, not a function modifier
+        //
+        // `register` is `Effect<SubscriptionHandle, never>`; `runSync` is safe
+        // because the registry mutates an in-memory `Ref` and never yields.
+        const handle = Effect.runSync(registry.register(definition, refinement, {
+            onFrame: (frame) => Effect.sync(() => {
+                emit.single(frame);
+            }),
+            onClose: (cause) => Effect.sync(() => {
+                emit.fail(cause);
+            }),
+        }));
+        // Per P3 issue #613: use `Effect.suspend` to defer running `unregister`
+        // to whenever the Stream's runtime invokes the finalizer Effect. This
+        // is future-proof if `unregister` ever grows yielded effects (e.g.
+        // flushing a queue); the `Effect.sync(() => Effect.runSync(handle.unregister))`
+        // form would force-eager-evaluate as sync.
+        return Effect.suspend(() => handle.unregister);
+    });
+}
+/**
+ * Broad-union escape hatch. The only intended in-tree consumer is
+ * `MoltZapService.connect`, which uses this to fan every inbound
+ * notification through `MoltZapService.handleNotification`. Payload
+ * narrowing is intentionally lost; callers wanting typed payloads use
+ * `subscribe(def, refinement?)`.
+ *
+ * The `subscribeAll` Stream uses a synthetic "match every definition"
+ * filter — implemented by the registry treating a `null` definition
+ * pointer as "match all", but for the Stream API we instead register
+ * one subscription per inbound frame's definition. Simpler: model
+ * "match all" by passing an in-band sentinel.
+ *
+ * Implementation: the registry has no native "match all" subscription
+ * shape (intentional — `subscribe<D>` is per-definition). To preserve
+ * the registry's typed dispatch surface, `subscribeAll` constructs a
+ * Stream that taps the registry via a per-arrival path: registering
+ * once with a sentinel definition would require a registry-level "match
+ * any" capability we deliberately avoid (would complicate the typed
+ * dispatch in subscribers.ts). Instead, the dispatcher feeds every
+ * frame to `subscribeAll`'s emit via a dedicated `subscribeAllRef`
+ * callback list maintained alongside `subsRef`.
+ *
+ * Architect-mandated code shape: per spec Goal #2 / plan §5.3, the
+ * surface returns a Stream value. Implementation passes the literal
+ * `AnyNotificationDefinition` sentinel via the registry's broad-union
+ * channel — see `notification/stream.ts → subscribeAllStream` below
+ * which registers via a new `SubscriberRegistry.registerAll` helper.
+ *
+ * To keep the registry minimal we route `subscribeAll` through a thin
+ * wrapper that the registry exposes as `registerAll(callbacks)` —
+ * identical lifecycle to `register(def, …)` but with no definition
+ * match (the dispatcher hits these callbacks for every inbound frame).
+ */
+export function subscribeAll(registry, refinement) {
+    return Stream.async((emit) => {
+        const handle = Effect.runSync(registry.registerAll(refinement, {
+            onFrame: (frame) => Effect.sync(() => {
+                emit.single(frame);
+            }),
+            onClose: (cause) => Effect.sync(() => {
+                emit.fail(cause);
+            }),
+        }));
+        return Effect.suspend(() => handle.unregister);
+    });
+}
+//# sourceMappingURL=stream.js.map

package/dist/notification/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/notification/stream.ts"],"names":[],"mappings":"AAAA,wVAAwV;AAExV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAKN,MAAM,mBAAmB,CAAC;AA6B3B,MAAM,UAAU,SAAS,CACvB,QAA4B,EAC5B,UAAa,EACb,UAAyD;IAEzD,OAAO,MAAM,CAAC,KAAK,CAA4C,CAAC,IAAI,EAAE,EAAE;QACtE,qEAAqE;QACrE,oEAAoE;QACpE,uIAAuI;QACvI,EAAE;QACF,uEAAuE;QACvE,oEAAoE;QACpE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAC3B,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE;YACxC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;gBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC;YACJ,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;gBACf,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC,CAAC;SACL,CAAC,CACH,CAAC;QACF,wEAAwE;QACxE,sEAAsE;QACtE,mEAAmE;QACnE,gFAAgF;QAChF,2CAA2C;QAC3C,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA4B,EAC5B,UAEY;IAMZ,OAAO,MAAM,CAAC,KAAK,CAGjB,CAAC,IAAI,EAAE,EAAE;QACT,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAC3B,QAAQ,CAAC,WAAW,CAAC,UAAU,EAAE;YAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;gBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC;YACJ,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;gBACf,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC,CAAC;SACL,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime/index.d.ts

@@ -1,11 +1,10 @@
 /**
  * @file Local-service IPC primitives and runtime helpers for the client CLI.
  *
- * The public surface is intentionally narrow: command definitions for the
- * local daemon socket and the subscription filter type consumed by status and
- * conformance adapters.
+ * Spec B (#596) deleted the three-field `SubscriptionFilter` re-export — the
+ * notification consumption surface is now Stream-based via
+ * `MoltZapWsClient.subscribe(def, refinement?)`.
  */
 export { LocalServiceCommands } from "./local-service-commands.js";
 export type { LocalServiceCommand } from "./local-service-commands.js";
-export type { SubscriptionFilter } from "./subscribers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/runtime/index.js

@@ -1,9 +1,9 @@
 /**
  * @file Local-service IPC primitives and runtime helpers for the client CLI.
  *
- * The public surface is intentionally narrow: command definitions for the
- * local daemon socket and the subscription filter type consumed by status and
- * conformance adapters.
+ * Spec B (#596) deleted the three-field `SubscriptionFilter` re-export — the
+ * notification consumption surface is now Stream-based via
+ * `MoltZapWsClient.subscribe(def, refinement?)`.
  */
 export { LocalServiceCommands } from "./local-service-commands.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/service-teardown.d.ts

@@ -0,0 +1,5 @@
+import { Effect, Scope } from "effect";
+export declare function composeServiceTeardown(serviceScope: Scope.CloseableScope | null, client: {
+    readonly close: () => Effect.Effect<void, never>;
+} | null): Effect.Effect<void, never>;
+//# sourceMappingURL=service-teardown.d.ts.map

package/dist/runtime/service-teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-teardown.d.ts","sourceRoot":"","sources":["../../src/runtime/service-teardown.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAQ,KAAK,EAAE,MAAM,QAAQ,CAAC;AA8B7C,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,EACzC,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;CAAE,GAAG,IAAI,GAClE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAQ5B"}

package/dist/runtime/service-teardown.js

@@ -0,0 +1,36 @@
+/* eslint-disable agent-code-guard/no-conditional-chaining -- composeServiceTeardown IS the resolution site for nullable scope+client inputs; the `closeXxxIfPresent` helpers each narrow their one nullable arg to a concrete `Effect`, so by the time `zipRight` runs every value is fully resolved. The rule fires on the parameter declarations (regarding them as "carriers"), but pushing the null-narrowing to every caller of `MoltZapService.close` would duplicate the conditional shape across the package. */
+import { Effect, Exit, Scope } from "effect";
+/**
+ * Build the close-order teardown Effect for `MoltZapService.close`:
+ * close the service-owned scope (which interrupts the
+ * `subscribeAll → Stream.runForEach` fan-out fiber) BEFORE invoking the
+ * ws-client's `close()`. Exposed as a top-level pure helper so the
+ * ordering can be exercised by a regression test without spinning up
+ * the full service. Codex r0 caught the original two-`runFork` race
+ * here; the regression test in `service.test.ts` pins the structural
+ * fix (P2-4 r1 cleanup).
+ *
+ * The chain is single-fork by construction (`Effect.zipRight`): the
+ * ws-client `close()` does not begin until the scope finalizer chain
+ * has completed.
+ */
+function closeScopeIfPresent(serviceScope) {
+    if (serviceScope === null)
+        return Effect.void;
+    return Scope.close(serviceScope, Exit.void);
+}
+function closeClientIfPresent(client) {
+    if (client === null)
+        return Effect.void;
+    return client.close();
+}
+export function composeServiceTeardown(serviceScope, client) {
+    // Resolve each optional input to a concrete Effect via the dedicated
+    // `closeXxxIfPresent` helpers, then sequence with `zipRight`. Single-fork
+    // sequencing: ws-client `close()` does not begin until the scope
+    // finalizer chain has completed.
+    const closeScope = closeScopeIfPresent(serviceScope);
+    const closeClient = closeClientIfPresent(client);
+    return closeScope.pipe(Effect.zipRight(closeClient));
+}
+//# sourceMappingURL=service-teardown.js.map

package/dist/runtime/service-teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-teardown.js","sourceRoot":"","sources":["../../src/runtime/service-teardown.ts"],"names":[],"mappings":"AAAA,yfAAyf;AACzf,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAC1B,YAAyC;IAEzC,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAAmE;IAEnE,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACxC,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,YAAyC,EACzC,MAAmE;IAEnE,qEAAqE;IACrE,0EAA0E;IAC1E,iEAAiE;IACjE,iCAAiC;IACjC,MAAM,UAAU,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/runtime/service-teardown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-teardown.test.d.ts.map

package/dist/runtime/service-teardown.test.d.ts.map

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

package/dist/runtime/service-teardown.test.js

@@ -0,0 +1,80 @@
+/**
+ * Spec B (#596) close-ordering regression test (P2-4 r1 cleanup).
+ *
+ * `MoltZapService.close` MUST close the service-owned scope (which holds
+ * the `subscribeAll → Stream.runForEach` fan-out fiber) BEFORE invoking
+ * the ws-client's `close()`. Codex r0 caught the original two-`runFork`
+ * race; the structural fix lives in `composeServiceTeardown` and these
+ * tests pin the ordering so a future refactor can't regress.
+ *
+ * `composeServiceTeardown` is a pure Effect producer: it composes the
+ * close chain but does NOT run it. The tests await the returned Effect
+ * via `yield*`, which means by the time we read `events` the chain has
+ * fully settled — no `Effect.runFork` race in the test harness either.
+ */
+/* eslint-disable agent-code-guard/finalizer-requires-scope -- scope is the test artifact closed explicitly via composeServiceTeardown(scope, ...); no enclosing Effect.scoped frame applies here by design */
+import { describe, expect, it } from "vitest";
+import { Effect, Scope } from "effect";
+import { composeServiceTeardown } from "./service-teardown.js";
+function makeRecorder() {
+    const events = [];
+    const fakeClient = {
+        close: () => Effect.sync(() => {
+            events.push("client");
+        }),
+    };
+    return { events, fakeClient };
+}
+function makeScopeRecorder(events) {
+    // Build a `Scope.CloseableScope` whose finalizer pushes "scope" — mirrors
+    // the runtime shape (the fan-out fiber is installed as a finalizer on
+    // `serviceScope` via `Effect.forkIn` in `MoltZapService.connect`). The
+    // scope is the artifact under test and is closed explicitly via
+    // `composeServiceTeardown`; no enclosing `Effect.scoped` is needed.
+    return Effect.gen(function* () {
+        const scope = yield* Scope.make();
+        yield* Scope.addFinalizer(scope, Effect.sync(() => {
+            events.push("scope");
+        }));
+        return scope;
+    });
+}
+function teardownOrderingCloses() {
+    return Effect.runPromise(Effect.gen(function* () {
+        const { events, fakeClient } = makeRecorder();
+        const scope = yield* makeScopeRecorder(events);
+        yield* composeServiceTeardown(scope, fakeClient);
+        expect(events).toEqual(["scope", "client"]);
+    }));
+}
+function teardownNullScopeRunsClient() {
+    return Effect.runPromise(Effect.gen(function* () {
+        const { events, fakeClient } = makeRecorder();
+        yield* composeServiceTeardown(null, fakeClient);
+        expect(events).toEqual(["client"]);
+    }));
+}
+function teardownNullClientClosesScope() {
+    return Effect.runPromise(Effect.gen(function* () {
+        const events = [];
+        const scope = yield* makeScopeRecorder(events);
+        yield* composeServiceTeardown(scope, null);
+        expect(events).toEqual(["scope"]);
+    }));
+}
+function teardownBothNullIsNoop() {
+    return Effect.runPromise(Effect.gen(function* () {
+        yield* composeServiceTeardown(null, null);
+        // The Effect completed without failing — that IS the assertion. The
+        // explicit expect anchors the test name; no value to compare beyond
+        // "no throw."
+        expect(true).toBe(true);
+    }));
+}
+describe("composeServiceTeardown — Spec B close ordering (P2-4)", () => {
+    it("closes service-owned scope BEFORE invoking ws-client.close()", teardownOrderingCloses);
+    it("tolerates null scope (calls only client.close())", teardownNullScopeRunsClient);
+    it("tolerates null client (closes only the scope)", teardownNullClientClosesScope);
+    it("no-op when both inputs are null", teardownBothNullIsNoop);
+});
+//# sourceMappingURL=service-teardown.test.js.map

package/dist/runtime/service-teardown.test.js.map

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

package/dist/runtime/subscribers.d.ts

@@ -1,166 +1,104 @@
 /**
  * Per-subscription notification registry for `MoltZapWsClient`.
  *
- * Responsibility: own the list of live `subscribe()` handles and fan each
- * inbound JSON-RPC notification out to every subscription whose filter matches.
- * Implements spec #222 §5.3 (C4 + the `RealClientEventSubscriber.subscribe`
- * filter stub). Lives as an internal collaborator of `MoltZapWsClient`;
- * the public types (`SubscriptionFilter`, `NotificationSubscription`,
- * `SubscriptionId`) re-export from the package barrel.
+ * Responsibility: own the list of live subscriptions and fan each inbound
+ * JSON-RPC notification out to every subscription whose definition (and
+ * optional typed refinement predicate) matches. Implements spec #596
+ * (notification consumption consolidation) via the AD1 path-(a) Stream.async
+ * design (architect plan §3, §5.5).
  *
- * Dispatch ordering (Invariant 6 — notifications delivered in arrival order):
- *   1. Inbound frames are handed to the registry in arrival order.
- *   2. Within a single frame, subscriptions are notified in registration
- *      order.
- *   3. There is no separate legacy `onNotification` fanout — spec #222 OQ-4 is
- *      resolved by DELETING `MoltZapWsClientOptions.onNotification`. Callers
- *      that want every notification register `subscribe({}, handler)` after
- *      construction and before `connect()`.
+ * Storage shape (post-Spec B):
+ *   - Subscriptions are records of typed `{onFrame, onClose}` callbacks
+ *     (NOT queues / Take items / Stream.fromQueue). `notification/stream.ts`
+ *     owns Stream construction via `Stream.async`; this module owns the
+ *     register/dispatch/closeAll lifecycle.
+ *   - The dispatch path snapshots `subsRef` at iteration start (AD1
+ *     snapshot-semantic contract from spec #222 §5.3 OQ-3 / spec #596
+ *     "Stream lifecycle contract" row).
+ *   - `closeAll` invokes each live sub's `onClose(new NotConnectedError(...))`
+ *     before clearing `subsRef` — deterministic typed-failure delivery
+ *     replaces the deleted `failAllNotificationWaiters` semantic.
  *
- * Unsubscribe semantics (OQ-3 A): `unsubscribe` takes effect on the next
- * frame. The registry snapshots its live-subscription list at the start
- * of each `dispatch` call; in-flight dispatch of frame N is not
- * interrupted by an unsubscribe during frame N. Frame N+1 observes the
- * unsubscribed state.
- *
- * Error channel: handlers are invoked inside a defect-catcher; a throw is
- * logged through Effect logging and swallowed (matching the prior
- * `onNotification` contract at `ws-client.ts:650-655` pre-deletion). The
- * registry itself has no typed error surface — `register`, `dispatch`, and
- * `closeAll` are `Effect<T, never>`.
+ * Filter grammar (post-Spec B):
+ *   - Subscription matches a frame iff `sub.definition === frame.definition`.
+ *   - Optional `refinement` is a typed predicate over the frame's params
+ *     (erased to the union type `ErasedNotificationRefinement` at the
+ *     storage boundary; consumers receive the typed-narrowed shape via
+ *     `Stream.async`'s typed `emit.single` callback inside
+ *     `notification/stream.ts`).
+ *   - The three-field `SubscriptionFilter` grammar is deleted (spec #596
+ *     Goal #3 + §"Acceptance criteria" delete sweep). Multi-definition
+ *     fan-out becomes `Stream.mergeAll([subscribe(d1), subscribe(d2)])`.
  */
 import { Brand, Effect } from "effect";
-import type { AnyNotificationDefinition, DecodedNotification } from "@moltzap/protocol";
-interface FilterableNotificationFrame {
-    readonly method: string;
-    readonly params?: unknown;
-}
+import { NotConnectedError, type AnyNotificationDefinition, type DecodedNotification, type NotificationParamsOf } from "@moltzap/protocol";
 /** Branded identifier for a subscription handle. Minted by `register`. */
-export type SubscriptionId = string & Brand.Brand<"SubscriptionId">;
+type SubscriptionId = string & Brand.Brand<"SubscriptionId">;
 /**
- * Filter grammar for `subscribe`. A notification is delivered to a subscription
- * iff it matches **every** field that is set on the filter. Unset fields
- * are wildcards; the empty filter `{}` matches every notification.
- *
- * OQ-2 resolution (A): exactly these three fields, no free-form
- * predicate, no schema-derived matcher. Matches the existing
- * `RealClientEventFilter` contract at
- * `packages/protocol/src/testing/conformance/client/runner.ts:104-116`
- * one-for-one.
- *
- *   - `emissionTag` — exact match against the canonical payload key
- *     `frame.params.__emissionTag`. (The adapter reads the same key at
- *     `packages/client/src/test-utils/conformance-adapter.ts:77-79`;
- *     `emitTaggedEventDefault` writes it at `runner.ts:343-357`. The
- *     `__emissionId` string in the `runner.ts:108` doc comment is a
- *     known doc-bug — architect files a follow-up issue against
- *     protocol to correct the comment; it is not the canonical name.)
- *   - `conversationId` — exact match against `frame.params.conversationId`
- *     when set on the notification payload.
- *   - `notificationNamePrefix` — `frame.method.startsWith(prefix)`.
+ * Per-subscription callback delivered each matching frame. Implemented in
+ * `notification/stream.ts` as `(frame) => Effect.sync(() => emit.single(frame))`.
+ * Returning `Effect<void, never>` keeps the dispatch path total — the
+ * Stream-side `emit.single` cannot fail synchronously.
  */
-export interface SubscriptionFilter {
-    readonly emissionTag?: string;
-    readonly conversationId?: string;
-    readonly notificationNamePrefix?: string;
-}
+type SubscriberFrameCallback = (frame: DecodedNotification<AnyNotificationDefinition>) => Effect.Effect<void, never>;
 /**
- * Handle returned by `register` / `MoltZapWsClient.subscribe`. Caller
- * holds the handle for its subscription's lifetime and runs
- * `unsubscribe` to stop delivery.
- *
- * `unsubscribe` is `Effect&lt;void, never>`: it is idempotent and total.
- * Calling `unsubscribe` a second time, or after `closeAll`, is a no-op.
+ * Per-subscription callback invoked exactly once when the client transitions
+ * to its terminal closed state. Implemented in `notification/stream.ts` as
+ * `(cause) => Effect.sync(() => emit.fail(cause))`.
  */
-export interface NotificationSubscription {
-    readonly id: SubscriptionId;
-    readonly unsubscribe: Effect.Effect<void, never>;
-}
+type SubscriberCloseCallback = (cause: NotConnectedError) => Effect.Effect<void, never>;
 /**
- * Per-subscription handler signature. Runs inside the registry's
- * dispatch fiber. Must not throw — throws are caught by the registry, logged,
- * and swallowed.
- *
- * The frame is a known-descriptor `DecodedNotification` (post-S9
- * fail-close: malformed / unknown-method frames are rejected before
- * dispatch). Handlers receive validated `params` typed as
- * `NotificationParamsOf&lt;D>` for the matching definition.
- *
- * Returning an `Effect` (not a plain `void`) lets handlers compose with
- * Effect-native downstream code without an extra runSync shim. The
- * registry awaits each handler's effect before moving to the next
- * subscription for this frame — fairness over throughput, so a slow
- * handler on subscription A does not reorder frames seen by
- * subscription B across frames.
+ * Handle returned by `register`. `unregister` is `Effect<void, never>`: it
+ * is idempotent and total. Calling `unregister` a second time, or after
+ * `closeAll`, is a no-op.
  */
-export type SubscriberHandler = (frame: DecodedNotification<AnyNotificationDefinition>) => Effect.Effect<void, never>;
+interface SubscriptionHandle {
+    readonly id: SubscriptionId;
+    readonly unregister: Effect.Effect<void, never>;
+}
 /**
  * Subscriber registry. One instance per `MoltZapWsClient`, created at
- * construction time and owned by the client. Not exported from the
- * package barrel — consumers reach the registry only through
- * `MoltZapWsClient.subscribe`.
+ * construction time and owned by the client.
+ *
+ * `register<D>` accepts typed `onFrame` / `onClose` callbacks for the
+ * specific definition `D`; internally the registry erases them to the
+ * `Subscriber{Frame,Close}Callback` union shape so a single iteration
+ * can dispatch over heterogeneous subscriptions without per-`D`
+ * dispatch tables.
  */
 export interface SubscriberRegistry {
+    readonly register: <D extends AnyNotificationDefinition>(definition: D, refinement: ((params: NotificationParamsOf<D>) => boolean) | undefined, callbacks: {
+        readonly onFrame: (frame: DecodedNotification<D>) => Effect.Effect<void, never>;
+        readonly onClose: SubscriberCloseCallback;
+    }) => Effect.Effect<SubscriptionHandle, never>;
     /**
-     * Add a subscription. Returns the handle immediately; delivery starts
-     * with the next frame passed to `dispatch`. Does not await any
-     * connection state — subscribe is legal pre-connect (spec §5.3 +
-     * Assumption 1 deletion: post-delete of `onNotification`, subscribe is the
-     * only pre-connect notification hook).
+     * `subscribeAll` surface (spec #596 Goal #2). Registers a broad-union
+     * subscription that fires for every inbound frame regardless of
+     * definition. The optional `refinement` predicate runs against the
+     * full `DecodedNotification<AnyNotificationDefinition>` shape.
+     *
+     * Stored in a sibling `subsAllRef` list — kept off `subsRef` so the
+     * per-definition dispatch loop in `dispatch` stays a simple
+     * `definition ===` check without a per-sub broad-union escape branch.
      */
-    readonly register: (filter: SubscriptionFilter, handler: SubscriberHandler) => Effect.Effect<NotificationSubscription, never>;
+    readonly registerAll: (refinement: ((notification: DecodedNotification<AnyNotificationDefinition>) => boolean) | undefined, callbacks: {
+        readonly onFrame: SubscriberFrameCallback;
+        readonly onClose: SubscriberCloseCallback;
+    }) => Effect.Effect<SubscriptionHandle, never>;
     /**
-     * Fan an inbound notification out to every matching subscription. Called by
-     * `MoltZapWsClient.handleIncoming` at the existing notification-dispatch
-     * point (`ws-client.ts:649-685`). Implementation snapshots the
-     * live-subscription list at the start of dispatch so
-     * unsubscribe-during-dispatch observes next-frame semantics (OQ-3 A).
-     *
-     * Frames are pre-validation (`DecodedNotification&lt;AnyNotificationDefinition>` union) — the
-     * type-system contract that subscribers see RAW frames, not the lifted
-     * `DecodedNotification&lt;D>` shape that typed handlers see.
-     *
-     * Dispatch order: registration order, iterated sequentially; slow
-     * handlers block later subscriptions for this frame but never
-     * reorder frame N relative to frame N+1.
+     * Fan an inbound notification out to every matching subscription. Called
+     * from `MoltZapWsClient.handleDecodedNotification`. Snapshot semantic:
+     * unsubscribes that commit mid-dispatch observe NEXT-frame semantics
+     * (AD1 path-(a) contract).
      */
     readonly dispatch: (frame: DecodedNotification<AnyNotificationDefinition>) => Effect.Effect<void, never>;
     /**
-     * Drop every live subscription. Called from `MoltZapWsClient.close`
-     * so handlers stop firing once the client is torn down. Idempotent.
+     * Terminal close. Invokes every live sub's `onClose` callback (which
+     * `emit.fail(cause)`s the corresponding consumer Stream), then clears
+     * both `subsRef` and `subsAllRef`. Idempotent.
      */
     readonly closeAll: Effect.Effect<void, never>;
 }
-/**
- * Construct an empty registry. Called once from the `MoltZapWsClient`
- * constructor.
- *
- * Implementation notes:
- *   - Live subscriptions are stored in a `Ref&lt;ReadonlyArray&lt;…>>` keyed
- *     by registration order. Append-on-register, filter-on-unsubscribe
- *     keeps the dispatch path O(N) with N = live subscription count.
- *     Bigger structures aren't justified at the expected sub count
- *     (≤ ~10 per fixture).
- *   - `dispatch` snapshots the array at start (OQ-3 A). An
- *     `unsubscribe` mid-dispatch mutates the Ref but the in-flight
- *     iteration walks the snapshot.
- *   - Handler exceptions are caught with `Effect.catchAllDefect` after
- *     the handler Effect. Sync `throw` from a `(frame) => …` body
- *     surfaces as a defect; we log + swallow to match the pre-deletion
- *     `onNotification` contract.
- */
 export declare function makeSubscriberRegistry(): Effect.Effect<SubscriberRegistry, never>;
-/**
- * Pure filter-match predicate. Exposed for unit testing so executable
- * client-side divergence proofs can force known-bad subscription
- * behavior without bypassing the production dispatch path.
- *
- * Returns `true` iff `frame` matches every set field on `filter`:
- *   - `filter.emissionTag === frame.params.__emissionTag` (strict ===)
- *   - `filter.conversationId === frame.params.conversationId` (strict ===)
- *   - `frame.method.startsWith(filter.notificationNamePrefix)`
- * Unset filter fields are wildcards.
- */
-export declare function matchesFilter(filter: SubscriptionFilter, frame: FilterableNotificationFrame): boolean;
 export {};
 //# sourceMappingURL=subscribers.d.ts.map