@antelopejs/interface-dms 0.10.4 → 0.12.0

package/docs/1.core/7.hooks.md

@@ -1,24 +1,20 @@
 ---
 title: "Hooks"
-description: "A hook is a named platform event with a typed argument list and a typed result."
+description: "A hook is a named platform event with a typed argument list and a typed result. The Hook enum, its payloads, registration, and the dispatchers."
+mode: reference
 ---
 
-# Hooks
-
-## Overview
-
-A hook is a named platform event with a typed argument list and a typed result. Modules register handlers with `RegisterHook`, and the code that owns the event dispatches it: `ExecuteHooks` runs every handler and discards what they return, `CollectHooks` gathers their return values, and `GetRegisteredHooks` hands back the handlers themselves for a caller that must invoke each one differently. `HookSignatures` ties each `Hook` member to its arguments and result, so the compiler checks a handler against the hook it registers for.
+A hook is a named platform event with a typed argument list and a typed result. Modules register handlers with `RegisterHook`, and the code that owns the event dispatches it. `ExecuteHooks` runs every handler and discards what they return. `CollectHooks` gathers their return values. `GetRegisteredHooks` returns the handlers themselves, for a caller that must call each one with its own arguments. `HookSignatures` maps each `Hook` member to its arguments and result, so the compiler checks a handler against the hook it registers for.
 
 Everything on this page lives in `@antelopejs/interface-dms/hooks`.
 
-## Register a Handler
+## Register a handler
 
-```typescript
+```typescript fragment
 import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
 
 export function registerBillingHooks(): void {
   RegisterHook(Hook.MEMBER_ADDED, async (payload) => {
-    // payload: { tenantId, userId, isTenantOwner }
     await seedBillingProfile(payload.tenantId, payload.userId);
   });
 
@@ -28,13 +24,13 @@ export function registerBillingHooks(): void {
 }
 ```
 
-`RegisterHook<H>(name: H, callback: HookHandler<H>, options?: HookRegistrationOptions)` appends the callback to the hook's list. The check is a TypeScript one: `HookHandler<H>` derives the parameter and return types from `HookSignatures[H]`, so a mismatched handler is a compile error. At runtime the call performs no validation.
+`RegisterHook<H>(name: H, callback: HookHandler<H>, options?: HookRegistrationOptions)` appends the callback to the hook's list. The check happens at compile time. `HookHandler<H>` derives the parameter and return types from `HookSignatures[H]`, so a mismatched handler is a compile error. At runtime the call validates nothing.
 
-A hook whose result is `undefined` is an event: its dispatchers discard what the handlers return, so such a handler may return anything — nothing, the result of the write it awaited, or a promise of it. `HookHandlerResult<H>` is that rule: `unknown` for these hooks, the hook's result (or a promise of it) for a hook that has one, such as `Hook.TENANT_DATA_EXPORT`.
+A hook whose result is `undefined` is an event. Its dispatchers discard what the handlers return, so such a handler may return anything, including nothing, the result of a write it awaited, or a promise of it. `HookHandlerResult<H>` encodes that rule. It is `unknown` for an event hook. For a hook that has a result, such as `Hook.TENANT_DATA_EXPORT`, it is that result or a promise of it.
 
-A registration belongs to the module that makes it, and goes away with it. When the module is destroyed — it stops for good, or it reloads in development — its handlers are released, and a reloaded module registers its own again from its next `construct()`. A module therefore has nothing to unregister on its way out.
+A registration belongs to the module that makes it. When that module is destroyed, because it stops for good or reloads in development, its handlers are released. A reloaded module registers its own again from its next `construct()`. A module therefore has nothing to unregister when it stops.
 
-Every registration records the module it came from, resolved from the registering call site. `HookRegistrationOptions.moduleId` overrides that resolution:
+Every registration records a module id, resolved from the module that makes the call. `HookRegistrationOptions.moduleId` overrides it:
 
 ```typescript
 interface HookRegistrationOptions {
@@ -42,11 +38,11 @@ interface HookRegistrationOptions {
 }
 ```
 
-The id only matters to a dispatcher that treats handlers per module rather than as one flat list — the tenant data export namespaces each contributor's archive entries by it. Set it explicitly whenever the registration happens somewhere the runtime would attribute to another module, such as a shared helper called during your module's construction. It does not change when the registration is released: that follows the module that made it.
+The id matters only to a dispatcher that treats handlers per module rather than as one list. The tenant data export namespaces each contributor's archive entries by it. Set it when the registration runs somewhere the runtime attributes to another module, such as a shared helper called while your module constructs. It does not change when the registration is released, which follows the module that made it.
 
-`UnregisterHook<H>(name: H, callback: HookHandler<H>)` removes a previously registered callback by identity, for a module that stops listening while it stays loaded. Keep a reference to the function you registered:
+`UnregisterHook<H>(name: H, callback: HookHandler<H>)` removes a registered callback by identity, for a module that stops listening while it stays loaded. When the same function is registered more than once, it removes the oldest registration. Keep a reference to the function you registered:
 
-```typescript
+```typescript fragment
 import {
   Hook,
   type HookHandler,
@@ -62,42 +58,56 @@ RegisterHook(Hook.MEMBER_ADDED, onMemberAdded);
 UnregisterHook(Hook.MEMBER_ADDED, onMemberAdded);
 ```
 
-`HookCallback` is the untyped shape the registry stores internally, `(...args: any[]) => Promise<any> | any`. Register through `HookHandler<H>` instead so the payload keeps its type.
-
-## The `Hook` Enum
+## The `Hook` enum
 
 | Member | Value | Arguments | Result |
 | ------ | ----- | --------- | ------ |
-| `Hook.DATABASE_INITIALIZED` | `"database:initialized"` | none | `undefined` — fires on every DMS start; a handler registered later runs at once (see [Initialise Against the Database](#initialise-against-the-database)) |
+| `Hook.DATABASE_INITIALIZED` | `"database:initialized"` | none | `undefined` |
 | `Hook.TENANT_BEING_PROVISIONED` | `"tenant:being-provisioned"` | `TenantProvisioningHookPayload` | `undefined` |
-| `Hook.TENANT_DELETED` | `"tenant:deleted"` | `tenantId: string` | `undefined` |
+| `Hook.TENANT_DELETED` | `"tenant:deleted"` | `tenantId: string`, `context?: TenantDeletionContext` | `undefined` |
 | `Hook.TENANT_DATA_EXPORT` | `"tenant:data-export"` | `tenantId: string`, `archive: TenantExportArchive`, `signal: AbortSignal` | `TenantDataExportContribution \| void` |
 | `Hook.INVITE_BEING_CREATED` | `"invite:being-created"` | `InviteHookPayload` | `undefined` |
 | `Hook.INVITE_CREATED` | `"invite:created"` | `InviteCreatedHookPayload` | `undefined` |
 | `Hook.INVITE_DELETED` | `"invite:deleted"` | `InviteDeletedHookPayload` | `undefined` |
 | `Hook.MEMBER_BEING_ADDED` | `"member:being-added"` | `MemberHookPayload` | `undefined` |
-| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` — fired by `changeTenantMembers` under tenant lifecycle admission before every membership write (`kind`: `added`, `removed`, `roles`, `ownership`); throwing vetoes the write |
+| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` |
 | `Hook.MEMBER_ADDED` | `"member:added"` | `MemberHookPayload` | `undefined` |
 | `Hook.MEMBER_REMOVED` | `"member:removed"` | `MemberRemovedHookPayload` | `undefined` |
 | `Hook.USER_REGISTERED` | `"user:registered"` | `UserRegisteredHookPayload` | `undefined` |
-| `Hook.USER_DELETED` | `"user:deleted"` | `UserDeletedHookPayload` | `undefined` — fires after every user deletion the DMS performs (today: a user deleting their own account), once its rows are gone; a failing handler is logged and does not bring the account back |
+| `Hook.USER_DELETED` | `"user:deleted"` | `UserDeletedHookPayload` | `undefined` |
+
+The `*_BEING_*` members fire before the write they precede. The past-tense members fire after it. `TENANT_BEING_PROVISIONED` has no past-tense counterpart. See [Enrich a workspace being provisioned](#enrich-a-workspace-being-provisioned).
+
+Some members have timing of their own:
 
-The `*_BEING_*` members fire before the write they precede; the past-tense members fire after it. `TENANT_BEING_PROVISIONED` has no past-tense counterpart — see [Enrich a Workspace Being Provisioned](#enrich-a-workspace-being-provisioned).
+- `DATABASE_INITIALIZED` fires on every DMS start, and a handler registered later runs at once. See [Initialise against the database](#initialise-against-the-database).
+- `MEMBER_BEING_CHANGED` is fired by `changeTenantMembers`, under tenant lifecycle admission, before every membership write. It fires once per change, with `kind` set to `added`, `removed`, `roles` or `ownership`. A handler that throws refuses the write.
+- `USER_DELETED` fires after every user deletion the DMS performs, once the user's rows are gone. Today the only such deletion is a user deleting their own account. The DMS catches and logs a failing handler, and the account stays deleted.
+- `USER_REGISTERED` fires after the account is created. The DMS catches and logs a failing handler, so a subscriber cannot strand a user whose account already exists.
+- `TENANT_DELETED` may fire more than once for one deletion. A handler deduplicates effects that are not idempotent by `context.operationId`.
 
-## Payload Interfaces
+## Payload interfaces
 
 ```typescript
+import type { InviteExtensionPayloads } from "@antelopejs/interface-dms/invite-extension-payloads";
+
 interface TenantProvisioningHookPayload {
   tenantId: string;
-  userId?: string; // absent for the `default` tenant
+  /** Absent for the `default` tenant. */
+  userId?: string;
   extras: Record<string, unknown>;
 }
 
+interface TenantDeletionContext {
+  operationId: string;
+}
+
 interface InviteHookPayload {
   tenantId: string;
   email: string;
   asTenantOwner: boolean;
   roleIds: string[];
+  deliveryId?: string;
 }
 
 interface InviteCreatedHookPayload extends InviteHookPayload {
@@ -105,16 +115,27 @@ interface InviteCreatedHookPayload extends InviteHookPayload {
   token: string;
 }
 
+type InviteDeletedReason =
+  | "accepted"
+  | "cancelled"
+  | "replaced"
+  | "expired"
+  | "resent";
+
 interface InviteDeletedHookPayload {
   tenantId: string;
   inviteId: string;
   email: string;
+  reason: InviteDeletedReason;
+  deliveryId?: string;
+  extensions?: InviteExtensionPayloads | null;
 }
 
 interface MemberHookPayload {
   tenantId: string;
   userId: string;
   isTenantOwner: boolean;
+  deliveryId?: string;
 }
 
 interface MemberRemovedHookPayload {
@@ -139,9 +160,13 @@ interface UserDeletedHookPayload {
 }
 ```
 
-The shapes are not uniform, and the difference between the addition and removal payloads is deliberate: `MEMBER_BEING_ADDED` and `MEMBER_ADDED` describe one member with `userId`, while `MEMBER_REMOVED` carries `userIds`, because a removal can cover several members at once. Let the handler's inferred parameter type guide you.
+The shapes differ on purpose. `MEMBER_BEING_ADDED` and `MEMBER_ADDED` describe one member with `userId`. `MEMBER_REMOVED` carries `userIds`, because one removal can cover several members. The handler's inferred parameter type shows which shape a hook passes.
 
-`MemberChangeHookPayload` is `{ tenantId } & MemberChange`, a union discriminated by `kind`:
+`deliveryId` is a stable identity for an invitation decision. It is set when the event comes from a durable invitation step, which can replay after a failure. A handler uses it to recognise a replay of an event it already handled.
+
+`InviteDeletedHookPayload.reason` says why the invitation row went away. Two reasons delete the row without ending the invitation. `accepted` means the invitee joined and the invitation was consumed. `resent` means the same invitation was reissued under a new token. `extensions` holds the payloads the invitation carried, for a handler that must undo its own work. [Invites](/docs/interfaces/core/invites) covers how an invitation is resolved and replaced.
+
+`MemberChangeHookPayload` is `MemberChange & { tenantId: string }`, where `MemberChange` is a union discriminated by `kind`:
 
 ```typescript
 type MemberChange =
@@ -151,21 +176,21 @@ type MemberChange =
   | { kind: "ownership"; userId: string; isTenantOwner: boolean; previousIsTenantOwner: boolean };
 ```
 
-Read `kind` first and return early for the kinds your policy does not limit. An invitation acceptance is an `added` change carrying its `deliveryId`, vetoed before the acceptance is persisted, including on replay: a `deliveryId` is not a policy exemption. See [`changeTenantMembers`](/docs/interfaces/core/tenancy#changetenantmembers) for which writes announce which kind.
+Read `kind` first and return early for the kinds your policy does not limit. An invitation acceptance is an `added` change that carries its `deliveryId`. The veto runs before the acceptance is stored, on a replay too, so a `deliveryId` does not exempt a change from policy. See [`changeTenantMembers`](/docs/interfaces/core/tenancy#changetenantmembers) for which writes announce which kind.
 
-`UserDeletedHookPayload.tenantIds` lists the workspaces the user was a member of, all left before the deletion; delete the per-user rows your module keeps in them. `reason` is `"self"` today, the user deleting their own account.
+`UserDeletedHookPayload.tenantIds` lists the workspaces the user was a member of. The user left all of them before the deletion. A module deletes the per-user rows it keeps in them. `reason` is `"self"` today, a user deleting their own account.
 
-`InviteCreatedHookPayload` carries the invite `token`. It is a signup credential: keep it inside the handler rather than forwarding it to a wider surface.
+`InviteCreatedHookPayload` carries the invite `token`. The token is a signup credential, so keep it inside the handler and do not forward it.
 
-`TenantProvisioningHookPayload.extras` is opaque: the DMS reads no key of it, validates nothing and stores nothing. See [Enrich a Workspace Being Provisioned](#enrich-a-workspace-being-provisioned).
+`TenantProvisioningHookPayload.extras` is opaque. The DMS reads no key of it, validates nothing and stores nothing. See [Enrich a workspace being provisioned](#enrich-a-workspace-being-provisioned).
 
-`TENANT_DATA_EXPORT` is the one hook whose handler produces something rather than only reacting. Its argument and return types live in `@antelopejs/interface-dms/tenant-export` and are re-exported from this module, so either import path works. They are covered in [Contribute to a Tenant Data Export](#contribute-to-a-tenant-data-export).
+`TENANT_DATA_EXPORT` is the one hook whose handler returns a result. Its argument and result types live in `@antelopejs/interface-dms/tenant-export`, and this module re-exports them. [Tenant data export](/docs/interfaces/core/tenant-data-export) covers them.
 
-## Dispatch: `ExecuteHooks` vs `CollectHooks`
+## Dispatch with `ExecuteHooks` or `CollectHooks`
 
-Both take the hook and its arguments and await each handler in registration order. They differ in what they do with the outcome.
+Both take the hook and its arguments, and await each handler in registration order. They differ in what they do with the outcome.
 
-```typescript
+```typescript fragment
 async function ExecuteHooks<H extends Hook>(
   name: H,
   ...args: HookSignatures[H]["args"]
@@ -174,42 +199,40 @@ async function ExecuteHooks<H extends Hook>(
 async function CollectHooks<H extends Hook>(
   name: H,
   ...args: HookSignatures[H]["args"]
-): Promise<HookSignatures[H]["result"][]>;
+): Promise<Awaited<HookHandlerResult<H>>[]>;
 ```
 
 | | `ExecuteHooks` | `CollectHooks` |
 | --- | --- | --- |
-| Return value | `Promise<void>` — handler results are discarded | `Promise<Result[]>` — one entry per handler that returned |
-| A handler that throws | The rejection propagates to the caller and the remaining handlers do not run | The error is logged and the handler contributes nothing; the remaining handlers still run |
-| Use for | Notifying that something happened | Asking every handler to contribute something |
+| Return value | `Promise<void>`. Handler results are discarded. | `Promise<Result[]>`, one entry per handler that did not throw. `Result` is the hook's declared result, and `unknown` for an event hook, whose handlers may return anything. |
+| A handler that throws | The rejection reaches the caller, and the remaining handlers do not run. | The error is logged and the handler adds no entry. The remaining handlers still run. |
+| Use for | Announcing that something happened | Asking every handler to contribute something |
 
-Use `ExecuteHooks` for the notification hooks — a failing handler should be able to fail the operation that fired it. Use `CollectHooks` for contribution hooks, where one broken module must not sink the whole collection.
+Use `ExecuteHooks` for the notification hooks, where a failing handler fails the operation that fired it. Use `CollectHooks` where one broken module must not stop the others. On an event hook, `CollectHooks` still runs every handler and returns whatever each one returned, typed `unknown`.
 
-```typescript
+```typescript fragment
 import {
   CollectHooks,
   ExecuteHooks,
   Hook,
 } from "@antelopejs/interface-dms/hooks";
 
-// notify: every handler runs, nothing is returned
 await ExecuteHooks(Hook.TENANT_DELETED, tenantId);
 
-// collect: gather what every handler returned, skipping the ones that threw
-const payloads = await CollectHooks(Hook.MEMBER_ADDED, {
+const results = await CollectHooks(Hook.MEMBER_ADDED, {
   tenantId,
   userId,
   isTenantOwner: false,
 });
 ```
 
-A caller that must not be broken by a subscriber wraps `ExecuteHooks` in its own `try`/`catch` — the DMS does this for `USER_REGISTERED`, where a failing subscriber would otherwise strand a user whose account was already created.
+A caller that a subscriber must not break wraps `ExecuteHooks` in its own `try`/`catch`. The DMS does so for `USER_REGISTERED` and `USER_DELETED`.
 
-## Dispatch Handler by Handler: `GetRegisteredHooks`
+## Dispatch handler by handler with `GetRegisteredHooks`
 
 Both dispatchers pass the same arguments to every handler. When each handler needs arguments of its own, take the list instead:
 
-```typescript
+```typescript fragment
 function GetRegisteredHooks<H extends Hook>(name: H): RegisteredHook<H>[];
 
 interface RegisteredHook<H extends Hook> {
@@ -218,27 +241,27 @@ interface RegisteredHook<H extends Hook> {
 }
 ```
 
-`moduleId` is what the registration recorded — the `HookRegistrationOptions.moduleId` that was passed, or the module the runtime attributed the call to — and is `undefined` when neither resolved. Handling the failures is the caller's job here: nothing wraps the handler for you.
+`moduleId` is the id the registration recorded. It is the `HookRegistrationOptions.moduleId` passed, or else the module the runtime attributed the call to, and `undefined` when neither resolved. The caller handles failures, because nothing wraps the handler.
 
-This is how the tenant data export runs. Each contributor needs an archive namespaced under its own module id, which no shared argument list can express.
+The tenant data export runs this way. Each contributor needs an archive namespaced under its own module id, which no shared argument list can express.
 
-## Initialise Against the Database
+## Initialise against the database
 
-`DATABASE_INITIALIZED` behaves like an already-resolved promise rather than a one-off event. The DMS fires it from its `start()`, once the database schemas are registered, and the hook then stays settled until the DMS stops:
+`DATABASE_INITIALIZED` behaves like a promise that has already resolved. The DMS fires it from its `start()`, once the database schemas are registered, and the hook stays settled until the DMS stops:
 
-- A handler registered before that runs when the DMS starts, in series with the others, as `ExecuteHooks` runs them. One that throws fails the DMS start.
-- A handler registered while it is settled — by a module loaded after the DMS started, or one reloaded in development — runs at once, in the background. The registration does not wait for it, and a failure is logged with the hook and module name rather than thrown into the registering module's `construct()` or `start()`.
+- A handler registered before the DMS starts runs when it starts, in series with the others, as `ExecuteHooks` runs them. A handler that throws fails the DMS start.
+- A handler registered while the hook is settled runs at once, in the background. This covers a module loaded after the DMS started, and a module reloaded in development. The registration does not wait for the handler. A failure is logged with the hook and module name, and is not thrown into the registering module's `construct()` or `start()`.
 - A handler registered while the DMS is stopped waits for its next start.
 
-A handler therefore runs once per DMS start and once per registration made while the DMS runs, which adds up to several times over the life of a process: the DMS itself reloading replays every handler, and a module that reloads registers — and so runs — its own again. Write it to be safe to replay against a live database: create what is missing, never insert unconditionally, and never send a message or charge from it without a record that it already happened.
+A handler therefore runs once per DMS start, and once per registration made while the DMS runs. Over the life of a process that adds up to several runs. A DMS reload replays every handler, and a reloaded module registers its handler again, which runs it again. Write the handler so it is safe to replay against a live database. Create what is missing, never insert unconditionally, and never send a message or charge from it without a record that it already happened.
 
-The settled state is what `SettleHook` and `UnsettleHook` manage. Only the hooks typed `StickyHook` accept them, and only `DATABASE_INITIALIZED` is one; the DMS is the only caller.
+`SettleHook` and `UnsettleHook` manage the settled state. They accept only the hooks typed `StickyHook`, and `DATABASE_INITIALIZED` is the only one. The DMS is the only caller.
 
-## Enrich a Workspace Being Provisioned
+## Enrich a workspace being provisioned
 
-A SaaS signup provisions a workspace, and the product running it usually collects more at that moment than the DMS models — an acquisition source, a team size, a referral code. `TENANT_BEING_PROVISIONED` is where a module writes those to its own tables, while the provisioning is still undone.
+A SaaS signup provisions a workspace, and the product often collects more at that moment than the DMS models, such as an acquisition source, a team size or a referral code. A module writes those to its own tables in a `TENANT_BEING_PROVISIONED` handler, while the provisioning is not yet final.
 
-```typescript
+```typescript fragment
 import {
   Hook,
   RegisterHook,
@@ -252,126 +275,33 @@ RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId, userId, extras })
 });
 ```
 
-The hook is dispatched with `ExecuteHooks`, so handlers run in series, each awaited, and **a handler that throws aborts the provisioning**: the rejection reaches the emitter, later handlers do not run, and the emitter unwinds the workspace it was creating. A workspace therefore never ends up provisioned while the enrichment a consumer needed failed to be written — that direction is the guarantee, and the reason to fire before the commit rather than after it.
+The hook is dispatched with `ExecuteHooks`, so handlers run in series, each awaited. A handler that throws aborts the provisioning. The rejection reaches the emitter, later handlers do not run, and the emitter removes the workspace it was creating. A workspace therefore never ends up provisioned while an enrichment a consumer needed failed to be written. The hook fires before the commit to give that guarantee.
 
-The other direction is not guaranteed, and no hook could provide it: there is no shared transaction to enlist in. A handler that already returned has committed its own rows, and neither a later handler throwing nor the emitter failing afterwards takes them back. Two habits make that survivable:
+The reverse does not hold, because there is no shared transaction. A handler that already returned has committed its own rows. A later handler that throws, or an emitter that fails afterwards, does not take them back. Two habits make that safe:
 
-- Key the write on `tenantId`, so it can be cleaned up along with the workspace — subscribing to `TENANT_DELETED` covers the ordinary deletion path.
-- Make it idempotent, so a retried signup does not double it.
+- Key the write on `tenantId`, so it can be cleaned up with the workspace. A `TENANT_DELETED` handler covers the normal deletion path.
+- Make the write idempotent, so a retried signup does not write it twice.
 
-The flip side is the usual one for a `*_BEING_*` hook: a handler that throws for its own reasons fails somebody's signup, so keep it to what genuinely must not be lost.
+A handler that throws for its own reasons fails someone's signup. Keep its work to what must not be lost.
 
-`extras` is opaque by design. The DMS reads no key of it, validates nothing, and stores nothing — it carries the object from the caller of the provisioning flow to the handlers, and each handler writes what it recognises. The shape is a contract between that caller and that handler, one the DMS is deliberately not a party to, so a product can start collecting a new field without waiting on a DMS release.
+`extras` is opaque. The DMS reads no key of it, validates nothing, and stores nothing. It carries the object from the caller of the provisioning flow to the handlers, and each handler writes the keys it recognises. The shape is a contract between that caller and that handler, and the DMS is not part of it. A product can therefore collect a new field without a DMS release.
 
-It fires once per tenant, when the tenant is created, and never again on a later start once it has succeeded. The DMS fires it for the `default` tenant once every module has started, so a module's tables and settings are ready; that payload has no `userId`, since the `default` tenant has no owner until onboarding. Replicas sharing a new database elect a holder through a lease on the tenant's row, and the others serve meanwhile. A holder that stops renewing for `provisioningLease.staleAfterMs` is taken over, even if its handlers are still running. If that attempt fails, or its process dies, the next start or another replica runs every handler again, so a handler skips what it already wrote. A SaaS module such as **`dms-saas`** fires it for each workspace its signup flow creates.
+The hook fires once per tenant, when the tenant is created, and never again on a later start once it has succeeded. The DMS fires it for the `default` tenant once every module has started, so the tables and settings that modules registered are ready. That payload has no `userId`, because the `default` tenant has no owner until onboarding. Replicas that share a new database elect one holder through a lease on the tenant's row, and the others serve meanwhile. A holder that stops renewing for `provisioningLease.staleAfterMs` is taken over, even if its handlers are still running. If that attempt fails, or its process dies, the next start or another replica runs every handler again, so a handler skips what it already wrote. A SaaS module such as `dms-saas` fires the hook for each workspace its signup flow creates.
 
-This is where a module writes the **default data** a tenant starts with — templates, folders, a sender, a demo history. Written once, that data belongs to the tenant: the module does not write it again on a later start, does not compare it with what members changed since, and does not wait for the tenant from `start()` or `DATABASE_INITIALIZED`.
+A module writes the default data a tenant starts with in this hook, such as templates, folders, a sender or a demo history. Once written, that data belongs to the tenant. The module does not write it again on a later start, does not compare it with what members changed since, and does not wait for the tenant from `start()` or `DATABASE_INITIALIZED`.
 
-```typescript
+```typescript fragment
 RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
   await writeDefaultFolders(tenantId);
 });
 ```
 
-An emitter fires the hook through `ProvisionTenant` from `@antelopejs/interface-dms/tenant-provisioning`, never with a bare `ExecuteHooks`. It registers the tenant as an instance of the `dms-tenant` schema first, then runs the handlers, so no handler runs before the instance exists, whatever order the modules registered in.
-
-## Contribute to a Tenant Data Export
-
-`TENANT_DATA_EXPORT` asks every module for its slice of one tenant's data, which is assembled into a single ZIP archive. A handler receives the tenant id, an archive to write into, and an `AbortSignal`. It has two ways to contribute, and may use both:
-
-- Return a `TenantDataExportContribution` — its `data` is serialized to `modules/<moduleId>.json`.
-- Write entries into the `archive` — for anything too large to hold in memory, or that is not JSON.
-
-Register with `RegisterTenantDataExportContributor` rather than a bare `RegisterHook`. It names the module id explicitly, and that id is what namespaces the contributor's archive entries:
-
-```typescript
-import { RegisterTenantDataExportContributor } from "@antelopejs/interface-dms/hooks";
-
-RegisterTenantDataExportContributor(
-  "@acme/dms-billing",
-  async (tenantId, archive, signal) => {
-    await archive.addStream(
-      "invoices.ndjson",
-      streamInvoices(tenantId, signal),
-    );
-    return {
-      moduleId: "@acme/dms-billing",
-      data: await collectBillingSettings(tenantId),
-    };
-  },
-);
-
-```
-
-The helper's signature is shown separately for reference:
-
-```typescript
-import type { Hook, HookHandler } from "@antelopejs/interface-dms/hooks";
-
-declare function RegisterTenantDataExportContributor(
-  moduleId: string,
-  handler: HookHandler<Hook.TENANT_DATA_EXPORT>,
-): void;
-```
-
-A handler that only writes archive entries returns nothing.
-
-```typescript
-interface TenantDataExportContribution {
-  moduleId: string;
-  data: unknown;
-}
-```
-
-### `TenantExportArchive`
-
-```typescript
-import type { Readable } from "node:stream";
-
-interface TenantExportArchive {
-  addJson(path: string, data: unknown): Promise<void>;
-  addFile(path: string, localPath: string): Promise<void>;
-  addStream(path: string, stream: Readable): Promise<void>;
-}
-```
-
-| Method | Adds |
-| ------ | ---- |
-| `addJson` | `data` serialized as a JSON entry. |
-| `addFile` | An artifact already materialized on disk, read from `localPath`. |
-| `addStream` | A remote or generated dump, without ever holding it in memory. |
-
-Paths are relative: the implementation prefixes every entry with `modules/<moduleId>/`, so two contributors can both write `invoices.ndjson` without colliding, and none has to defend against another's paths.
-
-**Await every call.** Each method resolves only once the archiver has consumed the entry — awaiting is what propagates back-pressure to whatever produces the data, and is what keeps memory flat however large the export grows. Firing them without `await` gives up both.
-
-The `signal` aborts when the export is cancelled or times out. Pass it down to whatever produces your data so a cancelled export stops reading rather than finishing into a discarded archive.
-
-### The Manifest
-
-Every run writes a `manifest.json` at the archive root recording what each contributor produced:
-
-```typescript
-interface TenantExportManifest {
-  tenantId: string;
-  exportedAt: string;
-  partial: boolean;
-  modules: TenantExportModuleReport[];
-}
-
-interface TenantExportModuleReport {
-  moduleId: string;
-  declaredModuleId?: string;
-  entries: string[];
-  failed: boolean;
-  error?: string;
-}
-```
+An emitter fires the hook through `ProvisionTenant` from `@antelopejs/interface-dms/tenant-provisioning`, never with a bare `ExecuteHooks`. `ProvisionTenant` registers the tenant as an instance of the `dms-tenant` schema first, then runs the handlers. No handler runs before the instance exists, whatever order the modules registered in.
 
-A failing contributor does not fail the export: its report carries `failed: true` and the error message, and `partial` goes `true` on the manifest so a consumer can tell an incomplete archive from a complete one. `declaredModuleId` appears when the returned contribution named a different id than the one the archive namespaced the entries under — a sign the registration and the return value disagree.
+## Contribute to a tenant data export
 
-Running the export is the other side of this contract: `buildTenantExportArchive` drives the contributors and writes the ZIP, and `startTenantExportJob` runs it as a background export job. Both belong to the [Base](/docs/interfaces/base/introduction) domain, under its helpers.
+`TENANT_DATA_EXPORT` asks every module for its part of one tenant's data, assembled into a single ZIP archive. Register a contributor with `RegisterTenantDataExportContributor`. [Tenant data export](/docs/interfaces/core/tenant-data-export) covers the handler, the archive it writes into, and the manifest.
 
-## Next Steps
+## Next steps
 
-[Realtime](/docs/interfaces/core/realtime) covers pushing an event to an open page instead of reacting to a platform event.
+[Realtime](/docs/interfaces/core/realtime) covers pushing an event to an open page, as opposed to reacting to a platform event.