@house-rules/party 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,67 @@
+# @house-rules/party
+
+## What it does
+
+Party owns person and agent principals, organisations, relationships, roles and assignments. It owns their tables and migrations. Identity owns login bindings. Party stores no login credentials.
+
+## Mount and bind
+
+Call `Party.layerMemory({ builtInRoles })` or `Party.layerPostgres({ builtInRoles })`. Each role entry is `{ name, permissions }`, keyed by role key. Raw `Party.layer(options)` needs `PersonStore` and `PartyStore`. Share the app's unit adapter. Postgres also needs the shared SQL client.
+
+Register this package in `migrations.json`. Never edit applied migrations. `0001` owns persons; `0002` adds organisations, relationships, custom roles and assignments; `0003` adds hashed one-time invitations; append-only `0004` publishes party_staff_read (person_id, organisation_id), containing current person-to-organisation staff relationships only. Read models may select this view for SQL privacy filters, never the relationship table. No cross-module foreign keys.
+
+Import PermissionCatalogue from application, not Party. Composition supplies its `permissions: () => Effect<readonly Permission[]>` before building modules. It and Runtime.permissions expose the same mount-derived array. Custom-role writes fail closed without the port. May filters permissions when the port is present. Exported PartyMount contains Party, all PartyOperations and bindParty; add the chosen layer in composition/modules.ts.
+
+Declare builtInRoles, systemPermissions and `may = Party.may()` in composition/access.ts. Pass `may` to composition in app.ts and roles to Party's mount in modules.ts. It resolves the MaySocket after Party is built. Its `permissionsOf(caller: PersonCaller)` returns an Effect of permissions with no requirements. It captures the built Party service. It does not cache assignments.
+
+## Operations
+
+Use `PartyOperations` from the browser-safe contract door. Bind all descriptors with `bindParty(service)`. App features call them through declared edges. Only features are exposed. All operation edges are empty.
+
+| Operation | Permission | Flags |
+| --- | --- | --- |
+| createPerson, createPrincipal | party:create | transactional |
+| disable | party:update | transactional, destructive, needsApproval |
+| lockActive | party:read | transactional |
+| principalsByIds, findPrincipal, holdersOf | party:read | readOnly |
+| showPerson, showMe | party:read | readOnly |
+| renamePerson | party:update | transactional |
+| createOrganisation | party:create-organisation | transactional |
+| relate, defineRole, assignRole, createInvitation | party:admin | transactional |
+| acceptInvitation | party:read | transactional |
+| listInvitations, listPeople | party:admin | readOnly |
+| myOrganisations, listMembers | party:read | readOnly |
+| revokeInvitation | party:admin | transactional, destructive, needsApproval |
+| unrelate, revokeRole, deleteRole | party:admin | transactional, destructive, needsApproval |
+| showOrganisation, isRelated, canAdminOrganisation, listRoles, rolesOf, myAccess | party:read | readOnly |
+
+## Service and fixed rules
+
+- `0005_principals.sql` adds principal kind, unique immutable handle, createdBy and disabledAt. It backfills existing people with kind person, handle=id and null provenance/disable time. Legacy handles and `createPerson` bypass the new validation; Person and existing operations keep their old shapes. The migration publishes `party_principals_read(id, display_name, kind, handle, created_by, created_at, disabled_at)` and `party_assignments_read(person_id, role_key, organisation_id)` for app read models.
+- `createPrincipal({ id?, displayName, kind, handle, createdBy })` is system-only. Kind is person or agent; createdBy is an ActorId or null passed as data. New handles contain 1 to 120 characters. `handles: { pattern?: RegExp, reserved?: readonly string[] }` supplies app policy. Matching is case-sensitive, with no normalization. Handle uniqueness spans both kinds and concurrent creates.
+- `disable({ id })` is system-only, irreversible, transactional, destructive and approval-gated. It returns `{ principal, fact }`, with a `principal.disabled` fact carrying before/after or null when already disabled. Creation returns a `principal.created` fact carrying after. Composition chooses recording in the same unit. Party never emits events. There is no enable. Protecting a person owner is app policy, not a Party role rule.
+- `standingOf(actorId)` is a facade method for Identity's caller-owned standing slot, not an operation. It answers active, disabled or missing. May also returns no permissions for disabled principals. New request admission belongs to Identity; already admitted requests without a lock may finish after disable.
+- `lockActive({ handle, kind })` accepts person and system callers with party:read and requires a live unit. It returns a principal, or PersonNotFound for unknown handles and kind mismatches for person callers. System callers may receive PrincipalKindRefused for a kind mismatch. Disabled targets return PersonNotFound to person callers and PrincipalDisabledRefused to system callers. Kind agent refuses a person owner. Postgres holds FOR SHARE until unit end, never FOR KEY SHARE. Disable locks FOR NO KEY UPDATE before capturing its fact and waits for active locks. Locks after its commit fail. Memory relies on the shared memoryUnitOfWork's whole-unit serialization.
+- `findPrincipal({ handle })` accepts person and system callers with party:read. It returns the full principal by exact handle, including disabledAt for disabled principals, or PersonNotFound. It is a directory read, not an active-principal check.
+- `holdersOf({ role, scope? })` accepts person and system callers with party:read. Scope is one organisation id; omitted or null means global assignments only. It returns `{ ids, truncated }` in ascending id order, including disabled holders. Unknown roles and empty scopes return no ids. `holdersLimit` in Party options defaults to 1000 and must be a positive safe integer below Number.MAX_SAFE_INTEGER; invalid options fail acquisition with PartyInputInvalid. Adapters fetch at most limit + 1 distinct ids; Party returns at most limit and flags overflow without failing unavailable. Storage failures remain typed PartyUnavailable. This is an assignment lookup, not a permission grant.
+- `principalsByIds({ ids })` accepts both person and system callers with party:read. It returns each matching principal once, includes disabled principals and omits missing ids. This is a directory read, not authority or credential admission.
+
+- `myAccess` is person-only and takes no target id. It reads only the caller's assignments, effective permissions and the public app catalogue. Postgres filters assignments by that caller id in SQL; memory uses the same port. System callers are refused.
+- Person creation is system-only at the binder. Person reads need a person caller. Rename allows only the target person. `erase(id)` is a trusted service hook, not an operation.
+- Global admins manage all scopes. An admin whose authority comes only from organisation X may manage roles and assignments only in X. Check both old and new scope when moving a custom role. Organisation creation accepts a person with party:create-organisation at the gate and relates the creator as staff. An app feature may bootstrap a scoped admin role through an explicit system assignRole edge.
+- A person defining or assigning a role must hold every permission it grants in the target scope. Global assignments count in any organisation; another organisation's assignments never count. This covers built-in roles and updates to already assigned custom roles. System assignment is exempt. `party:admin` alone cannot delegate unheld permissions.
+- Role reads take a caller. Organisation-scoped callers see global built-ins and custom roles only in their own organisations. Assignment reads apply the same scope filter. Postgres filters these lists in SQL; global admins and trusted system reads see all scopes.
+- Built-in keys are reserved. Custom permissions must have `resource:action` syntax and belong to the mount-derived catalogue. Organisation-scoped custom roles cannot be assigned outside their organisation.
+- System callers may assign roles for first sign-in. They cannot revoke roles, define roles or bypass other management checks. Ordinary person callers cannot use the system assignment path.
+- May unions every held role across contexts. It drops missing roles and permissions absent from the current catalogue. Revocation takes effect on the next call. MCP and HTTP get the same answer for the same Actor.
+- Invitations take `{ organisationId, roleKey: string | null }`. Creation checks the caller administers that org and holds every attached role permission there. It returns `{ invitation, code }` once. Codes use 256 random bits, SHA-256 storage and a seven-day expiry. Lists never return codes or hashes. Acceptance atomically consumes a pending unexpired code, relates the person as staff and returns `{ personId, organisationId, roleKey }`; an app feature assigns the optional role through a system edge in the same unit. Acceptance rechecks the inviter's current delegation authority. Unknown, used, revoked and expired codes are generic not_found. Revocation needs approval.
+- `myOrganisations` returns the caller's relationships or scoped assignments as `{ id, name, relation, roles: [{ roleKey, roleName, permissions }] }[]`. Roles are own org-scoped assignments only. Assignment-only membership has null relation; multiple relations use the first kind in lexical order.
+- `listPeople` returns `{ id, displayName, createdAt, assignments: [{ roleKey, roleName, organisationId, organisationName }], organisations: [{ id, name, relation }] }[]`. Global admins see all people and assignments. Scoped admins see only staff in administered orgs and only assignments and relations there, never global or other-org assignments. Non-admins get forbidden. Both adapters filter facts before returning; Postgres filters people, assignments and relations in SQL.
+- `listMembers({ organisationId })` needs `party:read` at the gate and admin authority in that org inside Party. It returns `{ id, displayName, createdAt, relation, roles: [{ roleKey, roleName }] }[]` for staff, with only org-scoped roles. Members, admins of other orgs and unknown ids get the same not_found. It needs no migration.
+- Removing a person's staff relation revokes all assignments scoped to that org in the same unit. Global assignments stay. Removing the last scoped org admin fails with conflict, with a clear message. Postgres locks the organisation before checking, so concurrent removals cannot remove both admins.
+- `canAdminOrganisation({ organisationId })` answers whether the current person holds party:admin globally or in that scope, using live assignments and the catalogue. It is a party:read operation, not an admin gate. It returns false for absent authority, including system callers. This lets modules own object checks through declared edges without requiring party:admin for every ordinary booking call.
+- Relationships are directional facts. Management checks every organisation endpoint. Other modules ask `isRelated` through an operation edge; they never query Party tables.
+- Domain checks run inside the write unit. All writes require `UnitOfWork.required`. Memory registers undo before mutation; Postgres joins the transaction. Modules never open units.
+- Expected errors declare kinds. Unavailable errors have fixed public messages and private diagnostic causes.
+
+The [README](README.md) lists inputs and mounting details. Shared suites test memory and real Postgres. Use `MigrationsTesting.database`, never mocked SQL. Tests use `it.effect` or `it.layer`.

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,143 @@
-# Temporary Holding Version
+# @house-rules/party
 
-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.
+`PartyOperations.myAccess` reads the caller's own assignments and effective permissions plus the app's public permission catalogue. It needs `party:read`, is read-only and refuses system callers. Bind it with `bindParty` like the other operations. It accepts no target person id. Both stores filter assignments by the caller id before returning them.
+
+Party owns person and agent principals, organisations, relationships, roles and role assignments. Identity owns login bindings. Party stores no email, issuer or login subject.
+
+## Mount
+
+```ts
+const options = {
+  builtInRoles: {
+    member: { name: "Member", permissions: ["party:read"] },
+    admin: { name: "Administrator", permissions: ["party:admin", "party:read"] },
+  },
+};
+const partyLayer = Party.layerPostgres(options).pipe(
+  Layer.provide(database),
+  Layer.provide(catalogueLayer),
+);
+```
+
+Use `Party.layerMemory(options)` for memory storage. Raw `Party.layer(options)` needs `PersonStore` and `PartyStore`. Share the app's unit adapter and SQL client. Register `@house-rules/party` in `migrations.json`. Migrations `0001` and `0002` create Party's core tables. Append-only `0003` adds invitations. `0004_publish_staff.sql` publishes `party_staff_read(person_id, organisation_id)` over current staff relationships. App read models may use it for SQL privacy filters. Modules still ask Party operations through declared edges, never read this view to make domain decisions.
+
+`PartyOperations.canAdminOrganisation({ organisationId })` needs party:read and returns whether the current person holds party:admin globally or in that scope. It uses live assignments and the catalogue. System callers and unrelated scoped admins get false.
+
+Import PartyMount from main and add `{ ...PartyMount, layer: chosenPartyLayer }` to the app's module plan. Composition captures Party and calls bindParty once. Pass `may: Party.may()`; composition resolves it after modules build. It captures Party and returns a MaySocket with no per-call requirements.
+
+`PermissionCatalogue` belongs to application, not Party. Its service shape is:
+
+```ts
+{ permissions: () => Effect<readonly Permission[]> }
+```
+
+Composition derives the catalogue from mount descriptors before acquiring Party. Its callback and Runtime.permissions expose the same array. Do not acquire Runtime inside Party's layer. There is no installation callback or mutable reference. Custom-role writes fail closed if the port is absent. Without a catalogue, May returns all held permissions. With it, May intersects them with the current catalogue on every call.
+
+## Operations
+
+Descriptors come from `@house-rules/party/contract`. Only app features are exposed. All operations have empty edges. `T` means transactional, `R` read-only, `D` destructive and `A` needs approval.
+
+| Member | Permission | Flags |
+| --- | --- | --- |
+| createPerson, createPrincipal | party:create | T |
+| disable | party:update | T D A |
+| lockActive | party:read | T |
+| principalsByIds, findPrincipal, holdersOf | party:read | R |
+| showPerson | party:read | R |
+| showMe | party:read | R |
+| myAccess | party:read | R |
+| renamePerson | party:update | T |
+| createOrganisation | party:create-organisation | T |
+| myOrganisations | party:read | R |
+| listPeople | party:admin | R |
+| listMembers | party:read | R |
+| createInvitation | party:admin | T |
+| acceptInvitation | party:read | T |
+| listInvitations | party:admin | R |
+| revokeInvitation | party:admin | T D A |
+| showOrganisation | party:read | R |
+| canAdminOrganisation | party:read | R |
+| relate | party:admin | T |
+| unrelate | party:admin | T D A |
+| isRelated | party:read | R |
+| defineRole | party:admin | T |
+| deleteRole | party:admin | T D A |
+| listRoles | party:read | R |
+| assignRole | party:admin | T |
+| revokeRole | party:admin | T D A |
+| rolesOf | party:read | R |
+
+Organisation creation takes `{ id, name }`. Relationships take `{ from: { kind, id }, to: { kind, id }, kind }`; endpoint kinds are `person` or `organisation`. Roles take `{ key, name, permissions, organisationId }`. Assignments take `{ personId, roleKey, organisationId }`. Use `null` for global scope. Role reads add `builtIn`.
+
+## Principals and standing
+
+`createPrincipal({ id?, displayName, kind, handle, createdBy })` creates a `person` or `agent`. It returns `{ principal, fact }`; the fact is `{ kind: "principal.created", after }`. `createdBy` is an ActorId or null, passed as data by the provisioning process. Party does not infer it from a system caller. Legacy `Person`, `createPerson`, reads and rename retain their existing shapes.
+
+Handle options are app policy:
+
+```ts
+Party.layerPostgres({
+  builtInRoles,
+  handles: {
+    pattern: /^[a-z][a-z0-9-]{0,31}$/u,
+    reserved: ["me", "none"],
+  },
+});
+```
+
+New handles must contain 1 to 120 characters. Without options there is no additional pattern or reserved word. Pattern and reserved checks are case-sensitive; Party never trims or lowercases handles. Handles are immutable and unique across both kinds, including concurrent creates. Duplicate handles or ids fail with `PersonAlreadyExists`; invalid or reserved handles fail with `PersonInputInvalid`. Migration `0005_principals.sql` backfills existing people with kind `person`, handle equal to id, and null `createdBy`/`disabledAt`. These legacy handles, including those made by `createPerson`, bypass the new handle validation so existing ids and account setup keep working.
+
+Caller rules at the operation boundary:
+
+- `createPrincipal` and `disable` accept only system callers. App provisioning features use explicit `asSystem` edges with reasons. Their permissions are `party:create` and `party:update` respectively.
+- `lockActive({ handle, kind })` accepts person and system callers with `party:read`. It needs an open unit and returns the principal. Unknown handles fail with `PersonNotFound`. A kind mismatch also returns `PersonNotFound` for person callers, so they cannot probe handles; system callers get `PrincipalKindRefused`. Disabled principals also return `PersonNotFound` to person callers; system callers get `PrincipalDisabledRefused`. Asking for kind `agent` rejects a person owner. Party does not know owner roles.
+- `principalsByIds({ ids })` accepts person and system callers with `party:read`. It returns matching principals once each, omits missing ids, and includes disabled principals. It exposes no credentials. This supports notification paths as well as person-facing names.
+- `findPrincipal({ handle })` accepts person and system callers with `party:read`. It matches the exact handle and returns the full principal, including id, kind, displayName, handle, createdBy, createdAt and disabledAt. Missing handles fail with `PersonNotFound`. Disabled principals are returned, not refused. Callers decide whether standing permits their action.
+- `holdersOf({ role, scope? })` accepts person and system callers with `party:read`. The role is its key; scope is one organisation id. Omitted or null scope selects global assignments only, never assignments across all organisations. It returns `{ ids, truncated }` in ascending id order, without duplicates, including disabled holders. Unknown roles or scopes with no assignments return `{ ids: [], truncated: false }`. This lookup grants no authority.
+- `standingOf(actorId)` is a facade method for a caller-owned Identity standing slot, not an operation. It returns `active`, `disabled` or `missing`; storage failures remain typed unavailable errors.
+
+Both lookups are read-only and need no unit. Set `holdersLimit` in `Party.layerMemory`, `Party.layerPostgres` or raw `Party.layer` options to bound each `holdersOf` result. The default is 1000. The limit must be a positive safe integer below `Number.MAX_SAFE_INTEGER`; invalid options fail layer acquisition with `PartyInputInvalid`. Adapters fetch at most limit + 1 distinct ids, then Party returns at most limit ids. `truncated` is true only when another matching id exists. Overflow is not an unavailable error; actual storage failures remain typed unavailable errors. Consumers that require complete results must check the flag.
+
+`disable({ id })` permanently sets `disabledAt` and returns `{ principal, fact }`. A first disable returns `{ kind: "principal.disabled", before, after }`; a repeated disable preserves the timestamp and returns `fact: null`. Unknown ids fail with `PersonNotFound`. It is transactional, destructive and needs approval. There is no enable. Party permits disabling either kind; protecting an owner is the app's provisioning policy. The composing feature or process chooses which returned facts to record in the same unit. Party never records them itself.
+
+`Party.may()` returns no permissions for a disabled principal. Identity should also check standing before admitting a request. For writes that must not race disable, call `lockActive` in the write's unit. Postgres takes `FOR SHARE`, not `FOR KEY SHARE`, on the principal row until commit or rollback. Disable takes `FOR NO KEY UPDATE` before capturing the change, so it waits for those units; a subsequent lock sees the committed disabled state and fails. Memory's shared `memoryUnitOfWork` serializes whole units and provides the same guarantee. Requests already admitted without `lockActive` may finish after a disable.
+
+Migration `0005` publishes `party_principals_read(id, display_name, kind, handle, created_by, created_at, disabled_at)` and `party_assignments_read(person_id, role_key, organisation_id)`. Read models may select these views for directory ordering and assignment joins. Modules still ask operations, not views, for domain decisions.
+
+## Invitations and membership
+
+`createOrganisation(caller, { id, name })` accepts a person and relates them as staff. The operation gate needs `party:create-organisation`. Bootstrap the creator's scoped admin assignment in the app through an explicit system `assignRole` edge, in the same feature transaction.
+
+`createInvitation(caller, { organisationId, roleKey })` needs an administrator of that organisation. Use `null` to omit a role. The inviter must hold every attached role permission in that scope. Creation returns `{ invitation, code }`. Save the code then: it is never listed again. It has 256 random bits, a seven-day expiry and only its SHA-256 hash is stored.
+
+`acceptInvitation(caller, code)` consumes the code with a conditional write and relates that person as staff. Its result is `{ personId, organisationId, roleKey }`. A feature calls the optional `assignRole` through a system edge. Keep both calls in one transaction, so a failed assignment restores the code and relation. Acceptance rechecks that the inviter can still delegate the current role. Unknown, expired, used and revoked codes all fail with `PartyNotFound`.
+
+`listInvitations(caller, organisationId)` shows only an administered org's invitations, without codes or hashes. `revokeInvitation(caller, id)` checks the invitation's org and needs approval.
+
+`myOrganisations(caller)` returns `{ id, name, relation, roles: [{ roleKey, roleName, permissions }] }[]` for the caller's relationships or scoped assignments. It includes only that person's org-scoped roles, not global roles. An assignment without a relationship has `relation: null`. If several relations exist, `relation` is the first kind in lexical order.
+
+`listPeople(caller)` returns `{ id, displayName, createdAt, assignments, organisations }[]`. Assignments are `{ roleKey, roleName, organisationId, organisationName }`, with null organisation fields for global roles. Organisations are `{ id, name, relation }`. Global admins see everyone and all assignments and relations. Org admins see only staff of their administered orgs and only assignments and relations in those orgs. Global assignments are hidden from org admins, even for a visible person. Other callers get forbidden.
+
+`listMembers(caller, organisationId)` returns `{ id, displayName, createdAt, relation, roles: [{ roleKey, roleName }] }[]` for that org's staff. Roles include only assignments scoped to that org. The operation gate needs `party:read`; Party checks admin authority for the requested org. Members, admins of other orgs and unknown org ids all get `PartyNotFound`.
+
+Both adapters filter storage facts before returning them. Postgres filters people, assignments and relations in SQL; it never fetches another org's assignments for an org-admin list. These reads use the existing tables and need no new migration.
+
+`unrelate` on person-to-organisation staff also revokes that person's assignments scoped to that org. Global roles stay. It refuses removal of the last scoped org admin with `PartyLastAdmin`, kind conflict, and locks the organisation before checking on Postgres.
+
+## Fixed rules
+
+Built-in roles live in options. Custom roles live in `party_role`. Custom keys cannot replace built-in keys. Permissions must be valid `resource:action` strings from the catalogue. A custom role may belong to one organisation or be global. Only global admins may edit global roles. Editing a role's scope checks both its old and new scope. Defining or assigning a role also requires every granted permission in that scope, including built-in roles and updates to assigned custom roles. Global permissions count in an organisation, never the reverse. Permissions in another organisation do not count. `party:admin` alone grants no extra delegation rights.
+
+Assignments refer to a role key, not a role row. This lets them resolve built-in roles too. An organisation admin may manage assignments only in that organisation. Organisation-scoped custom roles cannot be assigned elsewhere. Global admins may manage every organisation. Trusted system callers may assign a default role during first sign-in. Ordinary persons cannot use that exception. System callers cannot revoke roles or manage custom roles. Their trusted assignment path is exempt from the delegation subset check.
+
+`listRoles(caller)` returns global built-ins plus custom roles in the caller's organisations. `rolesOf(caller, personId)` filters assignments to those same scopes and hides global custom roles from scoped callers. Global admins and trusted system reads see all scopes. Both stores filter lists before returning them; Postgres does so in SQL.
+
+May unions permissions from all assignments, across all contexts. It ignores removed roles and stale permissions. It caches nothing, so revocation affects the next call. HTTP and MCP callers with the same Actor get the same permissions. Domain operations still check management scope inside the write unit. Relationship checks are directional facts; they grant no authority on their own.
+
+Any person may read a person's display name. Only that person may rename it. Person creation is system-only at the operation boundary. `party.erase(id)` is trusted service code for account deletion, not an exposed operation.
+
+Every write requires an open unit. Memory registers rollback before mutation. Postgres joins the app's transaction. Party never opens a unit. Tables have no cross-module foreign keys. Errors declare kinds; unavailable messages are fixed and keep diagnostic causes private.
+
+## Tests
+
+Run `pnpm exec tsc --project tsconfig.json --noEmit` and `pnpm exec varlock run --path ../../ -- vitest run` from this package. Shared storage and domain suites run on memory and real Postgres through `MigrationsTesting.database`.

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

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

package/dist/adapters/memory/party.js

@@ -0,0 +1,170 @@
+import { ActorId, UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer } from "effect";
+import { PartyStore } from "../../storage.js";
+export const memoryPartyStore = () => Layer.sync(PartyStore, () => {
+    const organisations = new Map();
+    const relationships = new Map();
+    const roles = new Map();
+    const assignments = new Map();
+    const invitations = new Map();
+    const copy = (value) => structuredClone(value);
+    const key = (value) => JSON.stringify(value);
+    const change = Effect.fn("PartyStore.memory.change")(function* (run) {
+        yield* UnitOfWork.required;
+        const before = [
+            new Map(organisations),
+            new Map(relationships),
+            new Map(roles),
+            new Map(assignments),
+            new Map(invitations),
+        ];
+        yield* UnitOfWork.onRollback(Effect.sync(() => {
+            organisations.clear();
+            for (const [k, v] of before[0])
+                organisations.set(k, v);
+            relationships.clear();
+            for (const [k, v] of before[1])
+                relationships.set(k, v);
+            roles.clear();
+            for (const [k, v] of before[2])
+                roles.set(k, v);
+            assignments.clear();
+            for (const [k, v] of before[3])
+                assignments.set(k, v);
+            invitations.clear();
+            for (const [k, v] of before[4])
+                invitations.set(k, v);
+        }));
+        return run();
+    });
+    const changeAssignment = Effect.fnUntraced(function* (value, assigned) {
+        yield* UnitOfWork.required;
+        let undo;
+        yield* UnitOfWork.onRollback(Effect.sync(() => undo?.()));
+        yield* Effect.sync(() => {
+            // Keep one previous entry, not a growing snapshot for every assignment in the unit.
+            const id = key(value);
+            const before = assignments.get(id);
+            undo = () => {
+                if (before === undefined)
+                    assignments.delete(id);
+                else
+                    assignments.set(id, before);
+            };
+            if (assigned)
+                assignments.set(id, copy(value));
+            else
+                assignments.delete(id);
+        });
+    });
+    return PartyStore.of({
+        organisation: (id) => Effect.sync(() => copy(organisations.get(id))),
+        organisationsFor: (id) => Effect.sync(() => copy([...organisations.values()]
+            .filter((org) => [...relationships.values()].some((r) => r.from.kind === "person" &&
+            r.from.id === id &&
+            r.to.kind === "organisation" &&
+            r.to.id === org.id) ||
+            [...assignments.values()].some((a) => a.personId === id && a.organisationId === org.id))
+            .map((org) => ({
+            ...org,
+            relation: [...relationships.values()]
+                .filter((r) => r.from.kind === "person" &&
+                r.from.id === id &&
+                r.to.kind === "organisation" &&
+                r.to.id === org.id)
+                .map((r) => r.kind)
+                .sort()[0] ?? null,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id)))),
+        relationsFor: (id, scopes) => Effect.sync(() => copy([...relationships.values()]
+            .flatMap((r) => {
+            const org = organisations.get(r.to.id);
+            return r.from.kind === "person" &&
+                r.from.id === id &&
+                r.to.kind === "organisation" &&
+                org &&
+                (scopes === null || scopes.includes(org.id))
+                ? [{ ...org, relation: r.kind }]
+                : [];
+        })
+            .sort((a, b) => a.name.localeCompare(b.name) ||
+            a.id.localeCompare(b.id) ||
+            a.relation.localeCompare(b.relation)))),
+        scopedAssignments: (id, scopes) => Effect.sync(() => copy([...assignments.values()]
+            .filter((a) => a.personId === id &&
+            (scopes === null ||
+                (a.organisationId !== null && scopes.includes(a.organisationId))))
+            .sort((a, b) => a.roleKey.localeCompare(b.roleKey) ||
+            (a.organisationId ?? "").localeCompare(b.organisationId ?? "")))),
+        assignmentsInOrganisation: (id) => Effect.sync(() => copy([...assignments.values()].filter((a) => a.organisationId === id))),
+        holderIds: (role, scope, take) => Effect.sync(() => [
+            ...new Set([...assignments.values()]
+                .filter((a) => a.roleKey === role && a.organisationId === scope)
+                .map((a) => a.personId)),
+        ]
+            .sort()
+            .slice(0, take)),
+        lockOrganisation: () => UnitOfWork.required,
+        memberIds: (ids) => Effect.sync(() => [
+            ...new Set([...relationships.values()]
+                .filter((r) => r.from.kind === "person" &&
+                r.to.kind === "organisation" &&
+                ids.includes(r.to.id) &&
+                r.kind === "staff")
+                .map((r) => ActorId.make(r.from.id))),
+        ]),
+        insertInvitation: (value) => change(() => {
+            invitations.set(value.id, copy(value));
+        }),
+        invitation: (id) => Effect.sync(() => copy(invitations.get(id))),
+        invitations: (id) => Effect.sync(() => copy([...invitations.values()].filter((i) => i.organisationId === id))),
+        consumeInvitation: (hash, now) => change(() => {
+            const found = [...invitations.values()].find((i) => i.codeHash === hash && i.state === "pending" && i.expiresAt > now);
+            if (!found)
+                return undefined;
+            invitations.set(found.id, { ...found, state: "used" });
+            return copy(found);
+        }),
+        revokeInvitation: (id) => change(() => {
+            const found = invitations.get(id);
+            if (found)
+                invitations.set(id, { ...found, state: "revoked" });
+        }),
+        insertOrganisation: (value) => change(() => {
+            if (organisations.has(value.id))
+                return false;
+            organisations.set(value.id, copy(value));
+            return true;
+        }),
+        relate: (value) => change(() => {
+            relationships.set(key(value), copy(value));
+        }),
+        unrelate: (value) => change(() => {
+            relationships.delete(key(value));
+        }),
+        isRelated: (value) => Effect.sync(() => relationships.has(key(value))),
+        role: (id) => Effect.sync(() => copy(roles.get(id))),
+        roles: (organisationIds) => Effect.sync(() => copy([...roles.values()]
+            .filter((r) => organisationIds == null ||
+            (r.organisationId !== null && organisationIds.includes(r.organisationId)))
+            .sort((a, b) => a.key.localeCompare(b.key)))),
+        putRole: (value) => change(() => {
+            roles.set(value.key, copy(value));
+        }),
+        deleteRole: (id) => change(() => {
+            roles.delete(id);
+            for (const [k, v] of assignments)
+                if (v.roleKey === id)
+                    assignments.delete(k);
+        }),
+        assign: (value) => changeAssignment(value, true),
+        revoke: (value) => changeAssignment(value, false),
+        assignments: (id, organisationIds, builtInKeys = []) => Effect.sync(() => copy([...assignments.values()].filter((a) => a.personId === id &&
+            (organisationIds == null ||
+                (a.organisationId === null
+                    ? builtInKeys.includes(a.roleKey)
+                    : organisationIds.includes(a.organisationId) &&
+                        (builtInKeys.includes(a.roleKey) ||
+                            roles.get(a.roleKey)?.organisationId === a.organisationId)))))),
+    });
+});

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

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

package/dist/adapters/memory/person.js

@@ -0,0 +1,87 @@
+import { UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer } from "effect";
+import { legacyPrincipal, personOf } from "../../person/principal.js";
+import { PersonStore } from "../../storage.js";
+export const memoryPersonStore = () => Layer.sync(PersonStore, () => {
+    const rows = new Map();
+    const handles = new Map();
+    const set = (id, principal) => {
+        const before = rows.get(id);
+        if (before)
+            handles.delete(before.handle);
+        if (principal) {
+            rows.set(id, principal);
+            handles.set(principal.handle, id);
+        }
+        else {
+            rows.delete(id);
+        }
+    };
+    const change = Effect.fnUntraced(function* (id, run) {
+        yield* UnitOfWork.required;
+        let undo;
+        yield* UnitOfWork.onRollback(Effect.sync(() => undo?.()));
+        return yield* Effect.sync(() => {
+            // Capture and mutate together, after registering undo, even with parallel writes in a unit.
+            const before = rows.get(id);
+            undo = () => set(id, before);
+            return run();
+        });
+    });
+    const insertPrincipal = (principal) => change(principal.id, () => {
+        if (rows.has(principal.id) || handles.has(principal.handle))
+            return false;
+        set(principal.id, { ...principal });
+        return true;
+    });
+    return PersonStore.of({
+        principal: (id) => Effect.sync(() => {
+            const row = rows.get(id);
+            return row && { ...row };
+        }),
+        principalByHandle: (handle) => Effect.sync(() => {
+            const id = handles.get(handle);
+            const row = id === undefined ? undefined : rows.get(id);
+            return row && { ...row };
+        }),
+        principalsByIds: (ids) => Effect.sync(() => [...rows.values()].filter((p) => ids.includes(p.id)).map((p) => ({ ...p }))),
+        insertPrincipal,
+        // memoryUnitOfWork serializes whole units, so the lock lasts until commit or rollback.
+        lockPrincipal: (handle) => Effect.gen(function* () {
+            yield* UnitOfWork.required;
+            const id = handles.get(handle);
+            const row = id === undefined ? undefined : rows.get(id);
+            return row && { ...row };
+        }),
+        principalForUpdate: (id) => Effect.gen(function* () {
+            yield* UnitOfWork.required;
+            const row = rows.get(id);
+            return row && { ...row };
+        }),
+        disable: (id, disabledAt) => Effect.gen(function* () {
+            yield* UnitOfWork.required;
+            const row = rows.get(id);
+            if (!row)
+                return undefined;
+            const disabled = { ...row, disabledAt: row.disabledAt ?? disabledAt };
+            yield* change(id, () => set(id, disabled));
+            return { ...disabled };
+        }),
+        find: (id) => Effect.sync(() => {
+            const row = rows.get(id);
+            return row && personOf(row);
+        }),
+        list: (ids) => Effect.sync(() => [...rows.values()].filter((p) => ids === null || ids.includes(p.id)).map(personOf)),
+        insertIfFree: (person) => insertPrincipal(legacyPrincipal(person)),
+        rename: (id, displayName) => Effect.gen(function* () {
+            yield* UnitOfWork.required;
+            const person = rows.get(id);
+            if (person === undefined)
+                return undefined;
+            const renamed = { ...person, displayName };
+            yield* change(id, () => set(id, renamed));
+            return personOf(renamed);
+        }),
+        erase: (id) => change(id, () => set(id, undefined)),
+    });
+});

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

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

package/dist/adapters/postgres/party.js

@@ -0,0 +1,73 @@
+import { ActorId, UnitOfWork } from "@house-rules/domain";
+import { Effect, Layer, Schema } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+import { StoredInvitation } from "../../invitation/invitation.js";
+import { Assignment } from "../../assignment/assignment.js";
+import { Organisation, OrganisationRelation, OwnOrganisation, PartyUnavailable, } from "../../organisation/organisation.js";
+import { Role } from "../../role/role.js";
+import { PartyStore } from "../../storage.js";
+export const postgresPartyStore = Layer.effect(PartyStore, Effect.gen(function* () {
+    const sql = yield* SqlClient;
+    const unavailable = (cause) => new PartyUnavailable({ cause });
+    const read = (schema, query) => query.pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.Array(schema))), Effect.mapError(unavailable));
+    const write = (query) => UnitOfWork.required.pipe(Effect.andThen(query.pipe(Effect.mapError(unavailable))), Effect.asVoid);
+    const roleColumns = sql.literal('key, name, permissions, organisation_id as "organisationId", false as "builtIn"');
+    const invitationColumns = sql.literal('id, organisation_id as "organisationId", role_key as "roleKey", created_by as "createdBy", code_hash as "codeHash", expires_at as "expiresAt", state');
+    const relation = (r) => sql `from_kind = ${r.from.kind} and from_id = ${r.from.id}
+    and to_kind = ${r.to.kind} and to_id = ${r.to.id} and kind = ${r.kind}`;
+    return PartyStore.of({
+        organisation: (id) => read(Organisation, sql `select id, name from party_organisation where id = ${id}`).pipe(Effect.map((rows) => rows[0])),
+        organisationsFor: (id) => read(OwnOrganisation, sql `select id, name, (select min(r.kind) from party_relationship r where r.from_kind = 'person' and r.from_id = ${id} and r.to_kind = 'organisation' and r.to_id = o.id) as relation from party_organisation o where exists (select 1 from party_relationship r where r.from_kind = 'person' and r.from_id = ${id} and r.to_kind = 'organisation' and r.to_id = o.id) or exists (select 1 from party_assignment a where a.person_id = ${id} and a.organisation_id = o.id) order by name, id`),
+        relationsFor: (id, scopes) => read(OrganisationRelation, sql `select o.id, o.name, r.kind as relation from party_relationship r join party_organisation o on o.id = r.to_id where r.from_kind = 'person' and r.from_id = ${id} and r.to_kind = 'organisation' and ${scopes === null ? sql `true` : sql.in("o.id", scopes)} order by o.name, o.id, r.kind`),
+        scopedAssignments: (id, scopes) => read(Assignment, sql `select person_id as "personId", role_key as "roleKey", organisation_id as "organisationId" from party_assignment where person_id = ${id} and ${scopes === null ? sql `true` : sql.in("organisation_id", scopes)} order by role_key, organisation_id nulls first`),
+        assignmentsInOrganisation: (id) => read(Assignment, sql `select person_id as "personId", role_key as "roleKey", organisation_id as "organisationId" from party_assignment where organisation_id = ${id}`),
+        holderIds: (role, scope, take) => read(Schema.Struct({ id: ActorId }), sql `select distinct person_id collate "C" as id from party_assignment
+            where role_key = ${role} and organisation_id is not distinct from ${scope}
+            order by id limit ${take}`).pipe(Effect.map((rows) => rows.map((r) => r.id))),
+        lockOrganisation: (id) => write(sql `select id from party_organisation where id = ${id} for update`),
+        memberIds: (ids) => read(Schema.Struct({ id: ActorId }), sql `select distinct from_id as id from party_relationship where from_kind = 'person' and to_kind = 'organisation' and kind = 'staff' and ${sql.in("to_id", ids)}`).pipe(Effect.map((rows) => rows.map((r) => r.id))),
+        insertInvitation: (i) => write(sql `insert into party_invitation (id, organisation_id, role_key, created_by, code_hash, expires_at, state) values (${i.id}, ${i.organisationId}, ${i.roleKey}, ${i.createdBy}, ${i.codeHash}, ${i.expiresAt}, ${i.state})`),
+        invitation: (id) => read(StoredInvitation, sql `select ${invitationColumns} from party_invitation where id = ${id}`).pipe(Effect.map((rows) => rows[0])),
+        invitations: (id) => read(StoredInvitation, sql `select ${invitationColumns} from party_invitation where organisation_id = ${id} order by id`),
+        consumeInvitation: Effect.fn("PartyStore.postgres.consumeInvitation")(function* (hash, now) {
+            yield* UnitOfWork.required;
+            const rows = yield* read(StoredInvitation, sql `update party_invitation set state = 'used' where code_hash = ${hash} and state = 'pending' and expires_at > ${now} returning ${invitationColumns}`);
+            return rows[0];
+        }),
+        revokeInvitation: (id) => write(sql `update party_invitation set state = 'revoked' where id = ${id}`),
+        insertOrganisation: Effect.fn("PartyStore.postgres.insertOrganisation")(function* (value) {
+            yield* UnitOfWork.required;
+            const rows = yield* sql `insert into party_organisation (id, name) values (${value.id}, ${value.name})
+        on conflict do nothing returning id`.pipe(Effect.mapError(unavailable));
+            return rows.length > 0;
+        }),
+        relate: (r) => write(sql `insert into party_relationship (from_kind, from_id, to_kind, to_id, kind)
+      values (${r.from.kind}, ${r.from.id}, ${r.to.kind}, ${r.to.id}, ${r.kind}) on conflict do nothing`),
+        unrelate: (r) => write(sql `delete from party_relationship where ${relation(r)}`),
+        isRelated: (r) => sql `select 1 from party_relationship where ${relation(r)}`.pipe(Effect.map((rows) => rows.length > 0), Effect.mapError(unavailable)),
+        role: (key) => read(Role, sql `select ${roleColumns} from party_role where key = ${key}`).pipe(Effect.map((rows) => rows[0])),
+        roles: (organisationIds) => read(Role, sql `select ${roleColumns} from party_role
+        where ${organisationIds == null ? sql `true` : sql.in("organisation_id", organisationIds)} order by key`),
+        putRole: (r) => write(sql `insert into party_role (key, name, permissions, organisation_id)
+      values (${r.key}, ${r.name}, array(select jsonb_array_elements_text(${JSON.stringify(r.permissions)}::jsonb)), ${r.organisationId})
+      on conflict (key) do update set name = excluded.name, permissions = excluded.permissions, organisation_id = excluded.organisation_id`),
+        deleteRole: Effect.fn("PartyStore.postgres.deleteRole")(function* (key) {
+            yield* write(sql `delete from party_assignment where role_key = ${key}`);
+            yield* write(sql `delete from party_role where key = ${key}`);
+        }),
+        assign: (a) => write(sql `insert into party_assignment (person_id, role_key, organisation_id)
+      values (${a.personId}, ${a.roleKey}, ${a.organisationId}) on conflict do nothing`),
+        revoke: (a) => write(sql `delete from party_assignment where person_id = ${a.personId}
+      and role_key = ${a.roleKey} and organisation_id is not distinct from ${a.organisationId}::text`),
+        assignments: (id, organisationIds, builtInKeys = []) => read(Assignment, sql `select person_id as "personId", role_key as "roleKey",
+      organisation_id as "organisationId" from party_assignment where person_id = ${id}
+      and ${organisationIds == null
+            ? sql `true`
+            : sql `((${sql.in("organisation_id", organisationIds)}
+          and (${sql.in("role_key", builtInKeys)} or exists
+            (select 1 from party_role r where r.key = party_assignment.role_key
+              and r.organisation_id = party_assignment.organisation_id)))
+        or (organisation_id is null and ${sql.in("role_key", builtInKeys)}))`}
+      order by role_key, organisation_id nulls first`),
+    });
+}));

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

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