@house-rules/relations 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,40 @@
+# @house-rules/relations: notes for agents
+
+Relations stores typed edges between opaque `(kind, id)` nodes. It owns structural validation and graph traversal, not authority. The package is publish-ready but is not part of the release workflow.
+
+## Boundary
+
+Relations takes NO host port and performs NO access checks and NO node-existence checks. It validates only STRUCTURE from its config. The consuming app verifies endpoint existence and access in its feature BEFORE calling relate/unrelate. Authority-bearing relationships, including memberships and roles, belong to `@house-rules/party`, never here.
+
+if removing an edge changes what someone may DO, it belongs in party; if it only changes what is shown or computed, it belongs in relations.
+
+Do not add a target-access port, caller parameter, role lookup or endpoint-existence lookup. Reads also return structural facts without filtering. Apps must guard graph reads and avoid exposing edges or node ids the caller cannot see.
+
+## Mounting
+
+Import `Relations` and `RelationsMount` from the main door. Composition selects `Relations.layerMemory(options)` or `Relations.layerPostgres(options)`, and pairs the mount with that layer. Provide one shared unit adapter. Postgres also needs `SqlClient` and the module's migrations, registered as `{ "workspace": "packages/relations" }` in this workspace or by package in an installed app.
+
+There is no host port. `RelationStore` is the module-owned storage port; adapters answer facts, while domain code checks structural limits. `bindRelations` captures the service once and supports person and system execution equally. The browser-safe contract door exports schemas, errors, permissions and `RelationsOperations`, never layers or bindings.
+
+## Options and operations
+
+Pass `nodeKinds`, `relationTypes`, `maxGraphSize` and `maxPageSize`. Each relation type declares `name`, allowed `source`/`target` kinds, `directed`, `acyclic`, `unique` and optional cardinality caps. Kind sets must be nonempty subsets of `nodeKinds`; type names and node kinds must be unique. Caps are positive integers. Directed types accept `maxOutPerSource` and `maxInPerTarget`; symmetric types accept `maxDegree` and cannot be acyclic.
+
+`Relations.presets.default` supplies only graph/page limits. Add app-specific kinds and types in code. See [README.md](README.md) for an example and traversal semantics.
+
+- `Relations.relate` and `Relations.unrelate` declare `relations:write` and are transactional. Unrelate is destructive.
+- `Relations.listRelations` and `Relations.subgraph` declare `relations:read` and are read-only.
+- `relate` returns `{ relation, events: [Related] }`; `unrelate` returns `{ events: [Unrelated] }`. `RelationEvents` in `./contract` declares facts with `kind: "Related"` or `kind: "Unrelated"`, `type`, `source: { kind, id }` and `target: { kind, id }`. Facts use stored endpoint order, including symmetric canonicalization. Read results are unchanged.
+- `removeNode(ref)` is an idempotent facade hook, not an operation. Call it inside the node-deletion feature's unit. It accepts any nonempty kind and id, even after the kind is removed from config. It returns void and no events because node deletion is a fact owned by the node's module.
+
+## Fixed rules
+
+The module returns event facts as plain data. It never emits, depends on event-log or reads `CurrentActor`. Features decide whether to record facts through explicit event-log edges; event-log supplies the envelope.
+
+Writes require `UnitOfWork.required`. The module never opens a unit. Memory registers undo before mutation and uses the shared `memoryUnitOfWork` to serialize units. Postgres joins the open transaction. Before insertion checks, it takes a transaction-scoped advisory lock with a fixed Relations namespace and a hash of the type name. Writes of one type are serialized; different types run in parallel. Features relating several types in one unit must relate them in a fixed, sorted type-name order across all callers to avoid deadlocks between per-type advisory locks. Deletions need no advisory lock because they cannot create a cycle or exceed a cap. The checks rely on READ COMMITTED; the default isolation level is assumed. Use the same module config for every process sharing a database.
+
+Node references are plain kind/id columns with no cross-module foreign keys. Symmetric edges use deterministic endpoint order, including when the allowed endpoint kinds differ. A self-edge counts once toward `maxDegree`; directed acyclic types reject it.
+
+Cycle traversal uses a bounded memory walk or a recursive Postgres CTE. `maxGraphSize` bounds visited nodes during cycle checks, and bounds both nodes and edges returned by subgraph BFS. Crossing a bound fails `GraphTooLarge`, never returns a partial graph. Parallel edges count separately. Depth zero returns only the root. Direction follows stored order; use `both` for symmetric traversal.
+
+Unavailable errors use fixed public text and retain causes internally. Test changes against both memory and real Postgres with `MigrationsTesting.database`. Run `pnpm check` and `pnpm test` before calling work ready.

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,79 @@
-# Temporary Holding Version
+# @house-rules/relations
 
-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.
+Typed structural edges between opaque nodes, with cardinality and cycle checks. The package is publish-ready but is not part of the release workflow. Nothing has been published.
+
+Relations does not check access or node existence. The app must verify both endpoints in its feature before it calls `relate` or `unrelate`. Memberships, roles and other authority-bearing relationships belong in Party.
+
+> if removing an edge changes what someone may DO, it belongs in party; if it only changes what is shown or computed, it belongs in relations.
+
+## Configure and mount
+
+```ts
+import { Relations, RelationsMount } from "@house-rules/relations";
+
+const relations = Relations.layerMemory({
+  ...Relations.presets.default,
+  nodeKinds: ["document", "folder"],
+  relationTypes: [
+    {
+      name: "contains",
+      source: ["folder"],
+      target: ["folder", "document"],
+      directed: true,
+      acyclic: true,
+      unique: true,
+      maxInPerTarget: 1,
+    },
+  ],
+});
+```
+
+Composition pairs `RelationsMount` with this layer and a shared `memoryUnitOfWork`. For Postgres, select `Relations.layerPostgres` instead, provide `SqlClient` and `sqlUnitOfWork`, and run the owning module's `migrations/` through `@house-rules/migrations`. This workspace registers it in root `migrations.json`. There are no cross-module foreign keys and no host-access port.
+
+All limits are positive integers. Endpoint kind lists must be nonempty subsets of `nodeKinds`. Duplicate node kinds or type names fail layer acquisition with `RelationsInputInvalid`. Symmetric types cannot be acyclic or use directed cardinality caps. Directed types cannot use `maxDegree`.
+
+## Operations
+
+The browser-safe `@house-rules/relations/contract` door exports `RelationsOperations`, `RelationEvents`, schemas, errors and `RelationsPermissions`. Features declare these descriptors as edges; composition captures the service with `bindRelations` through `RelationsMount`.
+
+| Operation | Input | Result | Permission and flags |
+| --- | --- | --- | --- |
+| `relate` | `{ type, source: { kind, id }, target: { kind, id } }` | `{ relation, events: [Related] }`; relation has `id` and epoch-millisecond `createdAt` | `relations:write`, transactional |
+| `unrelate` | `{ id }` | `{ events: [Unrelated] }` | `relations:write`, transactional, destructive |
+| `listRelations` | `{ node, type?, direction, page?: { size?, cursor? } }` | `{ edges, next? }` | `relations:read`, readOnly |
+| `subgraph` | `{ root, type, direction, depth? }` | `{ nodes, edges }` | `relations:read`, readOnly |
+
+Facade methods use the same input objects, except `unrelate(id)` takes the id directly. They take no Actor. Person and system bindings behave the same after the app's permission gates.
+
+`RelationEvents.Related` and `RelationEvents.Unrelated` declare `{ kind: "Related" | "Unrelated", type, source: { kind, id }, target: { kind, id } }`. Each successful write returns its fact in stored endpoint order. Unrelate returns the endpoints of the edge it actually deleted. Read results are unchanged. The module returns plain data, never emits, never depends on event-log and never reads `CurrentActor`. Features choose whether to record facts through explicit event-log edges; event-log supplies the envelope.
+
+`removeNode(ref)` is a facade-only cascade hook. Call it inside the same feature unit that deletes a node. It removes every touching edge, across all types, and succeeds when none exist. It accepts any nonempty kind and id, including a kind removed from config. It does not delete or verify the node. It returns void and no events because node deletion is a fact owned by the node's module.
+
+## Graph semantics
+
+Symmetric types store endpoints in deterministic kind-then-id order. Either input orientation is valid if it matches the declared endpoint kind pairing. Reversing the arguments finds the same duplicate when `unique` is true. Set `unique: false` to allow parallel edges with separate ids.
+
+Directions `out` and `in` follow stored source and target columns. Use `both` for symmetric edges. Lists order by `(createdAt, id)` and use an exclusive cursor; requested page size is capped at `maxPageSize`.
+
+Directed caps count edges leaving a source or entering a target, per type. Symmetric `maxDegree` counts touching edges, including a self-edge once. Each parallel edge counts. Checks run inside the write unit. Postgres serializes insertions of one relation type with a transaction-scoped advisory lock; different types can run in parallel. Deletions need no advisory lock. The checks rely on the assumed default READ COMMITTED isolation level. Memory uses the shared unit adapter's serialization.
+
+For an acyclic directed type, `relate(source, target)` searches from target for source before insertion. Self-edges fail `RelationCycle`. Postgres uses a recursive CTE with node deduplication and a demand limit; memory walks the same directed graph. If visited nodes exceed `maxGraphSize`, the write fails `GraphTooLarge` rather than assuming the graph is acyclic.
+
+Subgraph uses BFS. Omitted depth traverses until exhaustion or the bound; depth zero returns the opaque root alone even if it has no edges. Nodes and edges are deduplicated by reference and edge id. Both counts must fit `maxGraphSize`, so parallel edges cannot produce an unbounded result. Exceeding either bound fails `GraphTooLarge` without a partial result.
+
+## Failures and units
+
+Unknown types and invalid endpoints use `RelationTypeUnknown` and `RelationEndpointInvalid`. Duplicate, cardinality and cycle failures are conflicts. Removing an absent id returns `RelationNotFound`. Invalid page/depth/options use `RelationsInputInvalid`; oversized traversal uses `GraphTooLarge`. Store failures use `RelationsStoreUnavailable` with fixed public text and an internal cause.
+
+Every write, including the cascade hook and adapter writes, fails `NoOpenUnit` outside a live unit. The module never opens one. Memory undo runs on rollback; Postgres joins the existing transaction.
+
+## Tests
+
+```sh
+docker compose up -d
+pnpm --filter @house-rules/relations typecheck
+pnpm --filter @house-rules/relations build
+pnpm --filter @house-rules/relations test
+```
+
+Shared storage and structural suites run on memory and a fresh real Postgres database created through `MigrationsTesting.database`. Runtime tests exercise the mount, bindings and transactional feature execution.

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

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

package/dist/adapters/memory/relation.js

@@ -0,0 +1,67 @@
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer } from "effect";
+import { compareRelations, copyRelation, nodeKey, sameNode, touches, } from "../../relation/graph.js";
+import { RelationsStoreUnavailable } from "../../relation/relation.js";
+import { RelationStore } from "../../storage.js";
+export const memoryRelationStore = () => Layer.sync(RelationStore, () => {
+    const rows = new Map();
+    const change = Effect.fn("RelationStore.memory.change")(function* (run) {
+        yield* UnitOfWork.required;
+        const before = new Map([...rows].map(([id, edge]) => [id, copyRelation(edge)]));
+        yield* UnitOfWork.onRollback(Effect.sync(() => {
+            rows.clear();
+            for (const [id, edge] of before)
+                rows.set(id, edge);
+        }));
+        run();
+    });
+    return RelationStore.of({
+        lock: () => UnitOfWork.required,
+        list: (node, type, direction, size, after) => Effect.sync(() => [...rows.values()]
+            .filter((edge) => (type === undefined || edge.type === type) &&
+            touches(edge, node, direction) &&
+            (after === undefined || compareRelations(edge, { ...edge, ...after }) > 0))
+            .sort(compareRelations)
+            .slice(0, size)
+            .map(copyRelation)),
+        count: (node, type, direction) => Effect.sync(() => [...rows.values()].filter((edge) => edge.type === type && touches(edge, node, direction)).length),
+        exists: (source, target, type) => Effect.sync(() => [...rows.values()].some((edge) => edge.type === type && sameNode(edge.source, source) && sameNode(edge.target, target))),
+        reachable: (root, type, limit) => Effect.sync(() => {
+            const nodes = [{ ...root }];
+            const seen = new Set([nodeKey(root)]);
+            for (let i = 0; i < nodes.length && nodes.length < limit; i++) {
+                const node = nodes[i];
+                if (node === undefined)
+                    break;
+                for (const edge of rows.values()) {
+                    if (edge.type !== type ||
+                        !sameNode(edge.source, node) ||
+                        seen.has(nodeKey(edge.target)))
+                        continue;
+                    seen.add(nodeKey(edge.target));
+                    nodes.push({ ...edge.target });
+                    if (nodes.length >= limit)
+                        break;
+                }
+            }
+            return nodes;
+        }),
+        insert: Effect.fn("RelationStore.memory.insert")(function* (edge) {
+            yield* UnitOfWork.required;
+            if (rows.has(edge.id))
+                return yield* new RelationsStoreUnavailable({ cause: "Duplicate relation id." });
+            yield* change(() => void rows.set(edge.id, copyRelation(edge)));
+        }),
+        remove: Effect.fn("RelationStore.memory.remove")(function* (id) {
+            yield* UnitOfWork.required;
+            const found = rows.get(id);
+            yield* change(() => void rows.delete(id));
+            return found === undefined ? undefined : copyRelation(found);
+        }),
+        removeNode: (node) => change(() => {
+            for (const [id, edge] of rows)
+                if (touches(edge, node, "both"))
+                    rows.delete(id);
+        }),
+    });
+});

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

@@ -0,0 +1,4 @@
+import { Layer } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+import { RelationStore } from "../../storage.js";
+export declare const postgresRelationStore: Layer.Layer<RelationStore, never, SqlClient>;

package/dist/adapters/postgres/relation.js

@@ -0,0 +1,49 @@
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer, Schema } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+import { NodeRef, Relation, RelationsStoreUnavailable } from "../../relation/relation.js";
+import { RelationStore } from "../../storage.js";
+const unavailable = (cause) => new RelationsStoreUnavailable({ cause });
+export const postgresRelationStore = Layer.effect(RelationStore, Effect.gen(function* postgresRelationStore() {
+    const sql = yield* SqlClient;
+    const columns = sql.literal(`id, type, json_build_object('kind', source_kind, 'id', source_id) as source, json_build_object('kind', target_kind, 'id', target_id) as target, created_at::float8 as "createdAt"`);
+    const read = (query) => query.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(Relation))), Effect.mapError(unavailable));
+    const write = Effect.fn("RelationStore.postgres.write")(function* (query) {
+        yield* UnitOfWork.required;
+        yield* query.pipe(Effect.mapError(unavailable));
+    });
+    const at = (node, direction) => sql.or([
+        ...(direction !== "in"
+            ? [sql `(source_kind = ${node.kind} and source_id = ${node.id})`]
+            : []),
+        ...(direction !== "out"
+            ? [sql `(target_kind = ${node.kind} and target_id = ${node.id})`]
+            : []),
+    ]);
+    return RelationStore.of({
+        // Serialize same-type checks through commit. READ COMMITTED sees the preceding writer.
+        lock: (type) => write(sql `select pg_advisory_xact_lock(1919249505, hashtext(${type}))`),
+        list: (node, type, direction, size, after) => read(sql `
+        select ${columns} from relation_edges where ${at(node, direction)}
+        and ${type === undefined ? sql `true` : sql `type = ${type}`}
+        and ${after === undefined ? sql `true` : sql `(created_at, id collate "C") > (${after.createdAt}, ${after.id})`}
+        order by created_at, id collate "C" limit ${size}`),
+        count: (node, type, direction) => sql `select count(*)::float8 as count from relation_edges where type = ${type} and ${at(node, direction)}`.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ count: Schema.Int })))), Effect.map((rows) => rows[0]?.count ?? 0), Effect.mapError(unavailable)),
+        exists: (source, target, type) => sql `select id from relation_edges where type = ${type} and source_kind = ${source.kind} and source_id = ${source.id} and target_kind = ${target.kind} and target_id = ${target.id} limit 1`.pipe(Effect.map((rows) => rows.length > 0), Effect.mapError(unavailable)),
+        // UNION deduplicates nodes. The outer LIMIT stops recursive demand at the bound.
+        reachable: (root, type, limit) => sql `
+        with recursive reached(kind, id) as (
+          select ${root.kind}::text, ${root.id}::text
+          union
+          select e.target_kind, e.target_id from relation_edges e join reached r
+            on e.source_kind = r.kind and e.source_id = r.id where e.type = ${type}
+        ) select kind, id from reached limit ${limit}`.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(NodeRef))), Effect.mapError(unavailable)),
+        insert: (edge) => write(sql `insert into relation_edges (id, type, source_kind, source_id, target_kind, target_id, created_at) values (${edge.id}, ${edge.type}, ${edge.source.kind}, ${edge.source.id}, ${edge.target.kind}, ${edge.target.id}, ${edge.createdAt})`),
+        remove: Effect.fn("RelationStore.postgres.remove")(function* (id) {
+            yield* UnitOfWork.required;
+            const rows = yield* read(sql `delete from relation_edges where id = ${id} returning ${columns}`);
+            return rows[0];
+        }),
+        removeNode: (node) => write(sql `delete from relation_edges where ${at(node, "both")}`),
+    });
+}));

package/dist/contract.d.ts

@@ -0,0 +1,4 @@
+export { RelateResult, RelationEvents, UnrelateResult } from "./relation/events.js";
+export { DuplicateRelation, GraphTooLarge, ListRelationsInput, NodeRef, RelateInput, Relation, RelationCardinalityExceeded, RelationCursor, RelationCycle, RelationDirection, RelationEndpointInvalid, RelationGraph, RelationList, RelationNotFound, RelationPage, RelationsInputInvalid, RelationsStoreUnavailable, RelationTypeUnknown, SubgraphInput, } from "./relation/relation.js";
+export { RelationsOperations } from "./relation/operations.js";
+export { RelationsPermissions, type RelationsPermission } from "./relation/permissions.js";

package/dist/contract.js

@@ -0,0 +1,4 @@
+export { RelateResult, RelationEvents, UnrelateResult } from "./relation/events.js";
+export { DuplicateRelation, GraphTooLarge, ListRelationsInput, NodeRef, RelateInput, Relation, RelationCardinalityExceeded, RelationCursor, RelationCycle, RelationDirection, RelationEndpointInvalid, RelationGraph, RelationList, RelationNotFound, RelationPage, RelationsInputInvalid, RelationsStoreUnavailable, RelationTypeUnknown, SubgraphInput, } from "./relation/relation.js";
+export { RelationsOperations } from "./relation/operations.js";
+export { RelationsPermissions } from "./relation/permissions.js";

package/dist/facade.d.ts

@@ -0,0 +1,313 @@
+import { Effect, Layer } from "effect";
+import { RelationsOptions } from "./relation/options.js";
+import { RelationsInputInvalid } from "./relation/relation.js";
+import { RelationStore } from "./storage.js";
+declare const Relations_base: import("effect/Context").ServiceClass<Relations, "relations", {
+    relate: (input: {
+        readonly type: string;
+        readonly source: {
+            readonly kind: string;
+            readonly id: string;
+        };
+        readonly target: {
+            readonly kind: string;
+            readonly id: string;
+        };
+    }) => Effect.Effect<{
+        relation: {
+            readonly id: string;
+            readonly type: string;
+            readonly source: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly target: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly createdAt: number;
+        };
+        events: {
+            kind: "Related";
+            type: string;
+            source: {
+                kind: string;
+                id: string;
+            };
+            target: {
+                kind: string;
+                id: string;
+            };
+        }[];
+    }, import("./relation/relation.js").DuplicateRelation | import("./relation/relation.js").GraphTooLarge | import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationCardinalityExceeded | import("./relation/relation.js").RelationCycle | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+    unrelate: (id: string) => Effect.Effect<{
+        events: {
+            kind: "Unrelated";
+            type: string;
+            source: {
+                kind: string;
+                id: string;
+            };
+            target: {
+                kind: string;
+                id: string;
+            };
+        }[];
+    }, import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationNotFound | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+    listRelations: (input: {
+        readonly node: {
+            readonly kind: string;
+            readonly id: string;
+        };
+        readonly type?: string;
+        readonly direction: "both" | "in" | "out";
+        readonly page?: {
+            readonly size?: number;
+            readonly cursor?: {
+                readonly createdAt: number;
+                readonly id: string;
+            };
+        };
+    }) => Effect.Effect<{
+        edges: {
+            readonly id: string;
+            readonly type: string;
+            readonly source: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly target: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly createdAt: number;
+        }[];
+        next: {
+            createdAt: number;
+            id: string;
+        };
+    } | {
+        next?: never;
+        edges: {
+            readonly id: string;
+            readonly type: string;
+            readonly source: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly target: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly createdAt: number;
+        }[];
+    }, import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | RelationsInputInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+    subgraph: (input: {
+        readonly root: {
+            readonly kind: string;
+            readonly id: string;
+        };
+        readonly type: string;
+        readonly direction: "both" | "in" | "out";
+        readonly depth?: number;
+    }) => Effect.Effect<{
+        nodes: {
+            kind: string;
+            id: string;
+        }[];
+        edges: {
+            readonly id: string;
+            readonly type: string;
+            readonly source: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly target: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly createdAt: number;
+        }[];
+    }, import("./relation/relation.js").GraphTooLarge | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | RelationsInputInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+    removeNode: (ref: {
+        readonly kind: string;
+        readonly id: string;
+    }) => Effect.Effect<void, import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+}> & {
+    readonly id: "relations";
+} & {
+    readonly make: (options: {
+        readonly nodeKinds: readonly string[];
+        readonly relationTypes: readonly {
+            readonly name: string;
+            readonly source: readonly string[];
+            readonly target: readonly string[];
+            readonly directed: boolean;
+            readonly acyclic: boolean;
+            readonly unique: boolean;
+            readonly maxOutPerSource?: number;
+            readonly maxInPerTarget?: number;
+            readonly maxDegree?: number;
+        }[];
+        readonly maxGraphSize: number;
+        readonly maxPageSize: number;
+    }) => Effect.Effect<{
+        relate: (input: {
+            readonly type: string;
+            readonly source: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly target: {
+                readonly kind: string;
+                readonly id: string;
+            };
+        }) => Effect.Effect<{
+            relation: {
+                readonly id: string;
+                readonly type: string;
+                readonly source: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly target: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly createdAt: number;
+            };
+            events: {
+                kind: "Related";
+                type: string;
+                source: {
+                    kind: string;
+                    id: string;
+                };
+                target: {
+                    kind: string;
+                    id: string;
+                };
+            }[];
+        }, import("./relation/relation.js").DuplicateRelation | import("./relation/relation.js").GraphTooLarge | import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationCardinalityExceeded | import("./relation/relation.js").RelationCycle | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+        unrelate: (id: string) => Effect.Effect<{
+            events: {
+                kind: "Unrelated";
+                type: string;
+                source: {
+                    kind: string;
+                    id: string;
+                };
+                target: {
+                    kind: string;
+                    id: string;
+                };
+            }[];
+        }, import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationNotFound | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+        listRelations: (input: {
+            readonly node: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly type?: string;
+            readonly direction: "both" | "in" | "out";
+            readonly page?: {
+                readonly size?: number;
+                readonly cursor?: {
+                    readonly createdAt: number;
+                    readonly id: string;
+                };
+            };
+        }) => Effect.Effect<{
+            edges: {
+                readonly id: string;
+                readonly type: string;
+                readonly source: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly target: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly createdAt: number;
+            }[];
+            next: {
+                createdAt: number;
+                id: string;
+            };
+        } | {
+            next?: never;
+            edges: {
+                readonly id: string;
+                readonly type: string;
+                readonly source: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly target: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly createdAt: number;
+            }[];
+        }, import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | RelationsInputInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+        subgraph: (input: {
+            readonly root: {
+                readonly kind: string;
+                readonly id: string;
+            };
+            readonly type: string;
+            readonly direction: "both" | "in" | "out";
+            readonly depth?: number;
+        }) => Effect.Effect<{
+            nodes: {
+                kind: string;
+                id: string;
+            }[];
+            edges: {
+                readonly id: string;
+                readonly type: string;
+                readonly source: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly target: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+                readonly createdAt: number;
+            }[];
+        }, import("./relation/relation.js").GraphTooLarge | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationTypeUnknown | RelationsInputInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+        removeNode: (ref: {
+            readonly kind: string;
+            readonly id: string;
+        }) => Effect.Effect<void, import("@house-rules/domain").NoOpenUnit | import("./relation/relation.js").RelationEndpointInvalid | import("./relation/relation.js").RelationsStoreUnavailable, never>;
+    }, RelationsInputInvalid, RelationStore>;
+    readonly layer: (options: {
+        readonly nodeKinds: readonly string[];
+        readonly relationTypes: readonly {
+            readonly name: string;
+            readonly source: readonly string[];
+            readonly target: readonly string[];
+            readonly directed: boolean;
+            readonly acyclic: boolean;
+            readonly unique: boolean;
+            readonly maxOutPerSource?: number;
+            readonly maxInPerTarget?: number;
+            readonly maxDegree?: number;
+        }[];
+        readonly maxGraphSize: number;
+        readonly maxPageSize: number;
+    }) => import("@house-rules/domain").ModuleLayer<Relations, RelationsInputInvalid, RelationStore>;
+};
+export declare class Relations extends Relations_base {
+    static readonly presets: {
+        readonly default: {
+            readonly maxGraphSize: 1000;
+            readonly maxPageSize: 100;
+        };
+    };
+    static readonly layerMemory: (options: RelationsOptions) => Layer.Layer<Relations, RelationsInputInvalid, never>;
+    static readonly layerPostgres: (options: RelationsOptions) => Layer.Layer<Relations, RelationsInputInvalid, import("effect/sql/SqlClient").SqlClient>;
+}
+export {};

package/dist/facade.js

@@ -0,0 +1,19 @@
+import { defineModule } from "@house-rules/domain";
+import { Effect, Layer, Schema } from "effect";
+import { memoryRelationStore } from "./adapters/memory/relation.js";
+import { postgresRelationStore } from "./adapters/postgres/relation.js";
+import { RelationsOptions } from "./relation/options.js";
+import { RelationsInputInvalid } from "./relation/relation.js";
+import { makeRelations } from "./relation/relations.js";
+import { RelationStore } from "./storage.js";
+export class Relations extends defineModule()("relations", {
+    make: (options) => Effect.gen(function* relationsLayer() {
+        const settings = yield* Schema.decodeEffect(RelationsOptions)(options).pipe(Effect.mapError(() => new RelationsInputInvalid()));
+        const store = yield* RelationStore;
+        return makeRelations(store, settings);
+    }),
+}) {
+    static presets = { default: { maxGraphSize: 1000, maxPageSize: 100 } };
+    static layerMemory = (options) => this.layer(options).pipe(Layer.provide(memoryRelationStore()));
+    static layerPostgres = (options) => this.layer(options).pipe(Layer.provide(postgresRelationStore));
+}