@house-rules/event-log 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# @house-rules/event-log: notes for agents
+
+EventLog is a generic domain-event transport. It owns no kinds. It is not call-audit, which records feature starts and refusals. Read `README.md` for mounting.
+
+## Mount and record
+
+Mount `{ ...EventLogMount, layer: EventLog.layerPostgres(options) }` in composition/modules.ts. Provide the shared PgClient and `sqlUnitOfWork` over that same client. Tests may use `layerMemory(options)` with `memoryUnitOfWork`. Raw `EventLog.layer(options)` needs EventStore. Register `{ "workspace": "packages/event-log" }` in migrations.json, or the installed package entry. The package ships its migrations.
+
+Options are `{ registry, consumers }`. The registry maps kind strings to plain payload Schemas with no service requirements. There are no built-in event kinds or consumers. Consumer names must be unique and their kinds must exist in the registry. Registration is static for the mount lifetime. Keep the same registration order across processes.
+
+Producer modules own fact Schemas in their contract door. Operations return facts alongside their result, such as `{ task, events: [...] }`. A producer never emits, depends on EventLog or reads CurrentActor. A feature chooses which returned facts to record through its declared EventLog.record edge. App-wide facts belong to an app-owned package contract, not a feature-local value export.
+
+A fact is `{ kind, subject: { kind, id }, payload, scopeId }`. Pass null when scope is absent. Record decodes payload against the mounted registry, validates its JSON encoding and stores that encoding. Reads and delivery decode it again. Unknown kinds and malformed payloads fail EventInputInvalid. Preserve old kind Schemas while their history exists; use new versioned kind names when changing a payload incompatibly.
+
+The binder passes the person's Actor explicitly, or null for a system caller, and the available CallRequestId. The module never reads CurrentActor. Clock supplies occurredAt as epoch milliseconds. No secrets belong in facts, envelopes or dead-letter errors. Do not store tokens, credentials, private headers or raw driver errors. Pass a fixed, safe summary to settleFailure and keep causes in internal logs.
+
+Record requires UnitOfWork.required and fails NoOpenUnit outside a live unit. The event table IS the outbox. Producer writes and recording commit together in the feature's unit. The module never opens a unit. Memory registers undo before mutation; Postgres joins the caller's SQL transaction.
+
+## Delivery units and event ways
+
+Consumer config is `{ name, kinds, maxAttempts?, backoff?: { baseMs, capMs } }`, without a handler. Mount the source plug beside EventLog: `EventLog.source.pipe(Layer.provideMerge(EventLog.layerPostgres(options)))`, or layerMemory for tests. It provides the application-owned EventSource service from EventLog's claimDue/takeNext/settle methods, consumer coverage and wake stream. Application never imports event-log. Optional map metadata on the module plan is `{ name: "EventLog.source", package: "@house-rules/event-log", fills: "EventSource" }`, with no ways list.
+
+E9 is one system feature per consumer. Declare `defineWay({ protocol: "event", name, on: kinds, feature, mean: Mean.no })` in the app's ways-in/events/. The way name IS the consumer name. The way's on kinds must match the consumer's kinds exactly. Missing or extra kinds and duplicate consumer ways fail acquisition with GraphInvalid. The feature must declare a system start with reason and startedBy. Composition's explicit system permissions must cover its closure.
+
+Use EventInput from application/contract: `{ event: fullStoredEnvelope, causedBy: actorIdOrNull }`. causedBy is an identifier, never an Actor or authority. The event author does not supply the handler's permissions; even revoking that person's roles cannot change the system's explicit authority. System-only reads require their own explicit operations. Event trace steps retain causedBy as data.
+
+```text
+application's scoped event driver
+  claimDue(consumer) in its own unit
+  COMMIT attempt count + retry time
+  per token, one unit:
+    takeNext(token): lock consumer cursor
+    runFeature(system feature, { event, causedBy })
+    settleSuccess(token)
+  COMMIT success or ROLLBACK failure
+  after rollback: settleFailure(token, fixed safe summary) in a separate unit
+```
+
+The module still never opens a unit. Composition's kit driver owns these units. Transactional feature execution joins the delivery unit. A failed handler cannot erase the committed claim, and failure bookkeeping cannot accidentally commit handler writes. At or after the retry deadline, the next source wake or sweep lets claimDue start another attempt. After maxAttempts, the next due claim dead-letters and advances instead of returning another token. A crashed claim-to-delivery handoff consumes an attempt too.
+
+claimDue returns at most one token per consumer per call; the driver claims again after each batch until empty. Empty may mean busy, future retry or a dead-letter transition, so periodic sweeps remain necessary. takeNext returns null for stale/busy tokens and the driver skips the reaction. Settlement stays guarded by attempt and replay generation. The source keeps retry/backoff/dead-letter policy, not the kit.
+
+Drivers start after hooks and merge the source wake stream with a periodic sweep. composition.eventSweepMs is a positive integer, default 30000ms. Startup claims only source-reported due work. Listener failures log and restart after a sweep interval. Fresh execution uses May.system, a new request id, event:<way> channel and root span, without inherited person, caller services or network context. Disposal stops drivers before resources close.
+
+## Retry choices and replay
+
+O1: defaults are five attempts and `min(1000 * 2 ** (attempt - 1), 300000)` milliseconds between claims. The sequence begins 1s, 2s, 4s, 8s, 16s. The cap is five minutes; there is no jitter. Config permits 1 to 100 attempts and base/cap values from 1ms to five minutes, with base <= cap. The last attempt also gets its backoff window before dead-lettering.
+
+A dead letter is per `(consumer, eventId)` and contains lastError, attempts and failedAt. Failure for one consumer does not block another. Dead-lettering skips that reaction until manual replay, so a consumer may be out of date. The next selector can continue with the following event. There is no automatic replay.
+
+O2: replay has its own `event-log:replay` permission and needsApproval. It is in-process only by default. The package exposes no HTTP or MCP way; adding one is an app-owner decision. Use an admin feature and explicit human approval. Replay returns ReplayResult: `enqueued` when queued, `busy` when the consumer lock is held elsewhere, or `already_queued` when pending. A busy result may be retried later; it does not mean the event is queued. Replay queues the dead letter without rewinding the normal cursor. Replay items run before normal items, in event-id order, with a fresh retry budget and generation. Success removes the dead letter; exhausted replay updates it. Old attempt and replay-generation tokens cannot advance a newer attempt.
+
+O3: keep consumer delivery policy in module mount config and reaction Feature values in application event ways. EventLog.source fills the kit's caller-owned port. This package creates no runtime or way. Removing event ways and the plug leaves the kit and unrelated app features building and passing.
+
+## Ordering, signals and limits
+
+Delivery is at least once. Handlers must be idempotent and deduplicate by event id or a natural key. A rollback after an outside effect ran can redeliver the event. Outside effects belong in post-commit consumers, never in the original producer feature's unit; no transaction can unsend a message.
+
+One global increasing cursor orders event history. IDs are decimal strings to preserve PostgreSQL bigint precision over JSON. A transactional sequence row serializes appends until producer commit, so a higher ID cannot commit ahead of an earlier, still-hidden event. Per-aggregate ordering is not implemented. Consumer cursors do not move backwards; adding kinds later does not replay events below an existing cursor.
+
+There is no distributed lease. Postgres row locks and memory live-unit ownership serialize one consumer during the handler unit. nextDue is a retry timestamp, not a lease or a promise that a process owns an event between selector and item. A delayed item can become stale if another selector starts its next attempt. Multiple app processes still need idempotent reactions, particularly for effects outside the database. Memory must share one memoryUnitOfWork with its producers and consumers.
+
+Postgres wakeups use LISTEN/NOTIFY on the fixed house_rules_event_log channel. NOTIFY joins the producer transaction and arrives after commit. The LISTEN stream reserves a pool connection until its scope closes, so size the pool for it plus active units. Memory uses a sliding in-process signal; its signal may arrive before commit or for a rolled-back append. Signals carry no event payload and are hints, never durable delivery. The application's event driver restarts failed listeners, claims due work at startup and keeps a periodic sweep as the safety net for missed signals. Dispose listeners before closing the SQL pool.
+
+read(query) returns oldest-first history, default 100, maximum 1000. after is an exclusive event ID; kinds, subject, scopeId, requestId and inclusive time bounds filter history. listDeadLetters uses an exclusive `{ eventId, consumer }` cursor so pagination cannot skip another consumer's dead letter for the same event. It accepts an optional consumer filter and the same default 100 / maximum 1000 limit. The module publishes event_log_history for optional read models. It has no retention policy, projections or external webhook transport. Read permission grants access to all matching events; apps must not expose this global history to a person without their own scope policy.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Szwajka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @house-rules/event-log
 
-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.
+Transactional domain-event history with in-process delivery, bounded retries and manual dead-letter replay. The app supplies every event kind and payload Schema. EventLog owns none.
+
+## Mount
+
+```ts
+const options = {
+  registry: { ...TaskEvents, ...AppEvents },
+  consumers: [
+    { name: "notifications", kinds: ["task_moved"], maxAttempts: 5 },
+  ],
+};
+const mount = {
+  ...EventLogMount,
+  layer: EventLog.source.pipe(Layer.provideMerge(EventLog.layerPostgres(options))),
+};
+```
+
+Composition provides a shared PgClient and sqlUnitOfWork over that client. Register `{ "workspace": "packages/event-log" }` in migrations.json, or `{ "package": "@house-rules/event-log" }` in an installed app. Memory uses `EventLog.layerMemory(options)` and memoryUnitOfWork.
+
+Producer modules declare event facts in their contract and return them alongside operation results. A feature records selected facts through an explicit EventLog.record edge. Recording requires an open unit. Producer changes and events commit or roll back together because the event table is the outbox.
+
+## Operations
+
+| Operation | Permission | Purpose |
+| --- | --- | --- |
+| record | event-log:record | Validate a fact and stamp its actor, Clock time and request ID |
+| read | event-log:read | Read filtered history in global cursor order |
+| due | event-log:deliver | Read consumer names whose next event is due |
+| claimDue | event-log:deliver | Commit attempts and retry times; return tokens for handler items |
+| takeNext | event-log:deliver | Lock the consumer cursor and load the token's event |
+| settleSuccess | event-log:deliver | Advance the cursor in the successful handler's unit |
+| settleFailure | event-log:deliver | Optionally save a safe failure summary in a separate unit |
+| listDeadLetters | event-log:dead-letters | Read dead letters |
+| replay | event-log:replay | Manually queue one dead letter; requires approval |
+
+replay returns the typed ReplayResult: `enqueued`, `busy` or `already_queued`. Retry `busy` later; it does not confirm a queued replay.
+
+The binder passes Actor explicitly from the caller, or null for a system caller. EventLog never reads CurrentActor. Facts contain kind, subject, payload and nullable scopeId. No secrets belong in events or error summaries.
+
+## Event ways
+
+The application kit owns the event way and caller-owned EventSource port. `EventLog.source` fills it from this module's consumer registrations, claim/take/settle operations and wake stream. Keep it beside the mount layer with Layer.provideMerge, as above, so both EventLog and EventSource are available. The memory variant uses the same pattern with layerMemory. Optional map metadata is `{ name: "EventLog.source", package: "@house-rules/event-log", fills: "EventSource" }` on the module plan's plugs, with no ways list.
+
+```ts
+defineWay({
+  protocol: "event", name: "notifications", on: ["task_moved"],
+  feature: Features.notifyTaskMoved, mean: Mean.no,
+});
+```
+
+Each consumer name equals one event way name, and its kinds must match the way's on kinds exactly. Acquisition rejects missing or extra kinds and duplicate consumer ways with GraphInvalid. E9 is one system feature per consumer, now expressed directly as an event way, not two app driver features. The feature uses `EventInput` from application/contract and declares a system start. Input is `{ event: fullStoredEnvelope, causedBy: actorIdOrNull }`. causedBy records who caused the event; it grants nothing. System permissions come from composition, never from the author's roles.
+
+Composition owns delivery: claimDue commits the attempt and retry deadline in its own unit, then takeNext, runFeature and settleSuccess share one new unit per token. Failure rolls that unit back before settleFailure saves a fixed safe summary in another unit. The committed attempt survives. After a batch the driver claims again until none are due. Once attempts are exhausted, a later due claim dead-letters the event and advances the cursor.
+
+The driver listens to adapter wakes, drains source-reported due work at startup, and sweeps periodically. Configure composition.eventSweepMs, default 30000. Postgres uses transactional LISTEN/NOTIFY; memory uses an in-process hint. Failed listeners restart; disposal stops drivers before pools close. Each execution has fresh system permissions, request id, event:<way> channel and root span, with no inherited person or network context. Application never imports event-log. Removing event ways, EventLog.source and its mount leaves apps that do not need events independent of this package.
+
+Default retry policy is five attempts, exponential delays starting at one second, capped at five minutes. A deadline makes a retry eligible; the driver runs it on the next source wake or sweep at or after that time. With the default sweep, a one-second backoff can wait about 30 seconds when no wake arrives. Delivery is at least once. Handlers must be idempotent. Postgres next-event lookups use the `(kind, id)` index even for sparse or missing kinds. Cursor locks cover handler units; there is no distributed lease. Outside effects run in consumers after the producer commits, and cannot be undone by database rollback.
+
+See [AGENTS.md](AGENTS.md) for the exact unit protocol, O1-O3 choices, permissions and concurrency limits.

package/dist/adapters/memory/event.d.ts

@@ -0,0 +1,3 @@
+import { Layer } from "effect";
+import { EventStore } from "../../storage.js";
+export declare const memoryEventStore: () => Layer.Layer<EventStore>;

package/dist/adapters/memory/event.js

@@ -0,0 +1,143 @@
+import { CurrentUnit, UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer, PubSub, Stream } from "effect";
+import { EventStore } from "../../storage.js";
+const order = (a, b) => BigInt(a) < BigInt(b) ? -1 : BigInt(a) === BigInt(b) ? 0 : 1;
+export const memoryEventStore = () => Layer.effect(EventStore, Effect.gen(function* () {
+    const signal = yield* PubSub.sliding(1);
+    yield* Effect.addFinalizer(() => PubSub.shutdown(signal));
+    const rows = new Map();
+    const positions = new Map();
+    const pending = new Map();
+    const dead = new Map();
+    const owners = new Map();
+    let sequence = 0n;
+    const change = Effect.fn("EventStore.memory.change")(function* (run) {
+        yield* UnitOfWork.required;
+        const before = structuredClone({ rows, positions, pending, dead, sequence });
+        yield* UnitOfWork.onRollback(Effect.sync(() => {
+            rows.clear();
+            for (const [key, value] of before.rows)
+                rows.set(key, value);
+            positions.clear();
+            for (const [key, value] of before.positions)
+                positions.set(key, value);
+            pending.clear();
+            for (const [key, value] of before.pending)
+                pending.set(key, value);
+            dead.clear();
+            for (const [key, value] of before.dead)
+                dead.set(key, value);
+            sequence = before.sequence;
+        }));
+        run();
+    });
+    return EventStore.of({
+        append: Effect.fn("EventStore.memory.append")(function* (event) {
+            let stored = { ...event, id: "1" };
+            yield* change(() => {
+                sequence += 1n;
+                stored = structuredClone({ ...event, id: sequence.toString() });
+                rows.set(stored.id, stored);
+            });
+            yield* PubSub.publish(signal, undefined);
+            return structuredClone(stored);
+        }),
+        read: (query) => Effect.sync(() => [...rows.values()]
+            .filter((event) => (query.after === undefined || order(event.id, query.after) > 0) &&
+            (query.kinds === undefined || query.kinds.includes(event.kind)) &&
+            (query.subject === undefined ||
+                (event.subject.kind === query.subject.kind &&
+                    event.subject.id === query.subject.id)) &&
+            (query.scopeId === undefined || event.scopeId === query.scopeId) &&
+            (query.requestId === undefined || event.requestId === query.requestId) &&
+            (query.from === undefined || event.occurredAt >= query.from) &&
+            (query.to === undefined || event.occurredAt <= query.to))
+            .sort((a, b) => order(a.id, b.id))
+            .slice(0, query.limit ?? 100)
+            .map((row) => structuredClone(row))),
+        lock: Effect.fn("EventStore.memory.lock")(function* (consumer) {
+            yield* UnitOfWork.required;
+            const unit = yield* CurrentUnit;
+            if (unit === undefined)
+                return false;
+            const owner = owners.get(consumer);
+            if (owner !== undefined && owner !== unit) {
+                const active = yield* Effect.isSuccess(UnitOfWork.required.pipe(Effect.provideService(CurrentUnit, owner)));
+                if (active)
+                    return false;
+            }
+            owners.set(consumer, unit);
+            yield* UnitOfWork.onRollback(Effect.sync(() => {
+                if (owners.get(consumer) === unit)
+                    owners.delete(consumer);
+            }));
+            return true;
+        }),
+        candidate: (consumer, kinds) => Effect.sync(() => {
+            const retries = pending.get(consumer);
+            const replay = [...(retries?.values() ?? [])]
+                .filter((row) => row.replay)
+                .sort((a, b) => order(a.event.id, b.event.id))[0];
+            if (replay !== undefined)
+                return structuredClone(replay);
+            const cursor = positions.get(consumer) ?? "0";
+            const event = [...rows.values()]
+                .filter((row) => order(row.id, cursor) > 0 && kinds.includes(row.kind))
+                .sort((a, b) => order(a.id, b.id))[0];
+            return event === undefined
+                ? undefined
+                : structuredClone(retries?.get(event.id) ?? {
+                    event,
+                    attempts: 0,
+                    nextDue: 0,
+                    replay: false,
+                    generation: "0",
+                    lastError: "Delivery failed. See internal logs.",
+                });
+        }),
+        retry: (consumer, candidate) => change(() => {
+            const entries = pending.get(consumer) ?? new Map();
+            entries.set(candidate.event.id, structuredClone(candidate));
+            pending.set(consumer, entries);
+        }),
+        enqueueReplay: Effect.fn("EventStore.memory.enqueueReplay")(function* (consumer, candidate) {
+            yield* UnitOfWork.required;
+            if (pending.get(consumer)?.has(candidate.event.id))
+                return false;
+            yield* change(() => {
+                const entries = pending.get(consumer) ?? new Map();
+                entries.set(candidate.event.id, structuredClone(candidate));
+                pending.set(consumer, entries);
+            });
+            return true;
+        }),
+        advance: (consumer, eventId, replay) => change(() => {
+            pending.get(consumer)?.delete(eventId);
+            if (!replay)
+                positions.set(consumer, eventId);
+        }),
+        deadLetter: (row) => change(() => {
+            const entries = dead.get(row.consumer) ?? new Map();
+            entries.set(row.eventId, structuredClone(row));
+            dead.set(row.consumer, entries);
+        }),
+        listDeadLetters: (query) => Effect.sync(() => [...dead.values()]
+            .flatMap((entries) => [...entries.values()])
+            .filter((row) => (query.consumer === undefined || row.consumer === query.consumer) &&
+            (query.after === undefined ||
+                order(row.eventId, query.after.eventId) > 0 ||
+                (row.eventId === query.after.eventId && row.consumer > query.after.consumer)))
+            .sort((a, b) => order(a.eventId, b.eventId) ||
+            (a.consumer < b.consumer ? -1 : a.consumer === b.consumer ? 0 : 1))
+            .slice(0, query.limit ?? 100)
+            .map((row) => structuredClone(row))),
+        findDeadLetter: (consumer, eventId) => Effect.sync(() => {
+            const row = dead.get(consumer)?.get(eventId);
+            return row === undefined ? undefined : structuredClone(row);
+        }),
+        clearDeadLetter: (consumer, eventId) => change(() => {
+            dead.get(consumer)?.delete(eventId);
+        }),
+        wakeups: Stream.fromPubSub(signal),
+    });
+}));

package/dist/adapters/postgres/event.d.ts

@@ -0,0 +1,4 @@
+import { PgClient } from "@effect/sql-pg/PgClient";
+import { Layer } from "effect";
+import { EventStore } from "../../storage.js";
+export declare const postgresEventStore: Layer.Layer<EventStore, never, PgClient>;

package/dist/adapters/postgres/event.js

@@ -0,0 +1,95 @@
+import { PgClient } from "@effect/sql-pg/PgClient";
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer, Schema, Stream } from "effect";
+import { Candidate, DeadLetter } from "../../event/delivery.js";
+import { EventStoreUnavailable, StoredEvent } from "../../event/event.js";
+import { EventStore } from "../../storage.js";
+const unavailable = (cause) => new EventStoreUnavailable({ cause });
+export const postgresEventStore = Layer.effect(EventStore, Effect.gen(function* () {
+    const sql = yield* PgClient;
+    const columns = sql.literal(`id::text as id, kind, json_build_object('kind', subject_kind, 'id', subject_id) as subject, payload, scope_id as "scopeId", actor_id as "actorId", occurred_at::float8 as "occurredAt", request_id as "requestId"`);
+    const candidateColumns = sql.literal(`row_to_json(e) as event, coalesce(p.attempts, 0) as attempts, coalesce(p.next_due, 0)::float8 as "nextDue", coalesce(p.replay, false) as replay, coalesce(p.generation, '0') as generation, coalesce(p.last_error, 'Delivery failed. See internal logs.') as "lastError"`);
+    const deadColumns = sql.literal(`consumer, event_id::text as "eventId", last_error as "lastError", attempts, failed_at::float8 as "failedAt"`);
+    const read = (schema, query) => query.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(schema))), Effect.mapError(unavailable));
+    const write = Effect.fn("EventStore.postgres.write")(function* (query) {
+        yield* UnitOfWork.required;
+        yield* query.pipe(Effect.mapError(unavailable));
+    });
+    return EventStore.of({
+        append: Effect.fn("EventStore.postgres.append")(function* (event) {
+            yield* UnitOfWork.required;
+            // A sequence alone can commit out of order and let a consumer skip a late commit.
+            const ids = yield* read(Schema.Struct({ id: Schema.String }), sql `update event_log_sequence set cursor = cursor + 1 where singleton = true returning cursor::text as id`);
+            const id = ids[0]?.id;
+            if (id === undefined)
+                return yield* unavailable("Missing event cursor.");
+            yield* write(sql `insert into event_log_events (id, kind, subject_kind, subject_id, payload, scope_id, actor_id, occurred_at, request_id)
+        values (${id}::bigint, ${event.kind}, ${event.subject.kind}, ${event.subject.id}, ${sql.json(event.payload)}, ${event.scopeId}, ${event.actorId}, ${event.occurredAt}, ${event.requestId})`);
+            yield* write(sql `select pg_notify('house_rules_event_log', '')`);
+            return { ...event, id };
+        }),
+        read: (query) => read(StoredEvent, sql `select ${columns} from event_log_events where
+      id > ${query.after ?? "0"}::bigint
+      and (${query.kinds === undefined} or kind in (select jsonb_array_elements_text(${sql.json(query.kinds ?? [])})))
+      and (${query.subject === undefined} or (subject_kind = ${query.subject?.kind ?? ""} and subject_id = ${query.subject?.id ?? ""}))
+      and (${query.scopeId === undefined} or scope_id = ${query.scopeId ?? ""})
+      and (${query.requestId === undefined} or request_id = ${query.requestId ?? ""})
+      and (${query.from === undefined} or occurred_at >= ${query.from ?? 0})
+      and (${query.to === undefined} or occurred_at <= ${query.to ?? 0})
+      order by id limit ${query.limit ?? 100}`),
+        lock: Effect.fn("EventStore.postgres.lock")(function* (consumer) {
+            yield* UnitOfWork.required;
+            yield* write(sql `insert into event_log_consumers (name) values (${consumer}) on conflict (name) do nothing`);
+            const rows = yield* read(Schema.Struct({ name: Schema.String }), sql `select name from event_log_consumers where name = ${consumer} for update skip locked`);
+            return rows.length > 0;
+        }),
+        candidate: Effect.fn("EventStore.postgres.candidate")(function* (consumer, kinds) {
+            // Keep replay separate: an OR across pending and history prevents cursor range scans.
+            const replays = yield* read(Candidate, sql `select ${candidateColumns}
+        from (select ${columns} from event_log_events where id = (
+          select event_id from event_log_pending where consumer = ${consumer} and replay = true
+          order by event_id limit 1
+        )) e
+        join event_log_pending p on p.consumer = ${consumer} and p.event_id = e.id::bigint`);
+            if (replays[0] !== undefined)
+                return replays[0];
+            // A row range keeps rare/missing kinds on (kind, id), not a filtered primary-key walk.
+            const rows = yield* read(Candidate, sql `select ${candidateColumns}
+        from (select ${columns} from event_log_events where id = (
+          select next.id from jsonb_array_elements_text(${sql.json(kinds)}) k(kind)
+          cross join lateral (
+            select id from event_log_events where kind = k.kind
+            and (kind, id) > (k.kind, coalesce((select cursor from event_log_consumers where name = ${consumer}), 0))
+            order by event_log_events.kind, id limit 1
+          ) next
+          order by next.id limit 1
+        )) e
+        left join event_log_pending p on p.consumer = ${consumer} and p.event_id = e.id::bigint`);
+            return rows[0];
+        }),
+        retry: (consumer, candidate) => write(sql `insert into event_log_pending (consumer, event_id, attempts, next_due, replay, generation, last_error)
+      values (${consumer}, ${candidate.event.id}::bigint, ${candidate.attempts}, ${candidate.nextDue}, ${candidate.replay}, ${candidate.generation}, ${candidate.lastError})
+      on conflict (consumer, event_id) do update set attempts = excluded.attempts, next_due = excluded.next_due, replay = excluded.replay, generation = excluded.generation, last_error = excluded.last_error`),
+        enqueueReplay: Effect.fn("EventStore.postgres.enqueueReplay")(function* (consumer, candidate) {
+            yield* UnitOfWork.required;
+            const rows = yield* read(Schema.Struct({ id: Schema.String }), sql `insert into event_log_pending (consumer, event_id, attempts, next_due, replay, generation, last_error)
+          values (${consumer}, ${candidate.event.id}::bigint, 0, 0, true, ${candidate.generation}, ${candidate.lastError})
+          on conflict (consumer, event_id) do nothing returning event_id::text as id`);
+            return rows.length > 0;
+        }),
+        advance: Effect.fn("EventStore.postgres.advance")(function* (consumer, eventId, replay) {
+            yield* write(sql `delete from event_log_pending where consumer = ${consumer} and event_id = ${eventId}::bigint`);
+            if (!replay)
+                yield* write(sql `update event_log_consumers set cursor = ${eventId}::bigint where name = ${consumer}`);
+        }),
+        deadLetter: (row) => write(sql `insert into event_log_dead_letters (consumer, event_id, last_error, attempts, failed_at)
+      values (${row.consumer}, ${row.eventId}::bigint, ${row.lastError}, ${row.attempts}, ${row.failedAt})
+      on conflict (consumer, event_id) do update set last_error = excluded.last_error, attempts = excluded.attempts, failed_at = excluded.failed_at`),
+        listDeadLetters: (query) => read(DeadLetter, sql `select ${deadColumns} from event_log_dead_letters
+      where (${query.consumer === undefined} or consumer = ${query.consumer ?? ""}) and (event_id, consumer collate "C") > (${query.after?.eventId ?? "0"}::bigint, ${query.after?.consumer ?? ""})
+      order by event_id, consumer collate "C" limit ${query.limit ?? 100}`),
+        findDeadLetter: (consumer, eventId) => read(DeadLetter, sql `select ${deadColumns} from event_log_dead_letters where consumer = ${consumer} and event_id = ${eventId}::bigint`).pipe(Effect.map((rows) => rows[0])),
+        clearDeadLetter: (consumer, eventId) => write(sql `delete from event_log_dead_letters where consumer = ${consumer} and event_id = ${eventId}::bigint`),
+        wakeups: Stream.unwrap(sql.listen("house_rules_event_log").pipe(Effect.map(Stream.fromQueue))).pipe(Stream.as(undefined), Stream.mapError(unavailable)),
+    });
+}));

package/dist/contract.d.ts

@@ -0,0 +1,5 @@
+export { EventId, EventFact, StoredEvent, EventQuery, EventInputInvalid, EventStoreUnavailable, DeadLetterNotFound, } from "./event/event.js";
+export { DeliveryToken, ReplayResult, Delivery, DeadLetter, DeadLetterQuery, DeadLetterCursor, ConsumerOptions, } from "./event/delivery.js";
+export { EventLogOperations } from "./event/operations.js";
+export { EventLogPermissions, type EventLogPermission } from "./event/permissions.js";
+export type { EventLogOptions } from "./event/options.js";

package/dist/contract.js

@@ -0,0 +1,4 @@
+export { EventId, EventFact, StoredEvent, EventQuery, EventInputInvalid, EventStoreUnavailable, DeadLetterNotFound, } from "./event/event.js";
+export { DeliveryToken, ReplayResult, Delivery, DeadLetter, DeadLetterQuery, DeadLetterCursor, ConsumerOptions, } from "./event/delivery.js";
+export { EventLogOperations } from "./event/operations.js";
+export { EventLogPermissions } from "./event/permissions.js";

package/dist/event/bind-event-log.d.ts

@@ -0,0 +1,3 @@
+import { type Binding } from "@house-rules/application";
+import type { EventLogService } from "./event-log.js";
+export declare const bindEventLog: (service: EventLogService) => readonly Binding[];

package/dist/event/bind-event-log.js

@@ -0,0 +1,17 @@
+import { bindOperation, CallRequestId } from "@house-rules/application";
+import { Effect } from "effect";
+import { EventLogOperations as operations } from "./operations.js";
+export const bindEventLog = (service) => [
+    bindOperation(operations.record, (fact, { caller }) => Effect.gen(function* () {
+        const requestId = yield* CallRequestId;
+        return yield* service.record(caller.kind === "person" ? caller.actor : null, fact, requestId || null);
+    })),
+    bindOperation(operations.read, (query) => service.read(query)),
+    bindOperation(operations.due, () => service.due()),
+    bindOperation(operations.claimDue, (query) => service.claimDue(query)),
+    bindOperation(operations.takeNext, (token) => service.takeNext(token)),
+    bindOperation(operations.settleSuccess, (token) => service.settleSuccess(token)),
+    bindOperation(operations.settleFailure, ({ token, lastError }) => service.settleFailure(token, lastError)),
+    bindOperation(operations.listDeadLetters, (query) => service.listDeadLetters(query)),
+    bindOperation(operations.replay, ({ consumer, eventId }) => service.replay(consumer, eventId)),
+];

package/dist/event/delivery.d.ts

@@ -0,0 +1,87 @@
+import { Schema } from "effect";
+export declare const DeliveryToken: Schema.Struct<{
+    readonly consumer: Schema.NonEmptyString;
+    readonly eventId: Schema.String;
+    readonly attempt: Schema.Int;
+    readonly replay: Schema.Boolean;
+    readonly generation: Schema.String;
+}>;
+export type DeliveryToken = typeof DeliveryToken.Type;
+export declare const ReplayResult: Schema.Literals<readonly ["enqueued", "busy", "already_queued"]>;
+export type ReplayResult = typeof ReplayResult.Type;
+export declare const Delivery: Schema.Struct<{
+    readonly token: Schema.Struct<{
+        readonly consumer: Schema.NonEmptyString;
+        readonly eventId: Schema.String;
+        readonly attempt: Schema.Int;
+        readonly replay: Schema.Boolean;
+        readonly generation: Schema.String;
+    }>;
+    readonly event: Schema.Struct<{
+        readonly kind: Schema.NonEmptyString;
+        readonly subject: Schema.Struct<{
+            readonly kind: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>;
+        readonly payload: Schema.Unknown;
+        readonly scopeId: Schema.NullOr<Schema.NonEmptyString>;
+        readonly id: Schema.String;
+        readonly actorId: Schema.NullOr<Schema.NonEmptyString>;
+        readonly occurredAt: Schema.Int;
+        readonly requestId: Schema.NullOr<Schema.String>;
+    }>;
+}>;
+export type Delivery = typeof Delivery.Type;
+export declare const DeadLetter: Schema.Struct<{
+    readonly consumer: Schema.NonEmptyString;
+    readonly eventId: Schema.String;
+    readonly lastError: Schema.String;
+    readonly attempts: Schema.Int;
+    readonly failedAt: Schema.Int;
+}>;
+export type DeadLetter = typeof DeadLetter.Type;
+export declare const DeadLetterCursor: Schema.Struct<{
+    readonly eventId: Schema.String;
+    readonly consumer: Schema.NonEmptyString;
+}>;
+export type DeadLetterCursor = typeof DeadLetterCursor.Type;
+export declare const DeadLetterQuery: Schema.Struct<{
+    readonly consumer: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly after: Schema.optionalKey<Schema.Struct<{
+        readonly eventId: Schema.String;
+        readonly consumer: Schema.NonEmptyString;
+    }>>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type DeadLetterQuery = typeof DeadLetterQuery.Type;
+export declare const Candidate: Schema.Struct<{
+    readonly event: Schema.Struct<{
+        readonly kind: Schema.NonEmptyString;
+        readonly subject: Schema.Struct<{
+            readonly kind: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>;
+        readonly payload: Schema.Unknown;
+        readonly scopeId: Schema.NullOr<Schema.NonEmptyString>;
+        readonly id: Schema.String;
+        readonly actorId: Schema.NullOr<Schema.NonEmptyString>;
+        readonly occurredAt: Schema.Int;
+        readonly requestId: Schema.NullOr<Schema.String>;
+    }>;
+    readonly attempts: Schema.Int;
+    readonly nextDue: Schema.Int;
+    readonly replay: Schema.Boolean;
+    readonly generation: Schema.String;
+    readonly lastError: Schema.String;
+}>;
+export type Candidate = typeof Candidate.Type;
+export declare const ConsumerOptions: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly kinds: Schema.$Array<Schema.NonEmptyString>;
+    readonly maxAttempts: Schema.optionalKey<Schema.Int>;
+    readonly backoff: Schema.optionalKey<Schema.Struct<{
+        readonly baseMs: Schema.Int;
+        readonly capMs: Schema.Int;
+    }>>;
+}>;
+export type ConsumerOptions = typeof ConsumerOptions.Type;

package/dist/event/delivery.js

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+import { EventId, StoredEvent } from "./event.js";
+export const DeliveryToken = Schema.Struct({
+    consumer: Schema.NonEmptyString,
+    eventId: EventId,
+    attempt: Schema.Int.check(Schema.isGreaterThan(0)),
+    replay: Schema.Boolean,
+    generation: Schema.String,
+});
+export const ReplayResult = Schema.Literals(["enqueued", "busy", "already_queued"]);
+export const Delivery = Schema.Struct({ token: DeliveryToken, event: StoredEvent });
+export const DeadLetter = Schema.Struct({
+    consumer: Schema.NonEmptyString,
+    eventId: EventId,
+    lastError: Schema.String,
+    attempts: Schema.Int.check(Schema.isGreaterThan(0)),
+    failedAt: Schema.Int,
+});
+export const DeadLetterCursor = Schema.Struct({
+    eventId: EventId,
+    consumer: Schema.NonEmptyString,
+});
+export const DeadLetterQuery = Schema.Struct({
+    consumer: Schema.optionalKey(Schema.NonEmptyString),
+    after: Schema.optionalKey(DeadLetterCursor),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 1000 }))),
+});
+export const Candidate = Schema.Struct({
+    event: StoredEvent,
+    attempts: Schema.Int,
+    nextDue: Schema.Int,
+    replay: Schema.Boolean,
+    generation: Schema.String,
+    lastError: Schema.String,
+});
+export const ConsumerOptions = Schema.Struct({
+    name: Schema.NonEmptyString,
+    kinds: Schema.Array(Schema.NonEmptyString).check(Schema.isMinLength(1)),
+    maxAttempts: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))),
+    backoff: Schema.optionalKey(Schema.Struct({
+        baseMs: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 300000 })),
+        capMs: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 300000 })),
+    })),
+});