@wtfalch/authz-store 0.2.1 → 0.4.0

package/README.md

@@ -9,15 +9,366 @@ credentials, break-glass, the boot checks — and arrived at the same one. Of th
 lagging the other or a stale comment. This package is where that code goes so it
 exists once.
 
-`/Users/william.falch/Documents/dev/authz/docs/shared-persistence-map.md` is the
+[docs/shared-persistence-map.md](../../docs/shared-persistence-map.md) is the
 map: what moves here, what stays per-application, and why this is a second
 package rather than a subpath on the engine.
 
 ## Status
 
-**Unadopted, unpublished, private.** Moved so far: credential secrets, the
-`ScopedDb` seam, every table definition, and `ownerCoverage`, the first module
-that reads rows. Neither application depends on this yet.
+**Published.** `@wtfalch/authz-store` is on npm at 0.2.1. "Depend" here means a
+pin in that host's `package.json`, not a verified deployment: Boule (`manage`)
+pins 0.2.1, `people` pins 0.2.1, and otf's `web/` pins 0.2.0. archon still carries its own copy of
+this layer, unmoved.
+
+Moved so far: credential secrets, the `ScopedDb` seam, every table definition,
+`ownerCoverage`, wave 1 (authz#83): `StoreBinding` (the `applicationId`,
+`platformId` and `catalogue` a host now passes in explicitly rather than the
+store importing its own), `isCustomRoleKey`, the shared `types` (`Principal`,
+`TenantRow`, `Access`, `Result`), `policyResource`, `loadAccess` and the rest
+of `policy-access` (`loadPolicyState`, `requirePolicySchema`, `permits`,
+`permitsPlatform`, `policyTarget`, `refreshAccess`, `policyRole`,
+`policyAssignment`, `restriction`), and `denial`'s `explain`; and wave 2:
+`auditedReadGate`, `permitsRead` and `permitsPlatformRead` (now in
+`policy-access.ts`, reaching `audit.ts`'s `record()` through a dynamic import
+to avoid a static import cycle), `assignments` (`identityWhere`,
+`primaryRoleKey`, `primaryAssignment`, `roleAssignmentRefusal`,
+`writePrimaryAssignment`, `roleById`, `writeParticipationPolicy`), and `audit`
+(`record`, `recordAs`, `writeServiceEvent`, `securityLogFor`) — the write path
+is Boule's own: validated rows straight into `authz_events`, not
+`@wtfalch/audit`'s `ledger.sign()` (decided 2026-09-29, authz#94); and wave 3:
+`policy.ts`'s `definePolicy`, which builds a `StorePolicy` (a `StoreBinding`
+plus `catalogue`, `builtInRoles`, `starterRoles`, `elevated`,
+`requiresCoApproval`, `defaultCeiling`, `maxDepth`, `offered`) from a host's
+own policy-catalogue JSON — generic over that JSON's shape (`PolicyData`),
+since only the function that builds a catalogue from it was identical between
+hosts; `roles` (`roleDef`, `assignableRoles`, `rolesForEditor`,
+`canEditDefinition`, `createRole`, `updateRole`, `deleteRole`); and `boot`
+(`ensureBuiltInRoles`, `seedStarterRoles`, `checkSystemRoles`,
+`orphanedRoleKeys`, `content`) — ADR 0016 kept exactly: `builtInRoles` names
+only `self_service`, resynced on every boot; every other `systemRoles` entry
+is a starter role, seeded once by `seedStarterRoles`. Not moved:
+`DENIAL_EVENTS`, keyed to one host's own permission ids and staying in the
+hosts for that reason.
+
+Wave 4a (authz#83) moves the tenant tree's read and query half, from
+`tree.ts`: `nodeById`, `lockTenantsForUpdate`, `lockSubtreeForUpdate`,
+`lockAttachScope`, `ancestorsOf`, `childrenOf`, `descendantsOf`,
+`depthAbove`, `heightBelow`, `attachProblem` (now takes `policy: StorePolicy`
+for `maxDepth`/`offered`, in place of the host's own imported constants),
+`expectedDerivedFor`, `customRoleBlockers`, `attachCustomRoleBlockers`,
+`derivedEventAction`, `principalsAtOrAbove` and `detachReport`.
+
+Wave 4b (authz#83) moves the write and inheritance-propagation half, from
+`tree-writes.ts`: `recomputeDerived` (the one writer that makes a tenant's
+derived rows match the derivation rule), and the two callers that change the
+tree's shape, `attachInTx` and `detachInTx`. `DerivedCustomRoleError` is
+thrown, never returned, when a caller reaches `recomputeDerived` without
+having checked `customRoleBlockers` first (D19: a derived membership never
+carries a custom role).
+
+Wave 5a (authz#83) moves `propagate.ts`, `reconcile.ts` and
+`install-owner.ts`:
+
+- `propagate.ts`: `propagateMembershipChange`, the one place every direct
+  membership write (`memberships.ts`, `invitations.ts`, `install-owner.ts`,
+  `credentials.ts`, all still host-side except the second) recomputes the
+  derived rows it can have moved and writes one audit row per change.
+  `writerFromAccess`/`writerFromPrincipal` build the `PropagationWriter` it
+  signs the rows with, for a write that already has an `Access` and one
+  (invitation acceptance) that does not yet.
+- `reconcile.ts`: `reconcileDerived`, D19's drift check — every `inherited`
+  membership row compared, read-only, against what `expectedDerivedFor`
+  (`tree.ts`) says the tree calls for.
+- `install-owner.ts`: `installOwner`, the one exception to D8's rule that no
+  session or standing operator reach ever changes tenant membership. Boule's
+  copy read the host's own `profiles` table directly for two things — whether
+  the target person has ever signed in, and the tenant's current owners'
+  `lastSeenAt` — and that table is the host's, not the store's, so both
+  become an `OwnerActivityLookup` the host passes in: `personKnown(id)` and
+  `lastSeenAt(ids)`, batched over a tenant's direct owners rather than one
+  join. Every host adopting this wave implements that interface over its own
+  `profiles` (or equivalent) table.
+
+Every function in this wave that used to read `db` from a host's own
+`@/lib/db/root` now takes it as an explicit `db: DbOrTx` parameter, the same
+as `securityLogFor` and `createRole`/`updateRole`/`deleteRole` in earlier
+waves.
+
+Wave 5b (authz#83) moves `break-glass.ts`: `startBreakGlass`, `endBreakGlass`,
+`endSessionsFor`, `activeSession`, `sessionsFor` — the one place a support
+session opens, ends or force-ends. The break-glass support role is found by
+`isCustomRoleKey`, not `.builtIn` (ADR 0016: a starter role is `built_in:
+false` but still an application-defined role, never a tenant-authored one).
+`db` is again an explicit parameter rather than a host import, the same as
+wave 5a.
+
+Wave 6 (authz#83) moves `nesting.ts`, the consent flow over the tree:
+`proposeAttach`, `acceptAttach`, `declineAttach`, `detach`, and the three
+pending-proposal readers (`pendingProposalsForChild`,
+`pendingProposalsForParent`, `proposalsFromParent`). `proposeAttach` and
+`acceptAttach` take `policy: Pick<StorePolicy, 'maxDepth' | 'offered'>`
+explicitly, since `attachProblem` (wave 4a) needs it and the store has no
+`StorePolicy` of its own in scope. Unique-violation detection on the
+proposal's partial index (authz#96) uses `@wtfalch/db`'s `sqlState()`, the
+same helper otf already used, in place of the `(error as {code?}).code ===
+'23505'` duck-typing Boule's and archon's copies both wrote — declared as a
+peer dependency, matching `drizzle-orm`'s role (a host-supplied instance),
+pinned exact at `0.4.0` (the estate's `@wtfalch/*` pin rule), plus a matching
+exact `devDependency` for this package's own build and test.
+
+Wave 7 (authz#83, authz#95 decision 2, authz#98) moves `credentials.ts`
+(`mintCredential`, `revokeCredential`, `credentialsFor`) and `bootstrap.ts`
+(`bootstrapOperator`).
+
+Minting and revoking cut over from this package's own `credential-secret.ts`
+scheme to a host's `@wtfalch/keys` issuer: `mintCredential` and
+`revokeCredential` now take an `issuer` parameter, typed by the store's own
+`CredentialIssuerPort` (`issue`/`revoke`, in exactly the shapes the two
+functions call them), with no default. `@wtfalch/keys` is a `devDependency`
+only, pinned exact at `0.4.2`; a type test in `credentials.test.ts` proves
+`CredentialIssuer<StoreKeyGrant>` from `@wtfalch/keys/issued` satisfies the
+port, and nothing outside a test imports `@wtfalch/keys` from this package.
+`credential-secret.ts` is unchanged and stays: it verifies every row minted
+before a host adopts this wave, and a host's own bearer path keeps checking
+against it for those rows. Migration `0004_credential_keys_issued_id.sql`
+loosens `credentials.secret_hash` to nullable, adds `keys_issued_id`, and
+widens `credentials_secret_prefix_check` to 64 characters, matching
+`@wtfalch/keys`'s own bound. `credentialsFor` no longer joins a host's own
+`profiles` table; it takes an `IssuerNames` port instead
+(`personNames(ids)`, batched over every human issuer on the page), a host's
+display name falling back to email the same way the join order did.
+
+`bootstrapOperator` no longer reads `AUTHZ_BOOTSTRAP_OPERATOR` or imports
+`@wtfalch/auth`: a host resolves its own bootstrap subject and passes it as
+`options.subject`, along with `options.ensureProfile`, generic over the
+host's own `User` type. Boule's order is unchanged (`ensureProfile` first,
+then the tenant row lock, the owner count read only after the lock) and so
+is its `seedStarterRoles` call, which otf's copy of this function had
+dropped — a bug this move does not repeat.
+
+Wave 8a (authz#83, issue #98 decision 3) moves the sending and management
+half of `invitations.ts`: `generateInvitationToken`, `invite`,
+`markInvitationMail`, `resendInvitation`, `revokeInvitation`,
+`pendingInvitations`, `invitationPreview` and `invitationTenantId`.
+`INVITATION_CAP_PER_HOUR` is no longer a package constant; `invite` and
+`resendInvitation` take `capPerHour` as an option. The store never
+hard-codes an acceptance route either: `invite` takes a `link: (token:
+string) => string` builder, and Boule's own `invitationLink` (`/org/invite/
+${token}`) stays in the host, unmoved, as its caller. `acceptInvitation`
+is wave 8b, not this wave: it needs `acceptInvitationForUser`'s host-only
+`requireUser`/`ensureProfile`/`principalFromUser`, which stay in Boule as a
+non-goal (see wave 8b below for the boundary).
+
+Wave 8b (authz#83, issue #98 decisions 3–5) moves `acceptInvitation`,
+`AcceptInvitationResult`, `AttachRefusal` and the born-attach savepoint
+(`attemptBornAttach`, `AttachAttemptRefused`), staying in `invitations.ts`
+alongside wave 8a. `acceptInvitationForUser` does **not** move: it is the
+one caller of Boule's own `requireUser`, `ensureProfile` and
+`principalFromUser` from `access.ts`, none of which this package can reach,
+so it stays in Boule as this wave's one host-only function. `acceptInvitation`
+takes `binding`, `policy: Pick<StorePolicy, 'maxDepth' | 'offered'>` (for the
+born-attach path's `attachProblem`) and `profiles: Pick<OwnerActivityLookup,
+'personKnown'>` (install-owner.ts's own port, reused rather than a second one
+for the same "has this id ever signed in" question) as explicit parameters.
+`@wtfalch/people` is not imported: it depends on this package, so importing
+it back would be a cycle; the membership-row half of its `grantMembership` is
+inlined directly in `acceptInvitation` instead, with the role assignment and
+participation-policy writes staying this file's own, exactly as Boule's
+comment already described the split.
+
+Wave 9a (authz#83, issue #99 decision 4) moves the member-side writes and
+reads from `tenants.ts`: `createTenant`, `renameTenant`, `setSelfDenied`,
+`setTenantState`, `setCeiling`, `tenantById`, `tenantBySlug`, `allTenants`.
+`TENANT_CREATION` and `TENANT_CREATION_CAP_PER_DAY` are no longer package
+constants: a host passes both through `CreateTenantConfig` (decision 3), the
+same option shape as every other wave's config parameter. `defaultCeiling`
+and `offered` come off the `policy: StorePolicy` (or the narrower
+`Pick<StorePolicy, 'defaultCeiling' | 'offered'>` where that is all a
+function needs) a caller passes in, rather than an import (decision 4). The
+person check `createTenant` needs before it lets someone self-serve a
+tenant reuses `OwnerActivityLookup.personKnown` (wave 5a's own port), the
+same "has this id ever signed in" question, rather than a second port for
+it. A slug race is read the same way wave 6's proposal collision is: a real
+unique-violation, via `@wtfalch/db`'s `sqlState()`, not
+`(error as {code?}).code` duck-typing.
+
+Wave 9b (authz#83, issue #99 decision 4) moves the operator side from the
+same file: `createTenantAsOperator`, `deleteJustCreatedTenant`,
+`archiveTenant`. `createTenantAsOperator` takes a `link: (token: string) =>
+string` builder for its pending owner invitation, the same shape wave 8a's
+`invite` takes, so the store never hard-codes an acceptance route.
+`deleteJustCreatedTenant` moves as archon's compensating rollback for its
+own second, non-transactional write (issue #40) — a plain exported
+function only archon calls, operator-only by its own guards, with no hook
+or extension interface, since nothing else needs one. `openBearerScope`
+does **not** move: it only wraps the host's own db and tenant tables with
+the store's `openScopedDb`/`scopeColumnOf`, so it has nothing this package
+doesn't already export, and stays in archon.
+
+Wave 10a (authz#83) moves the grants compiler from Boule's own
+`src/lib/authz/grants.ts` (496 lines): `personRecordFor`, the person page's
+read of every grant a human principal holds in one organisation, with its
+provenance and the teams they participate in, and `teamRecordFor`, the team
+page's own read of one team, its place in the hierarchy, who is in it, and
+its scoped access. Both land in a new `src/person-records.ts`, not this
+package's existing `src/grants.ts` — that file is the `authz_grants` table
+and `guestGrants`, a different thing, and stays untouched. Boule's one
+`z.uuid()` check becomes the store's own `isUuid` from `types.ts`; the store
+gained no zod dependency. `APPLICATION_ID`, `PLATFORM_ID` and `catalogue`
+become `access.binding`, the same as every other moved module. `profiles`
+becomes a `PeopleDirectory` port, reused for both the grant-provenance name
+lookup (`resolveActorNames`) and `personRecordFor`'s own display fields —
+Boule's inner join against `profiles`, which excluded a member with no
+profile row from the result, becomes the directory's map coming up empty for
+that id, read the same way.
+
+Wave 10b (authz#83, William 2026-09-29) moves Boule's own
+`src/lib/authz/memberships.ts` (407 lines) into a new `src/memberships.ts`:
+`membersOf`, `selfStanding`, `guardStaysHeld`, `grantMembership`,
+`changeRole` and `removeMembership`, keeping Boule's own names. The
+row-level work four of those six delegated to `@wtfalch/people` 0.2.3 —
+`grantMembership`, `removeMembership`, `changeRole` and `guardStaysHeld`
+from its `membership.js`, and `membersOf` from its `roster.js` — is copied
+into a new `src/membership-rows.ts` instead of imported, because
+`@wtfalch/people` depends on this package and importing it back would be a
+cycle; a later issue in the people repo makes it reuse this copy rather than
+carry its own. Every row helper is exported under a name distinct from its
+policy-layer counterpart (`insertMembershipRow`, `deleteMembershipRow`,
+`changeRoleRow`, `guardStaysHeldRow`, `membersOfRow`), since the two layers
+would otherwise claim the same five names on one package surface. As of
+0.4.0 (https://github.com/wtfalch/people/issues/16) all five are exported
+from the main entry, so `@wtfalch/people` can call this copy instead of
+carrying its own — see the 0.4.0 note below. `identityWhere` is not duplicated: people's
+own copy tests the same three columns as `src/assignments.ts`'s, in a
+different argument order `and()` doesn't care about, so `membership-rows.ts`
+imports that one. `roster.js`'s `profiles` left join (a member with no
+profile row is kept, with null display fields) becomes the same
+`PeopleDirectory` port wave 10a introduced, read the same left-join way —
+a human principal missing from the directory keeps its row, a non-human one
+never reaches the directory at all, same as the original join's predicate.
+
+Wave 11a (authz#83) moves Boule's own `src/lib/authz/resource-access.ts`
+(814 lines) into a new `src/resource-access.ts`: `resourceOverview`,
+`saveAppRole`, `assignAppRole`, `removeAppAssignment`, `deleteAppRole`,
+`saveTeam`, `archiveTeam`, `changeTeamParticipant`, `scopedAuditLog`, and
+the shared `resourceAccessFor` request-time evaluator every one of them
+reads through. Boule's copy was the newest of the two hosts' — it alone
+has `resourceOverview`'s `canReadPeople` field, which archon and otf never
+grew — and is the one kept. `resourceAccessFor` itself reloads access on
+every call, a deliberate re-read Boule's own code already made, not a
+redundancy introduced here; it now takes the same `tx`/`db`/`scopeColumn`
+triple `loadAccess` does, since the store has no root handle of its own to
+default it onto the way Boule's `db` import did. Every exported function
+gained `db: DbOrTx` and `scopeColumn: Scope['column']` parameters for the
+same reason, the same convention every earlier wave followed.
+
+`appRolePermissionsSchema` was a module-level zod schema closed over
+Boule's own `catalogue` constant; it is now a function of
+`ResourceCatalogue` (`access.binding.catalogue`), as is the private
+`roleInputSchema` built from it — every validation rule inside both is
+unchanged. This is the store's first zod dependency: `zod` is now a peer
+and dev dependency of `@wtfalch/authz-store`, `^4.1.13`/`^4.5.4`, the same
+pins `@wtfalch/authz` itself carries. Boule's `import { db } from
+'@/lib/db/root'` and `import 'server-only'` are gone, the same as every
+earlier wave; its `asc`, `memberships` (table), `tenants` (table),
+`TenantRow` and `policyAssignment` imports — five names in all — were
+already unused in the original file and were not carried over.
+
+At 814 lines of source, this module is over the 800-line PR-size limit
+with its tests added, but it stays one PR: its functions share private
+helpers (`writer`, `resourceAccessFor`, `lookupResource`, `delegable`,
+`auditClause`, `target`) too tightly to split without duplicating them or
+introducing a cross-file dependency this wave's split would then have to
+undo.
+
+Wave 11b (authz#83) moves Boule's own `src/lib/authz/activations.ts` (694
+lines, ADR 0016 "No standing authority") into a new `src/activations.ts`:
+`needsCoApproval`, `requestActivation`, `approveActivation`,
+`selfApproveActivation` and `endActivation`. `elevated` and
+`requiresCoApproval` — ADR 0016 sets, not part of `StoreBinding` — come off a
+`policy: Pick<StorePolicy, ...>` parameter each function needs, the same
+shape wave 6's `proposeAttach`/`acceptAttach` and wave 9a's tenant writes
+take theirs; unlike Boule's own module-level constants, `StorePolicy.elevated`
+and `.requiresCoApproval` are already `ReadonlySet<string>`, so no widening
+cast is needed. The tenant-only `select ... for update` Boule's three
+write functions each repeated right after `refreshAccess` is dropped: the
+store's own `refreshAccess` already takes that lock inside itself. The two
+new tables (`authz_activations`, `authz_activation_approvals`) land in
+`migrations/0005_activations.sql`; `authz_roles.updated_by` and the
+`'activation'` `authz_assignments.source` value, and all six `activation.*`
+names in `authz_events_action_check`, were already in `0001_baseline.sql`
+before this wave. No FK from `principal_id`/`approver_id` to a host's own
+person table, the same as `break_glass_sessions.operator_id`. No audit event
+is written anywhere in this file, kept exactly as Boule had it, even though
+this package's own `authz_events_action_check` and pinned `@wtfalch/authz`
+already accept every name Boule's own comment said its installed version
+did not yet — turning the writes on is a behaviour change this move does
+not make on its own judgement.
+
+Wave 11c (authz#83) moves three of Boule's own modules into new files here,
+keeping every guard and comment: `src/lib/authz/export.ts` (464 lines) into
+`src/export.ts` (`exportTenant`), `src/lib/authz/events.ts` (189 lines) into
+`src/events.ts` (`eventsFor`), and `src/lib/authz/platform.ts` (71 lines)
+into `src/platform.ts` (`platformFrozen`, `setPlatformFrozen`). All three
+copies of `export.ts` (archon, Boule, otf) differed only cosmetically; Boule's
+was the source for all three. `exportTenant` takes this package's own
+`DbOrTx` instead of Boule's root `Db`; its own hand-built `tenant.exported`
+row (never through `record`/`recordAs`, since its caller has no full `Access`
+to build one from) is unchanged. `eventsFor` takes `db: DbOrTx` explicitly,
+with `APPLICATION_ID`/`PLATFORM_ID` now `access.binding`'s and its
+`auditedReadGate` call now this package's own (`policy-access.ts`, which
+takes `(access, db, permission, allowed)`). `platformFrozen` and
+`setPlatformFrozen` both take `db: DbOrTx`; `setPlatformFrozen` also takes
+`scopeColumn: Scope['column']` for the `refreshAccess` call inside its
+transaction, the same shape `tenants.ts` uses. otf's throw-based, host-bound
+`setPlatformFrozen` (it wraps a session-bound `requireOperator`) stays in
+otf, not moved.
+
+Wave 11d (authz#83) moves Boule's own `src/lib/authz/erase.ts`, `alerts.ts`
+and `startup.ts` into `src/erase.ts`, `src/alerts.ts` and `src/startup.ts`.
+`erase.ts` moves `pseudonymFor` and `erasePerson`, the one sanctioned write
+to `authz_events`; the SQL function it calls (`authz_erase_person`, `SECURITY
+DEFINER`, a pinned `search_path`) ships as `migrations/0006_erase_person.sql`,
+sweeping `authz_events` and `invitations` the way Boule's
+`drizzle/0008_erasure_and_boot.sql` did. Boule's own function also scrubbed
+`profiles` and called a reporting package's `reporting_erase_person`; both
+are host tables/packages, so they become one `ErasureHost` port
+(`emailOf`, `eraseHostRecords`) `erasePerson` calls inside its transaction,
+after the sweep and before the `person.erased` row, the same order rule
+Boule's own comment states. `otf`'s own `eraseOperatorPerson`, which sweeps
+otf's own tables, stays in otf and calls the store's `erasePerson`. `alerts.ts`
+moves the four D9 checks (`checkOrphanMemberships`, `checkStuckInvitations`,
+`checkBreakGlassBurst`, `checkOrphanedRoleKeys`), `reportAlert` and
+`runAlerts`; Boule's `@/lib/reporting/core` `reporting` becomes a structural
+`AuthzReporting` port. `startup.ts` moves `runStartupChecks` and
+`registerHousekeeping`; Boule's own version returned early with no
+`DATABASE_URL` to check, which this version drops — a host with no database
+to check simply does not call it, rather than this framework-neutral package
+reading `process.env` to decide the same thing for itself — and its
+`housekeeping` becomes a second structural port, `HousekeepingRegistry`.
+
+0.4.0 (authz#83 round 2, files#112): `loadAccess`'s credential-chain walk in
+`src/policy-access.ts` now selects only `issuerId`, `issuerClass`, `expiresAt`
+and `revokedAt` off `credentials`, instead of every column. files and ai
+dropped `secret_hash`, `secret_prefix` and `keys_issued_id` on purpose, and a
+plain `select()` there named them anyway, failing every service-credential
+request with "column does not exist". `export.ts`, `person-records.ts` and
+`credentials.ts` already select explicit column lists and were left as they
+are: each genuinely needs the secret/keys column it names (an export row's
+`secretPrefix`, a revoke's `keysIssuedId`, `credentialsFor`'s display
+`secretPrefix`), so narrowing further would break them, not fix them.
+
+0.4.0 also renames the SQL function `migrations/0006_erase_person.sql`
+creates, from `erase_person` to `authz_erase_person`. The old name collided
+with each host's own erasure function of the same name and signature, which
+also scrubs a host's `profiles`; `migrateStore`'s `CREATE OR REPLACE FUNCTION`
+replaced a host's function outright, silently dropping that scrub. 0.3.0
+published an hour before this fix and no persistent database had applied
+0006 yet, so this is a same-file rename, not a new numbered migration.
+`src/erase.ts` calls `authz_erase_person`.
+
+The rest of the host layer has not moved — tracked in
+https://github.com/wtfalch/authz/issues/83.
 
 New here, not moved: `authz_grants`, grants stored per person rather than
 compiled from a role, and `guestGrants`, which reads a tenant's guest grants
@@ -31,6 +382,43 @@ the tables from the drizzle definitions. `src/migrate.test.ts` applies the
 shipped SQL instead and fails when the two disagree on a column, a type,
 nullability or an index name.
 
+## 0.4.0
+
+`StoreBinding` (`src/binding.ts`) gains `hostEvents?: readonly string[]`: a host's own audit
+event names (archon: `flag.changed`, `cms.published`, `key.rotated`; files/ai/integrations:
+`mail.*`, `storage.*`, `integrations.*`), beyond `@wtfalch/authz`'s core events, so a host writes
+its own events through the same `record`/`recordAs`/`writeServiceEvent` path core events use,
+never a second one of its own (authz#83, archon#72). `definePolicy(data, binding)` accepts
+`hostEvents` in `binding` and carries it onto the returned `StorePolicy`; a `hostEvents` name that
+repeats a core event name is a configuration error and `definePolicy` throws. `recordAs` and
+`writeServiceEvent` each gain an optional trailing `binding` parameter, since neither had one to
+read `hostEvents` off before.
+
+`EventInput.action` (on `record`, `recordAs` and `writeServiceEvent`) is now `EventName |
+(string & {})`: core names still autocomplete, and any other string is accepted only when it is
+listed in the binding's `hostEvents`; anything else throws before the row is built any further,
+naming the action. **The store's own baseline `authz_events_action_check` constraint still lists
+core events only** — this package's migrations are unchanged. A host that adopts `hostEvents` must
+widen that CHECK in its own migration first (hosts that don't adopt keep their existing
+constraint as-is).
+
+0.4.0 (authz#83 round 2) adds a `./policy` subpath export
+(https://github.com/wtfalch/boule/pull/162): `definePolicy` plus `StorePolicy`,
+`StoreBinding`, `PolicyData` and `PolicyRoleTemplate`, and nothing else, for a
+client component that only needs the policy catalogue for permission labels.
+The main entry (`.`) still exports everything it does today — this is
+additive — but it also drags in `migrateStore`, which imports
+`node:fs/promises` and breaks a production client build; `./policy`'s import
+graph is proved free of any `node:` module, `drizzle-orm` or a database handle
+by `scripts/tests/package-contract.test.mjs`. 0.4.0 also exports the five
+membership row helpers from `src/membership-rows.ts` off the main entry —
+`insertMembershipRow`, `deleteMembershipRow`, `changeRoleRow`,
+`guardStaysHeldRow`, `membersOfRow` — so `@wtfalch/people` can call this
+package's copy instead of carrying its own
+(https://github.com/wtfalch/people/issues/16). No behaviour change: each
+helper writes an audit row only when a `MembershipRowAuditOptions` writer is
+passed, exactly as before.
+
 ## Migrations
 
 The package ships its own SQL in `migrations/`, and `migrateStore(db)` applies
@@ -68,7 +456,7 @@ The engine has no runtime dependencies, and a test scans its whole published
 imports `node:crypto`, which is precisely what that scan rejects. The separation
 is asserted, not intended: see `the store package exports exactly what it
 promises, and is Node-only by nature` in
-`/Users/william.falch/Documents/dev/authz/scripts/tests/package-contract.test.mjs`.
+`scripts/tests/package-contract.test.mjs`.
 
 ## A note for a Next.js host
 

package/dist/activations.d.ts

@@ -0,0 +1,60 @@
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+/** Whether a requested set of permissions needs a second approver at all (ADR 0016). */
+export declare function needsCoApproval(permissions: readonly string[], policy: Pick<StorePolicy, 'requiresCoApproval'>): boolean;
+export interface RequestActivationOptions {
+    readonly permissions: readonly string[];
+    readonly reason: string;
+    readonly reference: string;
+    /** Defaults to 60; a working session, not a fixed package ceiling. */
+    readonly minutes?: number;
+}
+/**
+ * Opens an activation. Every static check runs before the transaction, the
+ * same ordering `startBreakGlass` uses, so a malformed request never reaches
+ * the lock. `principalClass` is always `'human'`: agents and services cannot
+ * open one (no inbox for the self-approve-wait email, nothing eligible to
+ * approve on their behalf), and a credential is not a principal at all
+ * under D10.
+ */
+export declare function requestActivation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'elevated' | 'requiresCoApproval'>, options: RequestActivationOptions): Promise<Result<{
+    id: string;
+    status: 'pending' | 'active';
+    expiresAt: Date;
+}>>;
+export interface ApproveActivationOptions {
+    readonly activationId: string;
+    readonly decision: 'approved' | 'denied';
+    readonly reason?: string;
+}
+/**
+ * A second person's decision on someone else's pending activation. Refuses
+ * a same-principal row unconditionally, in every branch -- there is no path
+ * here that lets a requester sign their own activation; that is
+ * `selfApproveActivation`, a different action (ADR, "The two-person
+ * approval is Boule's own check").
+ */
+export declare function approveActivation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'requiresCoApproval'>, options: ApproveActivationOptions): Promise<Result<{
+    status: 'active' | 'denied';
+}>>;
+/**
+ * The solo path: the requester approves their own activation once no
+ * Aged-and-Independent person besides them is eligible, and only after a
+ * 24-hour wait re-checked inside this locked transaction (ADR, "The
+ * self-approve wait, enforced lazily like everything else here"). A
+ * manufactured second account never counts toward "another eligible
+ * approver exists" here, because `eligibleApprovers` already excludes
+ * anyone whose eligibility traces back to this same requester.
+ */
+export declare function selfApproveActivation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], policy: Pick<StorePolicy, 'requiresCoApproval'>, activationId: string): Promise<Result<{
+    status: 'active';
+}>>;
+/**
+ * Ends one's own activation, pending or active -- a safety valve, not a
+ * power, the same framing `endBreakGlass` gives ending your own session.
+ * The ADR names no permission for ending someone *else's* (unlike
+ * `break_glass:end-any`), so that branch does not exist here; see this
+ * wave's report.
+ */
+export declare function endActivation(access: Access, db: DbOrTx, scopeColumn: Scope['column'], activationId: string): Promise<Result<void>>;