spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/reference/functions/integration-outbound.md

@@ -0,0 +1,200 @@
+---
+title: integration-outbound
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/functions/_shared/retry-deliveries.ts
+  - .framework/functions/_shared/llm.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/adapters/generic-webhook-outbound.ts
+  - .framework/functions/adapters/openai-outbound.ts
+  - .framework/functions/adapters/resend-outbound.ts
+  - .framework/functions/deliveries.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - public/_redirects
+---
+
+# integration-outbound
+
+## What it does
+
+`integration-outbound` (`.framework/functions/integration-outbound.ts`) is the
+single egress path for outbound calls. Every attempt is recorded as a
+`webhook_deliveries` row (`direction: 'outbound'`), so there is no
+fire-and-forget — the delivery row exists before, during, and after the wire
+call.
+
+`execute` runs this sequence:
+
+1. Resolve the integration row by `integration_slug`: the caller-account row
+   first, then a system row (`account_id IS NULL`); both must be `is_active`.
+2. Open (or reuse, on `delivery_id`) the `webhook_deliveries` row — `status:
+   'pending'`, `attempt_count: 0`, `max_attempts` from
+   `action_config.max_attempts` → `integration.config.retry_policy.max_attempts`
+   → `3`.
+3. Resolve the credential field (`action_config.credential_field`, default
+   `api_token`) via `resolveCredential` (`.framework/functions/_shared/
+   resolve-credentials.ts`) — server-side only: `source: 'env_var'` reads
+   `process.env[value]`, `source: 'value'` returns the literal. An absent or
+   explicitly-empty (`source: 'value'`, `value: ''`) entry means "call
+   without auth": `execute` skips resolution, passes no credential to the
+   adapter, and audits `integration.credential_missing` /
+   `integration.credential_empty` with `skipped: true` — the adapter decides
+   whether a key is required. A named-but-unset `env_var` still throws. Every
+   resolution or failure emits an `integration.credential_*` audit event.
+4. Pick the adapter: `action_config.adapter ||
+   integration.config.outbound_adapter`. Built-ins live in
+   `builtInOutboundAdapters` (`adapters/openai-outbound`,
+   `adapters/generic-webhook-outbound`, `adapters/resend-outbound`); any other
+   name is dynamically imported as `./<name>` and must export `buildRequest`.
+5. `fetch` the request the adapter built, then update the delivery to
+   `delivered` (with `response_status`, `response_body`, `duration_ms`) or back
+   to `pending`/`failed` with `next_attempt_at`.
+
+Known callers: `_shared/llm.ts` (`callOpenAI`, `callOpenAIEmbeddings`,
+`callOpenAIChat` — all `integration_slug: 'openai'`), the pipeline stage
+handlers `http_request`, `agent_inference`, `send_email`, and
+`handler_module: 'webhook'` (all `integration_slug: 'generic-http'`), the
+`retryPendingDeliveries` sweep (`.framework/functions/_shared/
+retry-deliveries.ts`), and manual retry in `deliveries.ts`.
+
+## Route and methods
+
+- `POST /api/integration-outbound` — `public/_redirects` maps `/api/*` to
+  `/.netlify/functions/:splat`; the default export is `createHandler(execute)`.
+- There is no `action` dispatch — the request body *is* the contract.
+
+## Authentication
+
+`createHandler` resolves a principal and rejects anonymous requests with 401,
+so any authenticated caller works (human JWT or `x-api-key` machine principal).
+Internal callers import `execute` directly and pass their own `CoreContext`.
+
+The `delivery_id` (retry) path additionally requires
+`ctx.principal.isInternal` — true for the internal-invoke secret,
+`is_internal` API keys, and `SYSTEM_PRINCIPAL`. A non-internal caller passing
+`delivery_id` is *not* rejected: the stored-payload retry branch is skipped,
+but the row id is still reused for status bookkeeping instead of inserting a
+new delivery. See Agent notes.
+
+## Request contract
+
+Top-level body fields:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `integration_slug` | string | yes | `integrations.slug`; account-scoped row wins over the system row. |
+| `record_id` | uuid | no | Fetched via admin-data `get` and passed to the adapter as `record`. |
+| `action_config` | object | no | See below. |
+| `delivery_id` | uuid | no | Reuse an existing delivery row (retry path). |
+
+`action_config` keys consumed by `execute` itself:
+
+| Key | Notes |
+|---|---|
+| `adapter` | Adapter name; falls back to `integration.config.outbound_adapter`. |
+| `credential_field` | `integrations.credentials` field to resolve; default `api_token`. |
+| `max_attempts` | Overrides `config.retry_policy.max_attempts` and the default 3. |
+| `action_slug` | Stored on the delivery row for traceability. |
+| `update_record` / `update_fields` | On success, stamps `last_outbound_status`, `last_outbound_at`, plus `update_fields` onto `record_id` via admin-data `update`. |
+
+Adapter-specific `action_config` keys:
+
+- `adapters/generic-webhook-outbound` — `url` (required), `method` (default
+  `POST`), `headers`, `body`. Adds `Authorization: Bearer <credential>` when a
+  credential resolved.
+- `adapters/openai-outbound` — `endpoint` (required, e.g. `/chat/completions`,
+  `/embeddings`), `body`. Base URL from `integration.config.base_url` (default
+  `https://api.openai.com/v1`).
+- `adapters/resend-outbound` — `to` and `subject` required; `html` or `text`;
+  `from` resolves `actionConfig.from` → `config.from` → `EMAIL_FROM` env →
+  `onboarding@resend.dev`; optional `reply_to`; `config.api_url` overrides the
+  Resend endpoint.
+- Custom adapters — dynamically imported `./<name>` module exporting
+  `buildRequest(record, ctx)` → `{ url, method, headers?, body?,
+  external_id? }`.
+
+## Response contract
+
+Success returns, inside the standard `{ data, error, meta }` envelope:
+
+```json
+{ "success": true, "delivery_id": "<uuid>", "response_status": 200,
+  "response_body": { }, "is_retry": false }
+```
+
+`response_body` is the parsed JSON response, or the raw text when it isn't
+JSON. A non-2xx target response throws — the delivery row is still updated
+first (see Side effects), so the attempt is durable even though the HTTP
+response is an error envelope.
+
+## Side effects
+
+- `webhook_deliveries` insert (`pending`) or update (`processing` →
+  `delivered`/`pending`/`failed` with `attempt_count`, `next_attempt_at`,
+  `response_status`, `response_body`, `duration_ms`, `last_error`).
+- Audit events: `integration.outbound.started`, `.succeeded`,
+  `.failed_http`, `.error`, plus `integration.credential_*` events from
+  `resolveCredential`.
+- One external `fetch` per attempt. The tracking INSERT is intentionally
+  overlapped with the wire call (`insertPromise`), so logging does not
+  serialize ahead of latency.
+- Optional admin-data `update` on `record_id` when
+  `action_config.update_record` is set — runs the full permission/audit
+  pipeline, not a raw write.
+
+## Errors
+
+| Condition | Error |
+|---|---|
+| No slug | `integration_slug is required` |
+| Slug matches no active account or system integration | `Integration not found: <slug>` |
+| Retry of unknown delivery | `Delivery not found: <id>` |
+| `env_var` credential names an unset variable | `Environment variable <var> … is not set` (audits `integration.credential_env_missing`). Absent/empty credential entries do **not** throw — the call proceeds unauthenticated and the adapter enforces its own requirement (e.g. `OpenAI adapter requires api_token credential`) |
+| No adapter name resolved | `No outbound adapter configured for integration <slug>` |
+| Adapter import failed or lacks `buildRequest` | `Outbound adapter not found: <name>` |
+| Adapter returned no url/method | `Outbound adapter must return url and method` |
+| Delivery insert failed | `Failed to create outbound delivery record` |
+| Non-2xx target | `Outbound HTTP <method> to <url> failed with status <status>` |
+| Delivery-row insert races and fails | `Failed to create outbound delivery record` (surfaced where `insertPromise` is awaited) |
+
+Thrown errors map to HTTP 500 unless they carry `statusCode`; the delivery
+row keeps the attempt either way.
+
+## Agent notes
+
+- **Retry semantics.** `computeNextAttempt` is `30s * 2^attempt` capped at 1
+  hour plus up to 20% jitter. A failed attempt stays `pending` with
+  `next_attempt_at` until `attempt_count >= max_attempts`, then `failed`.
+  `retryPendingDeliveries` (run by `system-cron` each tick) sweeps `pending`
+  rows with `attempt_count < 10` whose `next_attempt_at` is due or null — up
+  to 100 per pass — and re-invokes `execute({ delivery_id })` under
+  `SYSTEM_PRINCIPAL`. Manual retry: `POST /api/deliveries?action=retry { id }`
+  — outbound only. Inbound retry is unimplemented.
+- **Non-internal `delivery_id`.** The `isInternal` check gates only the
+  *payload-replay* branch; the row id itself is still honored. An ordinary
+  caller can pass `delivery_id` and have their request's outcome stamped onto
+  that row (`status: 'processing'` → result). There is no per-account check on
+  the row — treat `delivery_id` as an internal field.
+- **`generic-http` is unauthenticated by default — and that works.**
+  Migration `004` seeds it with `api_token: { source: 'value', value: '' }`;
+  `execute` treats an absent or empty-literal credential as "no auth", so
+  `http_request`/`webhook`/`agent_inference` stages send the request with no
+  `Authorization` header on a stock install (the generic adapter only adds
+  Bearer when a credential resolved). To authenticate, set a real token or
+  point the field at an `env_var`; to authenticate differently, pass
+  `action_config.headers`. The skip is still audited as
+  `integration.credential_empty`/`credential_missing` with `skipped: true`.
+- **`openai` seed** uses `env_var: OPENAI_API_KEY`; `callOpenAIChat` defaults
+  to `gpt-4o-mini`/0.7/4000, overridable via `config.models.chat` /
+  `.embedding` on the integration row.
+- **Mock responses live in callers, not here.** `callInference` in
+  `.framework/functions/_shared/agent-runner.ts` catches "not found"/
+  "credential" errors and returns a marked mock; this function always throws.
+- Do not call outbound adapters or `fetch` external URLs directly — delivery
+  tracking, credential audit, and retry all depend on going through
+  `execute`. See [integrations and webhooks](../../concepts/integrations-and-webhooks.md).

package/.framework/src/instructions/reference/functions/integration-routes.md

@@ -0,0 +1,151 @@
+---
+title: integration-routes
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integration-routes.ts
+  - .framework/functions/_shared/webhook-registry.ts
+  - .framework/functions/_shared/webhook-registration.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/retry-deliveries.ts
+  - .framework/functions/deliveries.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - public/_redirects
+---
+
+# integration-routes
+
+## What it does
+
+`integration-routes` (`.framework/functions/integration-routes.ts`) is the
+inbound webhook surface. An external caller POSTs a provider payload to a
+named integration; the function authenticates the caller's API key, resolves
+the integration's registered handler through the `webhook_handlers` registry,
+lets the adapter normalize the payload into an item shape, creates the record
+through admin-data (full permission/type/audit pipeline), and records the
+whole attempt as a `webhook_deliveries` row (`direction: 'inbound'`).
+
+The `execute` sequence:
+
+1. Read `slug` from `?slug=` or `body.slug`; require a machine principal —
+   `ctx.principal.id` must match an `api_keys` row.
+2. Load the `integrations` row matching `slug` **and** `apiKey.account_id`
+   (inbound integrations are always account-scoped here), `is_active`.
+3. Enforce key pinning: `apiKey.integration_id` must equal the integration id
+   when set; `apiKey.app_id` must equal `integration.app_id` when both set.
+4. Extract the event name — `x-event-type` header first, else
+   `integration.config.event_path` (a dot-path into the payload).
+5. Resolve the handler name `config.handler_name || provider ||
+   'generic-webhook'` through `resolveHandler` (`.framework/functions/_shared/
+   webhook-registry.ts`): a `webhook_handlers` row maps `name → function_name`,
+   scoped by `(app_id, account_id)` with a global `NULL/NULL` fallback; the
+   module is dynamically imported (`custom/…` paths resolve into the custom
+   tree) and must export `adapt`, `handler`, or a default function.
+6. Insert the inbound `webhook_deliveries` row (`payload`, `api_key_id`,
+   `handler_name`, `external_id: body.id`), emit
+   `integration.inbound.started`, invoke the adapter, create the `items`
+   record via admin-data `create`, and mark the delivery `delivered`.
+
+## Route and methods
+
+- `/api/integration-routes?slug=<integration-slug>` — `public/_redirects`
+  maps `/api/*` to `/.netlify/functions/:splat`; the default export is
+  `createPublicHandler(execute)`.
+- `execute` performs no method check — any HTTP method with a JSON body
+  works; in practice providers POST.
+
+## Authentication
+
+`createPublicHandler` resolves a principal but does not reject anonymous
+requests — `execute` itself enforces:
+
+- `ctx.principal.id` must exist — `401 Machine principal required` otherwise
+  (JWT-only human callers have a person id, not an api-key id, so they fail
+  at the next check).
+- The id must match an `api_keys` row — `401 Invalid API key` otherwise.
+- The key's `account_id` scopes the integration lookup; a key pinned to
+  `integration_id` or `app_id` gets `403` for anything else.
+
+There is **no HMAC/signature verification** — the API key sent as
+`x-api-key` is the entire credential. Prefer keys pinned to
+`integration_id`/`app_id` and rotate them like any secret. See
+[auth and API keys](../../concepts/auth-and-api-keys.md).
+
+## Request contract
+
+| Input | Where | Notes |
+|---|---|---|
+| `slug` | query `?slug=` or `body.slug` | Integration slug, required. |
+| `x-api-key` | header | Machine credential; resolved by `resolvePrincipal`. |
+| `x-event-type` | header | Optional event name; overrides `config.event_path` extraction. |
+| payload | JSON body | Passed verbatim to the adapter; `body.id` is stored as the delivery's `external_id`. |
+
+The adapter returns:
+
+```ts
+{ type_slug: string, data: Record<string, any>, title?: string,
+  status?: string, thread?: any, links?: any[], external_id?: string,
+  error?: string, retryable?: boolean }
+```
+
+`type_slug` is required for record creation. `thread` and `links` are
+declared in the contract but currently no-ops (TODO in source).
+
+## Response contract
+
+Success returns the admin-data `create` result — the created `items` record —
+inside the standard `{ data, error, meta }` envelope, and the delivery is
+marked `delivered` with `response_status: 200`.
+
+Adapter-reported errors (`adapterResult.error`) throw with the adapter's
+message; `retryable: true` marks the delivery `pending` (with a backoff
+`next_attempt_at`) before the throw — though see Agent notes: the outer catch
+re-marks *every* post-insert error `pending`, and nothing re-delivers inbound
+rows anyway.
+
+## Side effects
+
+- `webhook_deliveries` insert (`direction: 'inbound'`, `api_key_id`,
+  `handler_name`, `payload`, `external_id`) then status updates.
+- One `items` row created via `admin-data` `create` under a synthesized
+  context (`adminDb`, `accountId: integration.account_id`,
+  `principal.id: null`) — type resolution, validation, triggers, and audit
+  all run.
+- Audit events: `integration.inbound.started`, `.delivered`,
+  `.adapter_retryable`, `.adapter_failed`, `.error`.
+
+## Errors
+
+| Status | Condition |
+|---|---|
+| 400 | `Integration slug is required` |
+| 401 | `Machine principal required` · `Invalid API key` |
+| 403 | `API key is not authorized for this integration` · `… for this app` |
+| 404 | `Integration not found: <slug>` · `Handler not found: <name>` |
+| 500 | `Failed to create inbound delivery record` · `Adapter result is missing type_slug` · adapter/admin-data errors propagate |
+
+## Agent notes
+
+- **Inbound retry is not implemented.** `retryPendingDeliveries`
+  (`.framework/functions/_shared/retry-deliveries.ts`) counts inbound rows as
+  `inbound_failed` and `deliveries?action=retry` rejects non-outbound
+  deliveries outright. Worse, the `catch` in `execute` re-marks *any* error
+  after the delivery insert as `pending` with `next_attempt_at` — including
+  non-retryable adapter errors and admin-data create failures — so failed
+  inbound deliveries sit `pending` forever. When debugging "stuck" inbound
+  rows, check `last_error`, not just `status`.
+- `registerWebhookHandler`/`deregisterWebhookHandler`
+  (`.framework/functions/_shared/webhook-registration.ts`) manage the
+  `webhook_handlers` table — upsert on `(app_id, account_id, name)`;
+  deregister soft-deletes. Migration `004` seeds the `generic-webhook`
+  handler (`adapters/generic-webhook-inbound`), which stores the raw payload
+  as a `webhook_event` item.
+- The lookup is cached per `(appId, accountId, handlerName)` in-process —
+  newly registered handlers may not resolve until a cold start.
+- Adapters run inside the function with a console `logger` and receive the
+  raw headers — they can do their own signature checks if the provider
+  requires it, but nothing enforces that.
+- See [integrations and webhooks](../../concepts/integrations-and-webhooks.md)
+  for the full mental model.

package/.framework/src/instructions/reference/functions/integrations.md

@@ -0,0 +1,130 @@
+---
+title: integrations
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integrations.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/public/_redirects
+---
+
+# integrations
+
+## What it does
+
+CRUD over `public.integrations` — the registry of external providers
+(`integration_type`: webhook/oauth/api/scheduled_sync, `provider`,
+`version`, `config`) including their `credentials` secrets map.
+Runtime delivery happens elsewhere — `integration-outbound` executes
+deliveries and `deliveries` lists them (see
+[Integrations and webhooks](../../concepts/integrations-and-webhooks.md)).
+
+## Route and methods
+
+`/.netlify/functions/integrations`, reachable as `/api/integrations`
+(`/api/*` → `/.netlify/functions/:splat`,
+`.framework/public/_redirects`). Dispatch is by HTTP method only:
+
+| Call | Handler |
+|---|---|
+| `GET /api/integrations` | `list` |
+| `GET /api/integrations?id=<uuid>` | `get` |
+| `POST /api/integrations` | `create` |
+| `PATCH /api/integrations` (`id` in body or query) | `update` |
+| `DELETE /api/integrations?id=<uuid>` | `remove` |
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list`/`create` require `ctx.accountId` (`Account context required` /
+  `User context (person and account) required`).
+- There is **no role check** anywhere in this file. System admins use
+  `adminDb`; others use `ctx.db` (JWT-scoped for humans, service role
+  for machines).
+- Credential exposure is controlled on the **read** path by
+  `sanitizeRecordData`: system admins get the full row including
+  `credentials`; every other principal gets `{ id }` — the integration
+  collapses to an opaque handle
+  (`.framework/functions/_shared/permissions.ts`,
+  `sanitizeFirstSurfaceRecordData`: no `design_schema` on the row →
+  minimal response). `credentials` never leave the function for
+  non-admins.
+
+## Request contract
+
+**list** (query): `integration_type`, `provider`, `is_active`,
+`is_configured` (`'true'`/`'false'`), `limit` (default 100), `offset`
+(default 0). Ordered by `name`; joins `app` and `created_by` person.
+
+**get** (query): `id`.
+
+**create** (body): `name`, `integration_type`, `provider` required.
+Optional: `slug` (defaults to a slugified `name`), `app_id`,
+`description`, `version` (default `'1.0.0'`), `config` (default `{}`),
+`credentials`, `metadata`. `account_id` and `created_by` are stamped
+from context. `is_configured` is **computed**, not accepted: every
+`credentials` entry must be `{ source, value }` with a non-empty string
+`value` for the flag to be `true`.
+
+**update** (`id` in body or query + body): allowlist — `name`, `slug`,
+`description`, `integration_type`, `provider`, `version`, `config`,
+`credentials`, `metadata`, `is_active`. Passing `credentials`
+recomputes `is_configured`.
+
+**remove** (query): `id` — soft delete (`is_active = false`).
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope. `list`/`get`/`create`/
+`update`/`remove` return sanitized row(s): full row for system admins,
+`{ id }` for non-admin humans. `remove` returns the deactivated row.
+
+## Side effects
+
+- `create`/`update` store `credentials` verbatim — the column is a
+  secrets map `{ field: { source: 'value'|'env_var', value } }`
+  (`.framework/migrations/004_core_rpc_and_broker.sql`), not encrypted at
+  rest by this function.
+- `update` recomputes `is_configured` whenever `credentials` is in the
+  body; it is never recomputed for `config`-only edits.
+- `emitLog` writes `integration.created` / `.updated` / `.deleted` audit
+  rows to `public.logs`. The update audit payload includes the full
+  `updateData` — **including credentials** — in `after`.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No account context | 500 | `Account context required` |
+| Missing create fields | 500 | `name, integration_type, and provider are required` |
+| No person+account context (create) | 500 | `User context (person and account) required` |
+| Missing `id` | 500 | `Integration ID is required` |
+| Row missing on delete | 500 | `Integration not found` |
+| Unknown method | 500 | `Unsupported method: <METHOD>` |
+
+Validation failures surface as HTTP 500 — thrown `Error`s without a
+`statusCode` map to 500 in the shared error path.
+
+## Agent notes
+
+- Writes are guarded only by authentication + RLS (for humans).
+  `create`/`update`/`remove` do not call any `canCreate`/`canUpdate`
+  permission check — a machine principal's service-role `ctx.db` writes
+  unconditionally.
+- `update`'s audit log records `credentials` in the `after` payload —
+  secrets land in `public.logs`. Rotate rather than patch in place if
+  log exposure matters.
+- Slug uniqueness is `UNIQUE(app_id, account_id, slug)`
+  (`.framework/migrations/004_core_rpc_and_broker.sql`); there is no
+  pre-check, so duplicates surface as PostgREST constraint errors.
+- Inbound webhook execution and credential resolution live in
+  `integration-routes`/`integration-outbound` and
+  `.framework/functions/_shared/resolve-credentials.ts` — this function
+  only manages the registry rows.

package/.framework/src/instructions/reference/functions/invites.md

@@ -0,0 +1,182 @@
+---
+title: invites
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/invites.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/rate-limit.ts
+  - .framework/functions/_shared/security.ts
+  - .framework/functions/admin-data.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/public/_redirects
+---
+
+# invites
+
+## What it does
+
+The registration and membership endpoint. Public actions probe the system
+(first user, domain match, invite-token validation); authenticated
+actions complete registration, create/revoke/re-send invites, approve or
+deny join requests, and manage account members. Invitees are `people`
+rows in `invited`/`pending` status carrying `invite_*` fields in `data`.
+
+## Route and methods
+
+`/.netlify/functions/invites`, reachable as `/api/invites` (`/api/*` →
+`/.netlify/functions/:splat`). The outer handler is a
+`createPublicHandler` dispatching **only** on `?action=` — there is no
+HTTP-method check, so `GET` and `POST` both reach every action (write
+actions still need a JSON body):
+
+| `?action=` | Auth | Purpose |
+|---|---|---|
+| `check-first-user` | public | `{ is_first_user }` — true when `people` is empty |
+| `check-domain` | public | domain→account match for registration routing |
+| `validate-token` | public | inspect an invite token (`?token=`) |
+| `complete-registration` | authenticated | place the caller via `complete_registration_placement` RPC |
+| `create-invite` | account admin | create an invited `people` stub + invite URL |
+| `list-invites` | authenticated | list pending invites, account-scoped |
+| `revoke-invite` | account admin | deactivate an invited person |
+| `reinvite` | account admin | rotate token + expiry on invited/inactive person |
+| `block-invite` | account admin | stamp `invite_blocked_at` on a person |
+| `approve` | account admin | activate a `pending` join request |
+| `deny` | account admin | deactivate a `pending` join request |
+| `list-members` | `*_admin` | list account members (via `admin-data`) |
+| `update-member` | `*_admin` | change `full_name` / `role_slug` |
+| `deactivate-member` | `*_admin` | set status `inactive` |
+
+Unknown action → `Unknown action: <action>`.
+
+## Authentication
+
+Mixed. The dispatcher is public (`createPublicHandler`), so anonymous
+reaches the three probe actions. Every other action requires an
+authenticated principal — each inner handler re-checks
+`principal.id !== 'anonymous'` and throws `Authentication required` (a
+plain `Error`, so it surfaces as HTTP 500, not 401).
+
+"Account admin" (`requireAccountAdmin`) means: principal permissions
+include `system`, **or** roles include `system_admin`, **or** any
+`*_admin` role **and** `principal.accountId` equals the target account.
+Member actions (`list-members`, `update-member`, `deactivate-member`)
+accept `system` permission or any `*_admin` role (`canManageMembers`)
+plus the same account check.
+
+## Request contract
+
+**`check-domain`** (query): `email` — must contain `@`. Personal-mailbox
+domains (gmail, yahoo, hotmail, outlook, icloud, protonmail, etc.) always
+return `{ match: false }`; otherwise matches when an active `people` row
+exists with `@<domain>`.
+
+**`validate-token`** (query): `token`. Looks up a `people` row in
+`invited`/`pending` status with `data.invite_token = <token>`.
+
+**`complete-registration`** (body): `app` and `path` required;
+`account_name`, `email` optional. `path` values are resolved by the RPC
+(e.g. `new_account` triggers extra `account_create` rate limits).
+
+**`create-invite`** (body): `email`, `account_id`, `role_slug` required;
+`full_name`, `base_url`, `app` optional. `role_slug: 'system_admin'` is
+refused, as is any role whose `is_system` flag is true or that is absent
+from the app's `invitation.allowed_roles`/`registration.roles` allowlist
+(when the app declares one).
+
+**`revoke-invite` / `reinvite` / `block-invite` / `approve` / `deny`**
+(body): `person_id` (+ `base_url` for `reinvite`).
+
+**`list-invites`** (query): `account_id` (system users may pass any;
+others are scoped to their own), `role_slugs` (comma-separated).
+
+**`list-members`** (query/body): `account_id` (defaults to the caller's).
+**`update-member`** (body): `person_id`, `full_name`, `role_slug`.
+**`deactivate-member`** (body): `person_id`.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `check-first-user` → `{ is_first_user: boolean }`.
+- `check-domain` → `{ match, account_id? }`.
+- `validate-token` → `{ email, full_name, account_name, role_name,
+  kind }`.
+- `complete-registration` → `{ status, account_slug, role_slug?, next? }`
+  from the RPC placement.
+- `create-invite` → `{ id, token, invite_url, expires_at, email_sent }`.
+- `reinvite` → `{ token, invite_url, expires_at }`.
+- `list-invites` → array of `{ id, email, full_name, status, kind,
+  expires_at, blocked_at, created_at, account, role }`.
+- `revoke-invite`/`block-invite`/`approve`/`deny` → `{ success: true }`.
+- `list-members` → `{ data: [...] }`; `update-member`/`deactivate-member`
+  → `{ success: true, data }`.
+
+## Side effects
+
+- `create-invite`/`reinvite` write `people` rows (via `admin-data` create
+  for the stub): `data.invite_token` (16-char alnum),
+  `invite_kind: 'invite'`, `invite_expires_at` (now + 7 days),
+  `invite_attempts: 0`, `invite_blocked_at`, `invite_invited_by`.
+- `invite_url` = `<base>/register?t=<token>`; `base_url` is honored only
+  for localhost or origins in `APP_BASE_URL`/`ALLOWED_ORIGINS`, otherwise
+  falls back to `APP_BASE_URL`.
+- `create-invite` sends email through `integration-outbound` when an
+  active `invite-email` (preferred) or `transactional-email` integration
+  exists; `config.templates.invite` subject/html support
+  `{{to_name}}`, `{{invite_url}}`, `{{account_name}}`, `{{expires_at}}`
+  placeholders, with a built-in HTML fallback.
+- `complete-registration` calls the service-role
+  `complete_registration_placement` RPC (the only writer of
+  `account_id`/`role_id` placement), then `recordRegistrationGeo` +
+  `registration.completed` log.
+- `checkRegistrationBlocklist` (email, email domain, IP) runs before
+  placement; `checkRateLimit` enforces `registration` and
+  `account_create` (person + IP keyed), `invite_create`, and
+  `invite_email` (account keyed).
+- `emitLog` writes `invite.created`, `invite.revoked`,
+  `invite.reinvited`, `invite.approved`, `invite.blocked`,
+  `invite.denied`, `member.updated`, `member.deactivated`.
+- Member actions delegate to `admin-data` list/update internally, so
+  admin-data logging and trigger firing apply there too.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Anonymous on a gated action | 500 | `Authentication required` |
+| Not an account admin | 500 | `Insufficient permissions — *_admin role required for this account` (and member variants) |
+| Missing required fields | 500 | `email, account_id, and role_slug are required` / `app and path are required` / `person_id is required` / `Token is required` / `Valid email is required` |
+| Unknown action | 500 | `Unknown action: <action>` |
+| `system_admin` or system role requested | 500 | `Role '<slug>' is not permitted in this context` / `Role '<slug>' not found` |
+| Duplicate email+account | 500 | `A person with this email already exists or has a pending invite for this account` |
+| Bad/used token | 500 | `Invite not found or already used` |
+| Blocked invite | 500 | `This invite link has been blocked. Please contact the administrator.` |
+| Expired invite | 500 | `This invite link has expired. Please request a new one.` |
+| ≥5 failed attempts | 500 | `Too many failed attempts. This invite has been blocked.` |
+| Registration blocklist hit | 403 | `This registration is not eligible. Contact support if you believe this is an error.` |
+| Rate limit | 429 | `RateLimitError` envelope fields (`action`, `limit`, `retry_after`) |
+| RPC placement failure | 400 | RPC message or `Registration placement failed` |
+| Wrong state | 500 | `Invite not found or already processed` / `Person is not in a reinvitable state` / `Access request not found or already processed` |
+
+## Agent notes
+
+- First-user bootstrap is **not** here — the Postgres
+  `handle_new_auth_user` trigger grants `system_admin` on the very first
+  signup. `check-first-user` only reports whether `people` is empty.
+- Invite tokens live on `people.data.invite_token`; revoke clears the
+  token and deactivates; reinvite rotates it (`invited` or `inactive`
+  rows only); `validate-token` enforces expiry, `invite_blocked_at`, and
+  the 5-attempt ceiling.
+- `approve`/`deny` target `status = 'pending'` rows — the join-request
+  path — while `revoke-invite` targets `invited`/`pending`.
+- `update-member` can only assign roles allowed by the target account's
+  owned apps (`invitation.allowed_roles`/`registration.roles` in
+  `apps.config`), and never `system_admin` or `is_system` roles.
+- `list-invites` does **not** verify membership in the queried account —
+  it scopes by `account_id` for non-system callers but accepts any
+  `account_id` they pass. Don't treat it as an authorization boundary.
+- Registration never trusts client claims: the placement RPC derives
+  account and role server-side from the app's registration config.