@house-rules/domain-postgres 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,25 @@
+# Agent guide: @house-rules/domain-postgres
+
+A Postgres `Platform` for Alchemy Domain (`@alchemy.run/domain` 2.0.0-beta.85, Effect 4.1.2). Swap it in where an app would use `Domain.InMemory`; the model does not change.
+
+## Wiring
+
+```ts
+import { fromEnv } from "@house-rules/domain-postgres";
+
+const Hosted = App.layer(AppHandlers).pipe(Layer.provide(fromEnv({ schema: "app" })));
+```
+
+- `fromEnv({ schema })` reads `DOMAIN_STORE` (`postgres` by default, or `memory`) and `DATABASE_URL`. Declare both in the app's `.env.schema`.
+- `layer({ schema })` is the same store without the env switch; provide a `PgClient` yourself.
+- By default `layer` and `fromEnv` create the schema and tables on start. That needs CREATE on the database or schema. When the runtime role may only read and write rows, the schema owner runs `migrate(schema)` in the migration step, and the app passes `createTables: false`. Start then only checks the tables and dies with `TablesMissing`, naming the schema and missing tables, if any are absent.
+- The runtime role needs `USAGE` on the schema, `SELECT, INSERT, UPDATE, DELETE` on its tables, `USAGE` on its sequences (`outbox.position` is a `bigserial`), and `ALTER DEFAULT PRIVILEGES FOR ROLE <owner> IN SCHEMA <schema>` granting the same on tables and sequences the owner adds later. The README has the SQL.
+- Tests provide `platformForTests`: a fresh `test_<uuid>` schema per test, dropped after. Run the suite again with `DOMAIN_STORE=memory` to cover `Domain.InMemory`.
+
+## Fixed rules
+
+- Run one replica per schema. Two processes would both run the outbox loop and the schedules, so a policy could fire twice.
+- No projections, streams or sagas. Building a model with them fails.
+- No backfill. A new view, or a view whose `version` changes, fills from new events only.
+- Pin `@alchemy.run/domain`, `alchemy` and `effect` to this package's peer versions. The `Platform` contract is beta; rerun the tests on every Alchemy bump.
+- A policy command id comes from its event, so a redelivered event is deduplicated by its receipt. A call to an outside provider inside a policy is not; make it idempotent.

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/domain-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Postgres `Platform` for Alchemy Domain (`@alchemy.run/domain` 2.0.0-beta.85). It keeps a model's events, state, receipts, views, schedules and outbox in your own Postgres, so a model runs on Node in a container and survives a restart. It is its own package so it can be deleted when Alchemy ships its own Postgres host. [AGENTS.md](AGENTS.md) holds the wiring and fixed rules for agents.
+
+```ts
+import { layer } from "@house-rules/domain-postgres";
+import * as PgClient from "@effect/sql-pg/PgClient";
+
+const Hosted = App.layer(AppHandlers).pipe(
+  Layer.provide(layer({ schema: "app" })),
+  Layer.provide(PgClient.layerConfig({ url: Config.Redacted("DATABASE_URL") })),
+);
+```
+
+`fromEnv({ schema })` picks the store from `DOMAIN_STORE`: `postgres` (default, needs `DATABASE_URL`) or `memory` (`Domain.InMemory`). Swapping the Layer is the whole move; the model does not change.
+
+## What it stores
+
+`layer` creates its tables in `schema` on start (`CREATE ... IF NOT EXISTS`), unless you pass `createTables: false` (see [A runtime role that cannot create](#a-runtime-role-that-cannot-create)):
+
+| Table | Holds |
+| --- | --- |
+| `instances` | each aggregate instance's state and version; its row lock is the single writer |
+| `events` | every committed event, keyed `(model, aggregate, id, seq)` so two writers can never commit the same seq |
+| `receipts` | the reply to each command id, so a retried command returns the first receipt |
+| `schedules`, `cancellations` | scheduled commands and the ones cancelled |
+| `views`, `view_keys`, `view_entries` | each view key's snapshot, with per-source checkpoints, and what it emitted |
+| `outbox` | deliveries to views and policies, written in the same transaction as the commit |
+
+A command commits its events, state, receipt and outbox rows in one transaction. One loop per model delivers the outbox in order, deletes each row after its view or policy succeeds, retries a failure, and parks a row after `maxAttempts` (5) by setting `failed_at`. Views drop duplicates by checkpoint, so delivery is at least once.
+
+## A runtime role that cannot create
+
+Postgres checks the CREATE privilege before it checks whether a schema or table exists. So the default start, which runs `CREATE ... IF NOT EXISTS`, fails with `permission denied` for a role that may only read and write rows, even when every table is there.
+
+Split the two jobs. The schema owner runs `migrate(schema)` in the deploy's migration step, with a `PgClient` that connects as the owner. `migrate` is idempotent. The app runs `layer({ schema, createTables: false })` or `fromEnv({ schema, createTables: false })` as the runtime role. With `createTables: false`, start reads `pg_catalog` instead of creating anything. If the schema or any table is missing, the layer dies with `TablesMissing`, which names the schema and the missing tables. It never creates them.
+
+The runtime role needs these grants, run once by the owner:
+
+```sql
+GRANT USAGE ON SCHEMA app TO app_runtime;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA app TO app_runtime;
+GRANT USAGE ON ALL SEQUENCES IN SCHEMA app TO app_runtime;
+ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_runtime;
+ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
+  GRANT USAGE ON SEQUENCES TO app_runtime;
+```
+
+The sequence grant covers `outbox.position`, a `bigserial`. The default privileges cover tables a later version of this package adds when the owner runs `migrate` again. The runtime role needs no CREATE on the database or the schema.
+
+## Limits
+
+- One replica per database schema. Two processes would both run the outbox loop and each other's schedules, and live reads (`watch`) only see commits made in their own process.
+- No projections, streams or sagas: building a model with them fails.
+- No backfill. A view added to a database that already has events starts empty and fills from new events only; bumping a view's `version` empties it the same way.
+- The `Platform` contract is beta. `Platform.ts` changed 308 lines between beta.84 and beta.85, so pin Alchemy exactly and rerun these tests on every bump.
+
+## Tests
+
+Tests run against real Postgres. Start it with `pnpm db:up` (docker compose, `127.0.0.1:55432`); CI runs the same image as a service. `platformForTests` gives each test its own schema and drops it after. Set `DOMAIN_STORE=memory` to run the same tests on `Domain.InMemory`; this package's `test` script runs both, and the restart test runs on Postgres only.

package/dist/adapters/aggregate-store.d.ts

@@ -0,0 +1,3 @@
+import type { AggregateKit, AggregateStore } from "@alchemy.run/domain/Platform";
+import type { Host } from "./host.ts";
+export declare const makeAggregateStore: (host: Host, kit: AggregateKit) => AggregateStore;

package/dist/adapters/aggregate-store.js

@@ -0,0 +1,139 @@
+import { AlreadyCancelled, AlreadyExecuted, NotScheduled, } from "@alchemy.run/domain/Aggregate";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+export const makeAggregateStore = (host, kit) => {
+    const { sql, t, model, notify, kick, stage, firing, arm } = host;
+    const name = kit.name;
+    const where = (id) => sql `model = ${model} AND aggregate = ${name} AND id = ${id}`;
+    const lock = (id) => Effect.gen(function* () {
+        yield* sql `
+        INSERT INTO ${t("instances")} (model, aggregate, id, state, version)
+        VALUES (${model}, ${name}, ${id}, NULL, 0) ON CONFLICT DO NOTHING`;
+        const rows = yield* sql `
+        SELECT state, version FROM ${t("instances")} WHERE ${where(id)} FOR UPDATE`;
+        return rows[0] ?? { state: null, version: 0 };
+    });
+    const receipt = (id, commandId) => Effect.map(sql `
+        SELECT result FROM ${t("receipts")} WHERE ${where(id)} AND command_id = ${commandId}`, (rows) => rows[0]?.result);
+    const commit = (id, command, meta) => Effect.gen(function* () {
+        const current = yield* lock(id);
+        const duplicate = yield* receipt(id, meta.commandId);
+        if (duplicate)
+            return duplicate;
+        const result = yield* kit.handle({
+            id,
+            state: current.state,
+            version: current.version,
+            command,
+            commandId: meta.commandId,
+            context: meta.context,
+            now: yield* Clock.currentTimeMillis,
+            correlationId: meta.correlationId,
+            trace: meta.trace,
+            link: meta.link,
+        });
+        if (result._tag === "Rejected")
+            return result;
+        yield* Effect.forEach(result.events, (stored) => sql `
+          INSERT INTO ${t("events")} (model, aggregate, id, seq, event, envelope)
+          VALUES (${model}, ${name}, ${id}, ${stored.envelope.seq},
+                  ${sql.json(stored.event)}, ${sql.json(stored.envelope)})`, { discard: true });
+        yield* sql `
+        UPDATE ${t("instances")} SET state = ${sql.json(result.state)}, version = ${result.version}
+        WHERE ${where(id)}`;
+        const sent = {
+            _tag: "Accepted",
+            receipt: {
+                stream: `${name}/${id}`,
+                version: result.version,
+                events: result.events.map((stored) => stored.event),
+                reply: result.reply,
+            },
+        };
+        yield* sql `
+        INSERT INTO ${t("receipts")} (model, aggregate, id, command_id, result)
+        VALUES (${model}, ${name}, ${id}, ${meta.commandId}, ${sql.json(sent)})`;
+        yield* stage(result.deliveries);
+        return sent;
+    });
+    const committed = (id) => Effect.andThen(notify.bump(`a:${name}/${id}`), kick);
+    const send = (id, command, meta) => sql.withTransaction(commit(id, command, meta)).pipe(Effect.orDie, Effect.tap(() => committed(id)));
+    firing.set(name, (id, commandId, token) => sql
+        .withTransaction(Effect.gen(function* () {
+        const rows = yield* sql `
+            DELETE FROM ${t("schedules")}
+            WHERE ${where(id)} AND command_id = ${commandId} AND token = ${token}
+            RETURNING command, meta`;
+        const due = rows[0];
+        if (due)
+            yield* commit(id, due.command, due.meta);
+    }))
+        .pipe(Effect.orDie, Effect.andThen(committed(id))));
+    const state = (id) => Effect.map(sql `SELECT state, version FROM ${t("instances")} WHERE ${where(id)}`, (rows) => rows[0] ?? { state: null, version: 0 }).pipe(Effect.orDie);
+    const eventsAfter = (id, after) => sql `
+      SELECT event, envelope FROM ${t("events")} WHERE ${where(id)} AND seq > ${after}
+      ORDER BY seq`.pipe(Effect.orDie);
+    return {
+        send,
+        schedule: (id, command, meta, due) => Effect.gen(function* () {
+            const at = "at" in due ? due.at : (yield* Clock.currentTimeMillis) + due.afterMillis;
+            const token = yield* sql
+                .withTransaction(Effect.gen(function* () {
+                yield* lock(id);
+                if (yield* receipt(id, meta.commandId))
+                    return yield* new AlreadyExecuted({
+                        aggregate: name,
+                        id,
+                        commandId: meta.commandId,
+                    });
+                yield* sql `DELETE FROM ${t("cancellations")} WHERE ${where(id)} AND command_id = ${meta.commandId}`;
+                const rows = yield* sql `
+                INSERT INTO ${t("schedules")} (model, aggregate, id, command_id, command, meta, due_at, token)
+                VALUES (${model}, ${name}, ${id}, ${meta.commandId}, ${sql.json(command)},
+                        ${sql.json(meta)}, ${at}, gen_random_uuid()::text)
+                ON CONFLICT (model, aggregate, id, command_id)
+                DO UPDATE SET command = EXCLUDED.command, meta = EXCLUDED.meta,
+                              due_at = EXCLUDED.due_at, token = EXCLUDED.token
+                RETURNING token`;
+                const token = rows[0]?.token;
+                return token ?? (yield* Effect.die(new Error("schedule row not written")));
+            }))
+                .pipe(Effect.catchTag("SqlError", Effect.die));
+            yield* arm(name, id, meta.commandId, token, at);
+            return at;
+        }),
+        unschedule: (id, commandId) => sql
+            .withTransaction(Effect.gen(function* () {
+            const fields = { aggregate: name, id, commandId };
+            yield* lock(id);
+            if (yield* receipt(id, commandId))
+                return yield* new AlreadyExecuted(fields);
+            const cancelled = yield* sql `
+              SELECT 1 FROM ${t("cancellations")} WHERE ${where(id)} AND command_id = ${commandId}`;
+            if (cancelled.length > 0)
+                return yield* new AlreadyCancelled(fields);
+            const removed = yield* sql `
+              DELETE FROM ${t("schedules")} WHERE ${where(id)} AND command_id = ${commandId}
+              RETURNING 1`;
+            if (removed.length === 0)
+                return yield* new NotScheduled(fields);
+            yield* sql `
+              INSERT INTO ${t("cancellations")} (model, aggregate, id, command_id)
+              VALUES (${model}, ${name}, ${id}, ${commandId})`;
+        }))
+            .pipe(Effect.catchTag("SqlError", Effect.die)),
+        state,
+        events: (id) => eventsAfter(id, 0),
+        changes: (id) => notify.changes(`a:${name}/${id}`, state(id)),
+        tail: (id, after) => {
+            let last = after;
+            return notify.changes(`a:${name}/${id}`, Effect.void).pipe(Stream.flatMap(() => Stream.unwrap(Effect.map(eventsAfter(id, last), (fresh) => {
+                const newest = fresh.at(-1);
+                if (newest)
+                    last = newest.envelope.seq;
+                return Stream.fromIterable(fresh);
+            }))));
+        },
+    };
+};

package/dist/adapters/from-env.d.ts

@@ -0,0 +1,17 @@
+import * as Domain from "@alchemy.run/domain";
+import * as Pg from "@effect/sql-pg/PgClient";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { type Options } from "./postgres-platform.ts";
+export declare const LOCAL_DATABASE_URL = "postgres://house_rules:house_rules@127.0.0.1:55432/house_rules";
+export declare const databaseUrl: Config.Config<Redacted.Redacted<string>>;
+export declare const domainStore: Config.Config<"memory" | "postgres">;
+export declare const PgForTests: Layer.Layer<Pg.PgClient | import("effect/sql/SqlClient").SqlClient, Config.ConfigError | import("effect/sql/SqlError").SqlError, never>;
+export declare const testSchema: Effect.Effect<string, never, Pg.PgClient | import("effect/Scope").Scope>;
+export declare const postgresInFreshSchema: Layer.Layer<Domain.Platform, never, Pg.PgClient>;
+export declare const fromEnv: (options: Omit<Options, "schema"> & {
+    readonly schema: string;
+}) => Layer.Layer<Domain.Platform, Config.ConfigError | import("effect/sql/SqlError").SqlError, never>;
+export declare const platformForTests: Layer.Layer<Domain.Platform, never, never>;

package/dist/adapters/from-env.js

@@ -0,0 +1,35 @@
+import * as Domain from "@alchemy.run/domain";
+import * as Pg from "@effect/sql-pg/PgClient";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { layer } from "./postgres-platform.js";
+export const LOCAL_DATABASE_URL = "postgres://house_rules:house_rules@127.0.0.1:55432/house_rules";
+export const databaseUrl = Config.Redacted("DATABASE_URL").pipe(Config.withDefault(Redacted.make(LOCAL_DATABASE_URL)));
+export const domainStore = Config.Literals(["postgres", "memory"], "DOMAIN_STORE").pipe(Config.withDefault("postgres"));
+export const PgForTests = Pg.layerConfig({ url: databaseUrl });
+export const testSchema = Effect.acquireRelease(Effect.gen(function* () {
+    const sql = yield* Pg.PgClient;
+    const rows = yield* sql `
+      SELECT 'test_' || replace(gen_random_uuid()::text, '-', '') AS name`;
+    const name = rows[0]?.name;
+    return name ?? (yield* Effect.die(new Error("no schema name")));
+}), (schema) => Effect.gen(function* () {
+    const sql = yield* Pg.PgClient;
+    yield* sql `DROP SCHEMA IF EXISTS ${sql(schema)} CASCADE`;
+}).pipe(Effect.ignore)).pipe(Effect.orDie);
+export const postgresInFreshSchema = Layer.unwrap(Effect.map(testSchema, (schema) => layer({ schema, pollInterval: "200 millis" })));
+export const fromEnv = (options) => Layer.unwrap(Effect.gen(function* () {
+    const store = yield* domainStore;
+    if (store === "memory")
+        return Domain.InMemory;
+    const url = yield* Config.Redacted("DATABASE_URL");
+    return layer(options).pipe(Layer.provide(Pg.layer({ url })));
+}));
+export const platformForTests = Layer.unwrap(Effect.gen(function* () {
+    const store = yield* domainStore;
+    return store === "memory"
+        ? Domain.InMemory
+        : postgresInFreshSchema.pipe(Layer.provide(PgForTests), Layer.orDie);
+})).pipe(Layer.orDie);

package/dist/adapters/host.d.ts

@@ -0,0 +1,21 @@
+import type { Delivery } from "@alchemy.run/domain/Platform";
+import type { PgClient } from "@effect/sql-pg/PgClient";
+import * as Effect from "effect/Effect";
+import type { SqlError } from "effect/sql/SqlError";
+import * as Stream from "effect/Stream";
+export type Fire = (id: string, commandId: string, token: string) => Effect.Effect<void>;
+export interface Notifier {
+    readonly bump: (key: string) => Effect.Effect<void>;
+    readonly changes: <A>(key: string, read: Effect.Effect<A>) => Stream.Stream<A>;
+}
+export interface Host {
+    readonly sql: PgClient;
+    readonly t: (table: string) => ReturnType<PgClient>;
+    readonly model: string;
+    readonly notify: Notifier;
+    readonly kick: Effect.Effect<void>;
+    readonly stage: (deliveries: ReadonlyArray<Delivery>) => Effect.Effect<void, SqlError>;
+    readonly firing: Map<string, Fire>;
+    readonly arm: (aggregate: string, id: string, commandId: string, token: string, at: number) => Effect.Effect<void>;
+}
+export declare const notifier: () => Notifier;

package/dist/adapters/host.js

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+export const notifier = () => {
+    const refs = new Map();
+    const ref = (key) => Effect.suspend(() => {
+        const found = refs.get(key);
+        if (found)
+            return Effect.succeed(found);
+        return Effect.tap(SubscriptionRef.make(0), (made) => Effect.sync(() => refs.set(key, made)));
+    });
+    return {
+        bump: (key) => Effect.suspend(() => {
+            const found = refs.get(key);
+            return found ? SubscriptionRef.update(found, (n) => n + 1) : Effect.void;
+        }),
+        changes: (key, read) => Stream.unwrap(Effect.map(ref(key), (found) => SubscriptionRef.changes(found).pipe(Stream.mapEffect(() => read)))),
+    };
+};

package/dist/adapters/outbox.d.ts

@@ -0,0 +1,14 @@
+import type { Delivery } from "@alchemy.run/domain/Platform";
+import type { PgClient } from "@effect/sql-pg/PgClient";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+export declare const makeOutbox: (options: {
+    readonly sql: PgClient;
+    readonly table: string;
+    readonly model: string;
+    readonly wake: Queue.Queue<void>;
+    readonly deliver: (delivery: Delivery) => Effect.Effect<void>;
+    readonly pollInterval: Duration.Input;
+    readonly maxAttempts: number;
+}) => Effect.Effect<never, never, never>;

package/dist/adapters/outbox.js

@@ -0,0 +1,44 @@
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Queue from "effect/Queue";
+const BATCH = 100;
+export const makeOutbox = (options) => {
+    const { sql, model } = options;
+    const table = sql(options.table);
+    const pass = Effect.gen(function* () {
+        const rows = yield* sql `
+      SELECT position, delivery, attempts FROM ${table}
+      WHERE model = ${model} AND failed_at IS NULL
+      ORDER BY position LIMIT ${BATCH}`;
+        for (const row of rows) {
+            const exit = yield* Effect.exit(options.deliver(row.delivery));
+            if (Exit.isSuccess(exit)) {
+                yield* sql `DELETE FROM ${table} WHERE position = ${row.position}`;
+                continue;
+            }
+            const attempts = row.attempts + 1;
+            if (attempts >= options.maxAttempts) {
+                const now = yield* Clock.currentTimeMillis;
+                yield* sql `UPDATE ${table} SET attempts = ${attempts}, failed_at = ${now} WHERE position = ${row.position}`;
+                yield* Effect.logError(`delivery ${row.position} to ${row.delivery.target.kind} ${row.delivery.target.name} failed ${attempts} times; parked`, exit.cause);
+                continue;
+            }
+            yield* sql `UPDATE ${table} SET attempts = ${attempts} WHERE position = ${row.position}`;
+            yield* Effect.logWarning(`delivery ${row.position} to ${row.delivery.target.kind} ${row.delivery.target.name} failed; retrying`, exit.cause);
+            // Stop here so later deliveries from the same source never overtake this one.
+            return "retry";
+        }
+        return rows.length === BATCH ? "more" : "drained";
+    }).pipe(Effect.orDie);
+    const idle = Effect.raceFirst(Queue.take(options.wake), Effect.sleep(Duration.fromInputUnsafe(options.pollInterval)));
+    return Effect.gen(function* () {
+        while (true) {
+            const result = yield* pass;
+            if (result === "more")
+                continue;
+            yield* idle;
+        }
+    });
+};

package/dist/adapters/postgres-platform.d.ts

@@ -0,0 +1,11 @@
+import { Platform } from "@alchemy.run/domain/Platform";
+import { PgClient } from "@effect/sql-pg/PgClient";
+import * as Duration from "effect/Duration";
+import * as Layer from "effect/Layer";
+export interface Options {
+    readonly schema?: string;
+    readonly createTables?: boolean;
+    readonly pollInterval?: Duration.Input;
+    readonly maxAttempts?: number;
+}
+export declare const layer: (options?: Options) => Layer.Layer<Platform, never, PgClient>;

package/dist/adapters/postgres-platform.js

@@ -0,0 +1,67 @@
+import { Platform } from "@alchemy.run/domain/Platform";
+import { PgClient } from "@effect/sql-pg/PgClient";
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import { makeAggregateStore } from "./aggregate-store.js";
+import { notifier } from "./host.js";
+import { makeOutbox } from "./outbox.js";
+import { checkTables, migrate } from "./tables.js";
+import { makeViewStore } from "./view-store.js";
+const unsupported = (kind) => Effect.die(new Error(`@house-rules/domain-postgres does not host ${kind} yet; use Domain.InMemory`));
+const makeHost = (sql, schema, model, scope, options) => Effect.gen(function* () {
+    const t = (name) => sql(`${schema}.${name}`);
+    const notify = notifier();
+    let deliver;
+    const wake = yield* Queue.sliding(1);
+    const kick = Queue.offer(wake, undefined).pipe(Effect.asVoid);
+    const stage = (deliveries) => Effect.forEach(deliveries, (delivery) => sql `INSERT INTO ${t("outbox")} (model, delivery) VALUES (${model}, ${sql.json(delivery)})`, { discard: true });
+    const firing = new Map();
+    const arm = (aggregate, id, commandId, token, at) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const fire = firing.get(aggregate);
+        if (!fire)
+            return;
+        yield* Effect.sleep(Duration.millis(Math.max(0, at - now))).pipe(Effect.andThen(fire(id, commandId, token)), Effect.catchCause((cause) => Effect.logError(`scheduled ${aggregate}/${id}/${commandId} failed`, cause)), Effect.forkIn(scope));
+    });
+    const host = { sql, t, model, notify, kick, stage, firing, arm };
+    const remember = (kit) => {
+        deliver ??= kit.deliver;
+    };
+    const outbox = makeOutbox({
+        sql,
+        table: `${schema}.outbox`,
+        model,
+        wake,
+        deliver: (delivery) => deliver ? deliver(delivery) : Effect.die(new Error("no store is hosted yet")),
+        pollInterval: options.pollInterval ?? "1 second",
+        maxAttempts: options.maxAttempts ?? 5,
+    });
+    const modelHost = {
+        aggregate: (_aggregate, kit) => Effect.sync(() => {
+            remember(kit);
+            return makeAggregateStore(host, kit);
+        }),
+        view: (_view, kit) => Effect.andThen(Effect.sync(() => remember(kit)), makeViewStore(host, kit)),
+        policy: (_policy, kit) => Effect.succeed({ receive: (delivery) => kit.run(delivery) }),
+        projection: () => unsupported("projections"),
+        stream: () => unsupported("streams"),
+        start: () => Effect.gen(function* () {
+            const due = yield* sql `
+            SELECT aggregate, id, command_id, token, due_at FROM ${t("schedules")} WHERE model = ${model}`.pipe(Effect.orDie);
+            yield* Effect.forEach(due, (row) => arm(row.aggregate, row.id, row.command_id, row.token, Number(row.due_at)), { discard: true });
+            yield* Effect.forkIn(outbox, scope);
+        }),
+    };
+    return modelHost;
+});
+export const layer = (options = {}) => Layer.effect(Platform, Effect.gen(function* () {
+    const sql = yield* PgClient;
+    const schema = options.schema ?? "domain";
+    yield* (options.createTables === false ? checkTables(schema) : migrate(schema)).pipe(Effect.orDie);
+    return Platform.of({
+        model: ({ modelName }) => Effect.flatMap(Effect.scope, (scope) => makeHost(sql, schema, modelName, scope, options)),
+    });
+}));

package/dist/adapters/tables.d.ts

@@ -0,0 +1,16 @@
+import { PgClient } from "@effect/sql-pg/PgClient";
+import * as Effect from "effect/Effect";
+export declare const tableNames: readonly ["instances", "events", "receipts", "schedules", "cancellations", "views", "view_keys", "view_entries", "outbox"];
+declare const TablesMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "TablesMissing";
+} & Readonly<A>;
+export declare class TablesMissing extends TablesMissing_base<{
+    readonly schema: string;
+    readonly missing: ReadonlyArray<string>;
+    readonly message: string;
+}> {
+}
+export declare const createTables: (schema: string) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, PgClient>;
+export declare const migrate: (schema: string) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, PgClient>;
+export declare const checkTables: (schema: string) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError | TablesMissing, PgClient>;
+export {};

package/dist/adapters/tables.js

@@ -0,0 +1,132 @@
+import { PgClient } from "@effect/sql-pg/PgClient";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+export const tableNames = [
+    "instances",
+    "events",
+    "receipts",
+    "schedules",
+    "cancellations",
+    "views",
+    "view_keys",
+    "view_entries",
+    "outbox",
+];
+export class TablesMissing extends Data.TaggedError("TablesMissing") {
+}
+export const createTables = (schema) => Effect.gen(function* () {
+    const sql = yield* PgClient;
+    const t = (name) => sql(`${schema}.${name}`);
+    // Parallel hosts on one database would race CREATE IF NOT EXISTS without it.
+    yield* sql `SELECT pg_advisory_xact_lock(hashtext(${`house-rules/domain-postgres/${schema}`}))`;
+    yield* sql `CREATE SCHEMA IF NOT EXISTS ${sql(schema)}`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("instances")} (
+        model text NOT NULL,
+        aggregate text NOT NULL,
+        id text NOT NULL,
+        state jsonb,
+        version integer NOT NULL DEFAULT 0 CHECK (version >= 0),
+        PRIMARY KEY (model, aggregate, id)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("events")} (
+        model text NOT NULL,
+        aggregate text NOT NULL,
+        id text NOT NULL,
+        seq integer NOT NULL CHECK (seq > 0),
+        event jsonb NOT NULL,
+        envelope jsonb NOT NULL,
+        PRIMARY KEY (model, aggregate, id, seq)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("receipts")} (
+        model text NOT NULL,
+        aggregate text NOT NULL,
+        id text NOT NULL,
+        command_id text NOT NULL,
+        result jsonb NOT NULL,
+        PRIMARY KEY (model, aggregate, id, command_id)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("schedules")} (
+        model text NOT NULL,
+        aggregate text NOT NULL,
+        id text NOT NULL,
+        command_id text NOT NULL,
+        command jsonb NOT NULL,
+        meta jsonb NOT NULL,
+        due_at bigint NOT NULL,
+        token text NOT NULL,
+        PRIMARY KEY (model, aggregate, id, command_id)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("cancellations")} (
+        model text NOT NULL,
+        aggregate text NOT NULL,
+        id text NOT NULL,
+        command_id text NOT NULL,
+        PRIMARY KEY (model, aggregate, id, command_id)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("views")} (
+        model text NOT NULL,
+        view text NOT NULL,
+        generation integer NOT NULL,
+        PRIMARY KEY (model, view)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("view_keys")} (
+        model text NOT NULL,
+        view text NOT NULL,
+        key text NOT NULL,
+        snapshot jsonb NOT NULL,
+        PRIMARY KEY (model, view, key)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("view_entries")} (
+        model text NOT NULL,
+        view text NOT NULL,
+        key text NOT NULL,
+        seq integer NOT NULL CHECK (seq > 0),
+        entry jsonb NOT NULL,
+        PRIMARY KEY (model, view, key, seq)
+      )`;
+    yield* sql `
+      CREATE TABLE IF NOT EXISTS ${t("outbox")} (
+        position bigserial PRIMARY KEY,
+        model text NOT NULL,
+        delivery jsonb NOT NULL,
+        attempts integer NOT NULL DEFAULT 0,
+        failed_at bigint
+      )`;
+    yield* sql `
+      CREATE INDEX IF NOT EXISTS ${sql("outbox_pending")} ON ${t("outbox")} (model, position)
+      WHERE failed_at IS NULL`;
+});
+export const migrate = (schema) => Effect.gen(function* () {
+    const sql = yield* PgClient;
+    yield* sql.withTransaction(createTables(schema));
+});
+export const checkTables = (schema) => Effect.gen(function* () {
+    const sql = yield* PgClient;
+    const schemas = yield* sql `
+      SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = ${schema}) AS found`;
+    const rows = yield* sql `
+      SELECT c.relname AS name
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ${schema} AND c.relkind IN ('r', 'p')`;
+    const found = new Set(rows.map((row) => row.name));
+    const missing = tableNames.filter((name) => !found.has(name));
+    if (missing.length === 0)
+        return;
+    const fix = `run migrate("${schema}") as the schema owner before starting with createTables: false`;
+    return yield* new TablesMissing({
+        schema,
+        missing,
+        message: schemas[0]?.found === true
+            ? `schema "${schema}" lacks tables ${missing.join(", ")}; ${fix}`
+            : `schema "${schema}" does not exist; ${fix}`,
+    });
+});

package/dist/adapters/view-store.d.ts

@@ -0,0 +1,4 @@
+import { type ViewKit, type ViewStore } from "@alchemy.run/domain/Platform";
+import * as Effect from "effect/Effect";
+import type { Host } from "./host.ts";
+export declare const makeViewStore: (host: Host, kit: ViewKit) => Effect.Effect<ViewStore, never, never>;

package/dist/adapters/view-store.js

@@ -0,0 +1,59 @@
+import { emptySnapshot, } from "@alchemy.run/domain/Platform";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+export const makeViewStore = (host, kit) => Effect.gen(function* () {
+    const { sql, t, model, notify, kick, stage } = host;
+    const name = kit.name;
+    const where = (key) => sql `model = ${model} AND view = ${name} AND key = ${key}`;
+    yield* sql
+        .withTransaction(Effect.gen(function* () {
+        const rows = yield* sql `
+            SELECT generation FROM ${t("views")} WHERE model = ${model} AND view = ${name} FOR UPDATE`;
+        const stored = rows[0]?.generation;
+        if (stored !== undefined && stored >= kit.generation)
+            return;
+        // Rebuilt: start every key over. Without a backfill, keys refill from new events only.
+        yield* sql `DELETE FROM ${t("view_keys")} WHERE model = ${model} AND view = ${name}`;
+        yield* sql `DELETE FROM ${t("view_entries")} WHERE model = ${model} AND view = ${name}`;
+        yield* sql `
+            INSERT INTO ${t("views")} (model, view, generation) VALUES (${model}, ${name}, ${kit.generation})
+            ON CONFLICT (model, view) DO UPDATE SET generation = EXCLUDED.generation`;
+    }))
+        .pipe(Effect.orDie);
+    const read = (key) => Effect.map(sql `SELECT snapshot FROM ${t("view_keys")} WHERE ${where(key)}`, (rows) => rows[0]?.snapshot ?? emptySnapshot).pipe(Effect.orDie);
+    const entriesAfter = (key, after) => Effect.map(sql `
+          SELECT entry FROM ${t("view_entries")} WHERE ${where(key)} AND seq > ${after} ORDER BY seq`, (rows) => rows.map((row) => row.entry)).pipe(Effect.orDie);
+    const apply = (key, deliveries) => Effect.gen(function* () {
+        yield* sql `
+          INSERT INTO ${t("view_keys")} (model, view, key, snapshot)
+          VALUES (${model}, ${name}, ${key}, ${sql.json(emptySnapshot)}) ON CONFLICT DO NOTHING`;
+        const rows = yield* sql `
+          SELECT snapshot FROM ${t("view_keys")} WHERE ${where(key)} FOR UPDATE`;
+        const before = rows[0]?.snapshot ?? emptySnapshot;
+        const result = yield* kit.apply(key, before, deliveries);
+        if (!result.changed)
+            return false;
+        yield* sql `UPDATE ${t("view_keys")} SET snapshot = ${sql.json(result.snapshot)} WHERE ${where(key)}`;
+        yield* Effect.forEach(result.entries, (entry) => sql `
+            INSERT INTO ${t("view_entries")} (model, view, key, seq, entry)
+            VALUES (${model}, ${name}, ${key}, ${entry.seq}, ${sql.json(entry)})`, { discard: true });
+        yield* stage(result.downstream);
+        return true;
+    });
+    const store = {
+        receive: (key, deliveries) => sql.withTransaction(apply(key, deliveries)).pipe(Effect.orDie, Effect.tap((changed) => changed ? Effect.andThen(notify.bump(`v:${name}/${key}`), kick) : Effect.void), Effect.asVoid, kit.observe(key, deliveries)),
+        read,
+        changes: (key) => notify.changes(`v:${name}/${key}`, read(key)),
+        list: (key) => entriesAfter(key, 0),
+        tail: (key, after) => {
+            let last = after;
+            return notify.changes(`v:${name}/${key}`, Effect.void).pipe(Stream.flatMap(() => Stream.unwrap(Effect.map(entriesAfter(key, last), (fresh) => {
+                const newest = fresh.at(-1);
+                if (newest)
+                    last = newest.seq;
+                return Stream.fromIterable(fresh);
+            }))));
+        },
+    };
+    return store;
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { layer, type Options } from "./adapters/postgres-platform.ts";
+export { migrate, TablesMissing } from "./adapters/tables.ts";
+export { domainStore, fromEnv, LOCAL_DATABASE_URL, PgForTests, platformForTests, testSchema, } from "./adapters/from-env.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { layer } from "./adapters/postgres-platform.js";
+export { migrate, TablesMissing } from "./adapters/tables.js";
+export { domainStore, fromEnv, LOCAL_DATABASE_URL, PgForTests, platformForTests, testSchema, } from "./adapters/from-env.js";

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@house-rules/domain-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "A Postgres Platform for Alchemy Domain: events, state, views and an outbox in your own Postgres.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakubSzwajka/house-rules.git",
+    "directory": "packages/domain-postgres"
+  },
+  "bugs": {
+    "url": "https://github.com/JakubSzwajka/house-rules/issues"
+  },
+  "homepage": "https://github.com/JakubSzwajka/house-rules",
+  "dependencies": {
+    "@effect/sql-pg": "4.1.2"
+  },
+  "peerDependencies": {
+    "@alchemy.run/domain": "2.0.0-beta.85",
+    "alchemy": "2.0.0-beta.85",
+    "effect": "4.1.2"
+  },
+  "devDependencies": {
+    "@alchemy.run/domain": "2.0.0-beta.85",
+    "@effect/vitest": "4.1.2",
+    "alchemy": "2.0.0-beta.85",
+    "effect": "4.1.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run && DOMAIN_STORE=memory vitest run"
+  }
 }