@kronos-ts/messaging 0.1.1 → 0.2.0

package/dist/subscription-filter.js

@@ -0,0 +1,71 @@
+/**
+ * Helper that builds a structured filter from a partial payload.
+ *
+ * ```ts
+ * emitUpdate(GetCourseView, payloadEquals({ courseId: e.courseId }), view)
+ * ```
+ *
+ * Prefer this over a function filter when you want updates to fan out across
+ * a distributed query bus.
+ */
+export function payloadEquals(partial) {
+    return { payloadEquals: partial };
+}
+/** Evaluate a {@link SubscriptionFilter} against a payload. */
+export function applySubscriptionFilter(filter, payload) {
+    if (typeof filter === "function")
+        return filter(payload);
+    return matchesPayloadEquals(payload, filter.payloadEquals);
+}
+/** Extract the structured form, if any, for serialization across a transport. */
+export function extractStructuredFilter(filter) {
+    if (!filter)
+        return undefined;
+    if (typeof filter === "function")
+        return undefined;
+    return filter;
+}
+/** Deep equality on the keys defined in `expected`. */
+export function matchesPayloadEquals(payload, expected) {
+    if (payload === null || typeof payload !== "object") {
+        return Object.keys(expected).length === 0;
+    }
+    for (const key of Object.keys(expected)) {
+        if (!deepEqual(payload[key], expected[key]))
+            return false;
+    }
+    return true;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const aKeys = Object.keys(ao);
+    const bKeys = Object.keys(bo);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!deepEqual(ao[key], bo[key]))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=subscription-filter.js.map

package/dist/subscription-filter.js.map

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

package/dist/transaction.d.ts

@@ -57,4 +57,35 @@ export declare function getActiveTransaction<T = unknown>(): T | undefined;
  * Migration) can rename if the kronos() app API warrants.
  */
 export declare function transactionalUnitOfWorkFactory<T>(delegate: UoWRunner, txManager: TransactionManager<T>): UoWRunner;
+/**
+ * Lazy variant of {@link transactionalUnitOfWorkFactory}.
+ *
+ * Unlike the eager factory, no transaction is begun on UoW entry. Instead,
+ * a factory is installed in the UoW that opens the tx on the first call to
+ * {@link getOrBeginActiveTransaction}. Pure-read UoWs that never request a
+ * tx pay zero begin/commit cost and never claim a connection from the pool.
+ *
+ * On first request: the tx is begun, stored in {@link TRANSACTION_KEY},
+ * and commit/rollback hooks are registered. Subsequent requests within
+ * the same UoW return the cached tx — there is exactly one tx per UoW.
+ *
+ * Components that may write to the underlying store (event stores,
+ * schedulers, ORM integrations) reach the tx via
+ * {@link getOrBeginActiveTransaction}; read-only paths use
+ * {@link getActiveTransaction} so they observe an existing tx but do not
+ * provoke one to open.
+ */
+export declare function lazyTransactionalUnitOfWorkFactory<T>(delegate: UoWRunner, txManager: TransactionManager<T>): UoWRunner;
+/**
+ * Return the active UoW transaction, opening it if a lazy factory is
+ * installed and no tx has been begun yet. Returns the cached tx on
+ * subsequent calls within the same UoW.
+ *
+ * Returns `undefined` when no UoW is active OR when an active UoW has
+ * neither an existing tx nor a lazy factory installed (e.g., the app
+ * doesn't compose a TransactionManager). Callers that need a tx must
+ * decide what to do with `undefined` — typically fall back to opening
+ * an ad-hoc tx on their own driver.
+ */
+export declare function getOrBeginActiveTransaction<T = unknown>(): Promise<T | undefined>;
 //# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAQjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IACnB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAM/D;AAED,uGAAuG;AACvG,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,OAAO,CAA8B,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAC9C,QAAQ,EAAE,SAAS,EACnB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,SAAS,CAcX"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAQjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAclD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IACnB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAM/D;AAED,uGAAuG;AACvG,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,OAAO,CAA8B,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAC9C,QAAQ,EAAE,SAAS,EACnB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,SAAS,CAcX;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kCAAkC,CAAC,CAAC,EAClD,QAAQ,EAAE,SAAS,EACnB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,SAAS,CA0BX;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAUvF"}

package/dist/transaction.js

@@ -1,5 +1,16 @@
 import { resourceKey } from "@kronos-ts/common";
 import { processingStateStorage, setResource, on, onError, Phase, } from "./processing-state.js";
+/**
+ * Resource key holding a deferred-begin factory installed by
+ * {@link lazyTransactionalUnitOfWorkFactory}. The factory begins the tx on
+ * first call, registers commit/rollback hooks on the UoW, caches the
+ * resulting tx in {@link TRANSACTION_KEY}, and returns it. Subsequent calls
+ * return the cached tx without a re-begin.
+ *
+ * NOT exported from the package barrel — components reach the lazily-begun
+ * tx through {@link getOrBeginActiveTransaction}.
+ */
+const LAZY_TX_FACTORY_KEY = resourceKey("lazyTxFactory");
 /**
  * A no-op transaction manager for when no database transactions are needed.
  */
@@ -71,4 +82,73 @@ export function transactionalUnitOfWorkFactory(delegate, txManager) {
         });
     };
 }
+/**
+ * Lazy variant of {@link transactionalUnitOfWorkFactory}.
+ *
+ * Unlike the eager factory, no transaction is begun on UoW entry. Instead,
+ * a factory is installed in the UoW that opens the tx on the first call to
+ * {@link getOrBeginActiveTransaction}. Pure-read UoWs that never request a
+ * tx pay zero begin/commit cost and never claim a connection from the pool.
+ *
+ * On first request: the tx is begun, stored in {@link TRANSACTION_KEY},
+ * and commit/rollback hooks are registered. Subsequent requests within
+ * the same UoW return the cached tx — there is exactly one tx per UoW.
+ *
+ * Components that may write to the underlying store (event stores,
+ * schedulers, ORM integrations) reach the tx via
+ * {@link getOrBeginActiveTransaction}; read-only paths use
+ * {@link getActiveTransaction} so they observe an existing tx but do not
+ * provoke one to open.
+ */
+export function lazyTransactionalUnitOfWorkFactory(delegate, txManager) {
+    return async (metadata, action) => {
+        return delegate(metadata, async () => {
+            let tx;
+            let committed = false;
+            const factory = async () => {
+                if (tx !== undefined)
+                    return tx;
+                tx = await txManager.begin();
+                setResource(TRANSACTION_KEY, tx);
+                on(Phase.COMMIT, async () => {
+                    if (tx === undefined)
+                        return;
+                    await txManager.commit(tx);
+                    committed = true;
+                });
+                onError(async () => {
+                    if (tx === undefined || committed)
+                        return;
+                    await txManager.rollback(tx);
+                });
+                return tx;
+            };
+            setResource(LAZY_TX_FACTORY_KEY, factory);
+            return action();
+        });
+    };
+}
+/**
+ * Return the active UoW transaction, opening it if a lazy factory is
+ * installed and no tx has been begun yet. Returns the cached tx on
+ * subsequent calls within the same UoW.
+ *
+ * Returns `undefined` when no UoW is active OR when an active UoW has
+ * neither an existing tx nor a lazy factory installed (e.g., the app
+ * doesn't compose a TransactionManager). Callers that need a tx must
+ * decide what to do with `undefined` — typically fall back to opening
+ * an ad-hoc tx on their own driver.
+ */
+export async function getOrBeginActiveTransaction() {
+    const state = processingStateStorage.getStore();
+    if (!state)
+        return undefined;
+    const existing = state.resources.get(TRANSACTION_KEY.symbol);
+    if (existing !== undefined)
+        return existing;
+    const factory = state.resources.get(LAZY_TX_FACTORY_KEY.symbol);
+    if (factory === undefined)
+        return undefined;
+    return await factory();
+}
 //# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,mBAAmB,CAAA;AACjE,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,EAAE,EACF,OAAO,EACP,KAAK,GACN,MAAM,uBAAuB,CAAA;AAe9B;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;QACrB,MAAM,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;QACtB,QAAQ,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;KACzB,CAAA;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,MAAM,eAAe,GAAyB,WAAW,CAAC,aAAa,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,EAAE,CAAA;IAC/C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,OAAO,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,MAAM,CAAkB,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAmB,EACnB,SAAgC;IAEhC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE;QAChC,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,CAAA;QAClC,OAAO,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnC,WAAW,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;YAChC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;gBAC1B,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAC5B,CAAC,CAAC,CAAA;YACF,OAAO,CAAC,KAAK,IAAI,EAAE;gBACjB,MAAM,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YAC9B,CAAC,CAAC,CAAA;YACF,OAAO,MAAM,EAAE,CAAA;QACjB,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/messaging",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Messaging primitives for Kronos — commands, events, handlers, and event processors.",
   "license": "Apache-2.0",
   "type": "module",

package/src/emit-update.ts

@@ -3,12 +3,13 @@ import { resourceKey, qualifiedNameToString, type ResourceKey } from "@kronos-ts
 import { requireInvocationPhase } from "./processing-state.js"
 import type { QueryBus } from "./query-bus.js"
 import type { QueryDescriptor } from "./descriptor.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
 
 /** Emit a subscription-query update from within the current processing context. */
 export interface EmitUpdateFunction {
   <Q extends z.ZodType>(
     query: QueryDescriptor<Q>,
-    filter: (query: z.infer<Q>) => boolean,
+    filter: SubscriptionFilter<z.infer<Q>>,
     update: unknown,
   ): void
 }
@@ -31,5 +32,5 @@ export const emitUpdate: EmitUpdateFunction = (queryDescriptor, filter, update)
   const bus = state.resources.get(QUERY_BUS_KEY.symbol) as QueryBus | undefined
   if (!bus) throw new Error("No query bus configured")
   const queryName = qualifiedNameToString(queryDescriptor.name)
-  bus.emitUpdate(queryName, filter as (q: unknown) => boolean, update)
+  bus.emitUpdate(queryName, filter as SubscriptionFilter, update)
 }

package/src/event-scheduler.ts

@@ -0,0 +1,96 @@
+/**
+ * EventScheduler — schedule an event to be appended to the event store at
+ * a future time, with the option to cancel before the fire-time.
+ *
+ * # Semantics
+ *
+ * - `schedule(event, at)` MUST be called from inside a UnitOfWork (i.e.,
+ *   from a command/event/query handler, or any code that opened a UoW
+ *   via `runInNewUoW`). The scheduled record participates in the active
+ *   UoW transaction: if the UoW rolls back, the schedule is not persisted;
+ *   if the UoW commits, the schedule is durably stored.
+ *
+ * - Once the schedule is committed, the implementation guarantees that the
+ *   event WILL be appended to the event store at or after `at`, unless
+ *   {@link EventScheduler.cancel} is called and succeeds before the
+ *   fire-time. "At or after" because workers poll on an interval — fire
+ *   times are not real-time deadlines.
+ *
+ * - `cancel(token)` returns a {@link CancelResult} discriminated union so
+ *   callers can branch on three distinct outcomes: the schedule was
+ *   cancelled before firing, the event had already been appended (too
+ *   late), or no such schedule exists (already-cancelled, never-existed,
+ *   or token from a different deployment).
+ *
+ * - Cancel is also UoW-aware: when called inside a UoW, it participates
+ *   in the active tx so a handler that cancels and then throws does NOT
+ *   leave the schedule cancelled. When called outside any UoW (rare —
+ *   typically an ops/admin path), it commits standalone.
+ *
+ * # Calling from handlers
+ *
+ * Implementations resolve themselves from the active UoW's resources
+ * (similar to {@link send} and {@link emitUpdate}), so handler code uses
+ * the scheduler the framework configured for it. The interface itself
+ * is transport-agnostic — postgres and in-memory implementations live
+ * in their respective packages.
+ *
+ * # NOT what this is
+ *
+ * - This is NOT a command scheduler. AF5 schedules events, not commands;
+ *   if you want a command to run later, schedule an event and run an
+ *   automation processor that turns the event into a command on receipt.
+ * - This is NOT a cron / recurring scheduler. Each `schedule()` produces
+ *   a single one-shot fire.
+ */
+
+import type { EventMessage } from "./message.js"
+
+/**
+ * Opaque handle returned by {@link EventScheduler.schedule}. Pass back to
+ * {@link EventScheduler.cancel} to attempt cancellation. Tokens are
+ * implementation-specific (postgres uses the row PK; in-memory uses a
+ * UUID) but always carry a stable `id`.
+ */
+export interface ScheduleToken {
+  readonly id: string
+}
+
+/**
+ * Outcome of {@link EventScheduler.cancel}.
+ *
+ * - `cancelled`        — the schedule existed in `pending` state and was
+ *                        successfully marked `cancelled`. Event will NOT
+ *                        be appended.
+ * - `already-appended` — a worker already fired this schedule; the event
+ *                        is in the event store. Caller decides whether
+ *                        compensation is needed.
+ * - `not-found`        — no row matches the token. Could mean: already
+ *                        cancelled, never existed, or wrong store. Caller
+ *                        usually treats this as a no-op.
+ */
+export type CancelResult =
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "already-appended" }
+  | { readonly kind: "not-found" }
+
+export interface EventScheduler {
+  /**
+   * Schedule {@link event} for append at {@link at}. Must be called inside
+   * a UoW; throws otherwise. The schedule participates in the active UoW
+   * tx and is only durable once the UoW commits.
+   *
+   * `at` is the wall-clock fire-time. Past dates are valid — they cause
+   * the worker to fire the schedule on its next poll.
+   */
+  schedule(event: EventMessage, at: Date): Promise<ScheduleToken>
+
+  /**
+   * Attempt to cancel a pending schedule. See {@link CancelResult} for
+   * the three possible outcomes.
+   *
+   * Safe to call from inside a UoW (joins the active tx) or outside
+   * (commits standalone).
+   */
+  cancel(token: ScheduleToken): Promise<CancelResult>
+}

package/src/in-memory-event-scheduler.ts

@@ -0,0 +1,150 @@
+/**
+ * In-memory {@link EventScheduler} — intended for tests only.
+ *
+ * Backed by a `Map<scheduleId, record>` and `setTimeout`. Publishes fired
+ * events through a supplied {@link EventSink} (typically the in-memory
+ * event bus or a test spy).
+ *
+ * # UoW semantics (best-effort, test-grade)
+ *
+ * - `schedule()` must be called inside a UoW (INVOCATION phase). The
+ *   record is staged immediately so cancel() inside the SAME UoW sees it,
+ *   but the `setTimeout` arming is deferred to AFTER_COMMIT — so if the
+ *   UoW rolls back the schedule never fires. `onError` cleans the staged
+ *   record so callers see `not-found` on the rolled-back token.
+ *
+ * - `cancel()` may be called inside or outside a UoW. State change is
+ *   applied immediately for caller-visibility; this means a UoW that
+ *   cancels and then rolls back does NOT restore the schedule. This
+ *   differs from the postgres implementation (which is true
+ *   transactional) and is acceptable for the in-memory's test-only
+ *   remit. Document this when writing tests that depend on cancel
+ *   rollback semantics — use the postgres scheduler for that.
+ *
+ * # NOT production
+ *
+ * No persistence, no recovery on restart, no at-least-once. A test-only
+ * spy with a real-enough surface to exercise framework wiring.
+ */
+
+import type { EventMessage } from "./message.js"
+import type { EventSink } from "./event-sink.js"
+import type { EventScheduler, ScheduleToken, CancelResult } from "./event-scheduler.js"
+import {
+  requireInvocationPhase,
+  onAfterCommit,
+  onError,
+  processingStateStorage,
+} from "./processing-state.js"
+import { generateIdentifier } from "@kronos-ts/common"
+
+type RecordStatus = "pending" | "appended" | "cancelled"
+
+interface ScheduleRecord {
+  status: RecordStatus
+  event: EventMessage
+  fireAt: number
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export interface InMemoryEventSchedulerOptions {
+  readonly eventSink: EventSink
+  /** Override `Date.now` for deterministic tests. Defaults to `Date.now`. */
+  readonly now?: () => number
+}
+
+export interface InMemoryEventScheduler extends EventScheduler {
+  /**
+   * Cancel any armed timers and drop all internal state. Tests call this
+   * in `afterEach` to ensure schedulers from one test do not fire into
+   * another. Not part of the public {@link EventScheduler} contract.
+   */
+  stop(): Promise<void>
+}
+
+export function createInMemoryEventScheduler(
+  options: InMemoryEventSchedulerOptions,
+): InMemoryEventScheduler {
+  const { eventSink } = options
+  const now = options.now ?? Date.now
+  const records = new Map<string, ScheduleRecord>()
+
+  function armTimer(id: string, record: ScheduleRecord): void {
+    const delay = Math.max(0, record.fireAt - now())
+    record.timer = setTimeout(() => {
+      const rec = records.get(id)
+      if (!rec || rec.status !== "pending") return
+      rec.status = "appended"
+      rec.timer = undefined
+      eventSink.publish([rec.event]).catch((err) => {
+        // Test-only: surface but do not crash the process. Real
+        // implementations need an at-least-once retry; not modelled here.
+        console.warn("inMemoryEventScheduler: publish failed:", err)
+      })
+    }, delay)
+  }
+
+  return {
+    async schedule(event: EventMessage, at: Date): Promise<ScheduleToken> {
+      requireInvocationPhase()
+
+      const id = generateIdentifier()
+      const record: ScheduleRecord = {
+        status: "pending",
+        event,
+        fireAt: at.getTime(),
+      }
+      records.set(id, record)
+
+      onAfterCommit(() => {
+        const rec = records.get(id)
+        if (!rec || rec.status !== "pending") return
+        armTimer(id, rec)
+      })
+
+      onError(() => {
+        // Roll back the staged record so post-rollback cancel() sees
+        // `not-found` rather than `cancelled`.
+        const rec = records.get(id)
+        if (rec && rec.status === "pending") records.delete(id)
+      })
+
+      return { id }
+    },
+
+    async cancel(token: ScheduleToken): Promise<CancelResult> {
+      const rec = records.get(token.id)
+      if (!rec) return { kind: "not-found" }
+      if (rec.status === "appended") return { kind: "already-appended" }
+      if (rec.status === "cancelled") return { kind: "not-found" }
+
+      rec.status = "cancelled"
+      if (rec.timer !== undefined) {
+        clearTimeout(rec.timer)
+        rec.timer = undefined
+      }
+
+      // Best-effort UoW participation: if we're inside a UoW that later
+      // errors, revert the cancel so the schedule's pending state
+      // re-materialises. The original timer (if it was armed) has already
+      // been cleared — the AFTER_COMMIT re-arm cycle is not re-driven
+      // here, which means a cancel + rollback inside a post-commit window
+      // would not re-fire. Acceptable for the in-memory's test-only remit.
+      if (processingStateStorage.getStore() !== undefined) {
+        onError(() => {
+          const r = records.get(token.id)
+          if (r && r.status === "cancelled") r.status = "pending"
+        })
+      }
+
+      return { kind: "cancelled" }
+    },
+
+    async stop(): Promise<void> {
+      for (const rec of records.values()) {
+        if (rec.timer !== undefined) clearTimeout(rec.timer)
+      }
+      records.clear()
+    },
+  }
+}

package/src/index.ts

@@ -145,6 +145,14 @@ export {
   runAfterCommitOrImmediately,
 } from "./subscription-query.js"
 
+export {
+  type SubscriptionFilter,
+  payloadEquals,
+  applySubscriptionFilter,
+  extractStructuredFilter,
+  matchesPayloadEquals,
+} from "./subscription-filter.js"
+
 // Event sink (publish-only)
 export { type EventSink } from "./event-sink.js"
 
@@ -237,7 +245,9 @@ export {
   type TransactionManager,
   noTransactionManager,
   getActiveTransaction,
+  getOrBeginActiveTransaction,
   transactionalUnitOfWorkFactory,
+  lazyTransactionalUnitOfWorkFactory,
   TRANSACTION_KEY,
 } from "./transaction.js"
 
@@ -252,6 +262,18 @@ export {
 export { send, COMMAND_BUS_KEY } from "./send.js"
 export { emitUpdate, QUERY_BUS_KEY } from "./emit-update.js"
 
+// Event scheduling
+export {
+  type EventScheduler,
+  type ScheduleToken,
+  type CancelResult,
+} from "./event-scheduler.js"
+export {
+  type InMemoryEventScheduler,
+  type InMemoryEventSchedulerOptions,
+  createInMemoryEventScheduler,
+} from "./in-memory-event-scheduler.js"
+
 // Modules — Plan 08-03a (D-82): function-style helpers replace Module-shape factories
 export {
   registerCommandHandlersNatively,

package/src/intercepting-query-bus.ts

@@ -1,6 +1,7 @@
 import type { QueryBus } from "./query-bus.js"
 import type { QueryMessage } from "./message.js"
 import type { SubscriptionQueryResult } from "./subscription-query.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
 import type { DispatchInterceptor, HandlerInterceptor } from "./interceptor.js"
 
 /**
@@ -64,7 +65,7 @@ export function createInterceptingQueryBus(
 
     emitUpdate(
       queryName: string,
-      filter: (queryPayload: unknown) => boolean,
+      filter: SubscriptionFilter,
       update: unknown,
     ): Promise<void> {
       return delegate.emitUpdate(queryName, filter, update)
@@ -72,7 +73,7 @@ export function createInterceptingQueryBus(
 
     completeSubscription(
       queryName: string,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       return delegate.completeSubscription(queryName, filter)
     },
@@ -80,7 +81,7 @@ export function createInterceptingQueryBus(
     completeSubscriptionExceptionally(
       queryName: string,
       error: Error,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       return delegate.completeSubscriptionExceptionally(queryName, error, filter)
     },

package/src/query-bus.ts

@@ -1,5 +1,6 @@
 import type { QueryMessage } from "./message.js"
 import type { SubscriptionQueryResult } from "./subscription-query.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
 
 /**
  * The query bus — low-level infrastructure for dispatching query messages.
@@ -43,10 +44,14 @@ export interface QueryBus {
    * Emit an update to all active subscription queries matching the filter.
    * When called within an active UnitOfWork (detected via ALS), the update is
    * deferred to AFTER_COMMIT.
+   *
+   * The filter can be either a function (local-only when a distributed bus is
+   * in use) or a structured `payloadEquals` predicate (crosses transports).
+   * See {@link SubscriptionFilter}.
    */
   emitUpdate(
     queryName: string,
-    filter: (queryPayload: unknown) => boolean,
+    filter: SubscriptionFilter,
     update: unknown,
   ): Promise<void>
 
@@ -55,7 +60,7 @@ export interface QueryBus {
    */
   completeSubscription(
     queryName: string,
-    filter?: (queryPayload: unknown) => boolean,
+    filter?: SubscriptionFilter,
   ): Promise<void>
 
   /**
@@ -64,6 +69,6 @@ export interface QueryBus {
   completeSubscriptionExceptionally(
     queryName: string,
     error: Error,
-    filter?: (queryPayload: unknown) => boolean,
+    filter?: SubscriptionFilter,
   ): Promise<void>
 }