spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/reference/functions/pipeline-runner-background.md

@@ -0,0 +1,121 @@
+---
+title: pipeline-runner-background
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/pipeline-runner-background.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/principal.ts
+  - netlify.toml
+---
+
+# pipeline-runner-background
+
+## What it does
+
+The isolated executor for trigger-dispatched pipeline runs. When a record
+write matches a trigger, `.framework/functions/_shared/trigger-engine.ts`
+inserts a `pipeline_executions` row with `status: 'queued'` and POSTs the
+dispatch payload here. This function authenticates the call, reconstructs
+a machine `RequestContext`, and hands the pre-created `execution_id` to
+`runPipeline` — so the queued row transitions `queued → running → terminal`
+instead of a duplicate execution being inserted.
+
+The `-background` filename suffix makes Netlify treat it as a background
+function: the dispatcher gets a 202 acknowledgement immediately and the
+run itself gets the fixed 15-minute invocation budget in its own process
+and connection pool (see the note in `netlify.toml`). It is **not** a
+scheduled function — it is invoked once per trigger fire, over HTTP.
+
+## Route and methods
+
+`POST /.netlify/functions/pipeline-runner-background` — internal
+function-to-function traffic only. The only caller in the framework is the
+trigger engine's dispatch path, which sends an `X-Internal-Secret` header
+and awaits only the ack (bounded by a 5s timeout), never the pipeline's
+completion.
+
+## Authentication
+
+Not `createHandler` — auth is checked inline, by design: the middleware
+path would resolve the secret-bearing request to anonymous and 401 before
+the handler ran.
+
+`isDispatchAuthorized` compares the `X-Internal-Secret` header against the
+`INTERNAL_INVOKE_SECRET` environment variable. Both sides are SHA-256
+hashed before `timingSafeEqual`, so length-mismatch early-exit cannot leak
+the expected secret via timing. If `INTERNAL_INVOKE_SECRET` is unset, the
+check always fails — every dispatch gets 403 (fail closed).
+
+On success the handler fabricates a context with `SYSTEM_PRINCIPAL`
+(wildcard `*:*` machine principal), `adminDb`, the dispatching
+`account_id`, and provenance `sourceType: 'trigger'` carrying the
+`trigger_id`.
+
+## Request contract
+
+JSON body:
+
+| Field | Required | Purpose |
+|---|---|---|
+| `pipeline_id` | yes | Pipeline to run; missing → 400 |
+| `execution_id` | no | Pre-created `queued` execution row to claim |
+| `trigger_data` | no | Trigger envelope passed to stage templates |
+| `account_id` | no | Account scope for the fabricated context |
+| `trigger_id` | no | Recorded in principal provenance |
+
+Malformed JSON → 400 `Invalid JSON body`.
+
+## Response contract
+
+- `200` — `{ ok, execution_id, status }` where `ok` is true only when the
+  run finished `completed`. (In practice Netlify answers background
+  invocations with 202 to the dispatcher; the JSON body matters to
+  `netlify functions:invoke` and logs.)
+- `400` — `{ error: 'Invalid JSON body' }` or
+  `{ error: 'pipeline_id is required' }`.
+- `403` — `{ error: 'Forbidden — invalid internal secret' }`.
+- `500` — `{ error, execution_id }` when `runPipeline` throws (missing or
+  inactive pipeline, claim failure, stage abort).
+
+## Side effects
+
+- On entry, `sweepStaleExecutions()` runs fire-and-forget — fails
+  `running`/`pending`/`queued` execution rows untouched for over 10
+  minutes.
+- `runPipeline` claims the `queued` execution row (or inserts one with the
+  same id when the claim finds nothing), executes the pipeline stages, and
+  writes terminal status, stage results, and `duration_ms` back to
+  `pipeline_executions`. Whatever the stages do — record writes, outbound
+  HTTP, embeddings, notifications — happens here, outside the triggering
+  request's process.
+
+## Errors
+
+- Missing/invalid secret → 403.
+- Missing `pipeline_id` or unparseable body → 400.
+- `Pipeline not found or inactive`, claim/insert failures, and stage
+  errors → 500 with the thrown message. Stage-level failures are normally
+  captured on the execution row rather than thrown, unless the stage
+  aborts the run.
+
+## Agent notes
+
+- Duplicate-delivery safety lives in `runPipeline`: it only claims rows
+  still `status = 'queued'`; when the claim matches nothing it inserts a
+  row with the same `execution_id`, so a redelivered dispatch dies on the
+  primary-key conflict instead of running the pipeline twice
+  (`.framework/functions/_shared/pipeline-runner.ts`).
+- If `INTERNAL_INVOKE_SECRET` is not set in the environment, trigger
+  dispatch is a silent no-op — triggers still insert `queued` rows but the
+  POST to this function 403s, and the sweeper eventually marks those rows
+  `failed`.
+- The timing-safe secret check duplicates
+  `isInternalInvokeAuthorized` in `.framework/functions/_shared/principal.ts`;
+  keep the two implementations in sync if either changes.
+- Do not call this endpoint from client code. It exists for the trigger
+  engine; manual pipeline runs go through `runPipeline` callers (CLI,
+  timers, `system-cron`) or the `pipelines` API.

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

@@ -0,0 +1,136 @@
+---
+title: pipelines
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/pipelines.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/public/_redirects
+---
+
+# pipelines
+
+## What it does
+
+CRUD plus `toggle`, `by-trigger` lookup, and `executions` listing over
+`public.pipelines` — the config rows that define a `trigger_type` and an
+ordered `stages` array. **This function manages config only**: pipeline
+execution is done by `.framework/functions/_shared/pipeline-runner.ts`
+(`runPipeline`), invoked by `system-cron` (due timers), by
+`pipeline-runner-background` (trigger dispatches), or by the
+`generate_embeddings`/kb stage handlers — and run bookkeeping lives in
+`public.pipeline_executions` via the sibling `pipeline-executions`
+function. See [Automation](../../concepts/automation.md).
+
+## Route and methods
+
+`/.netlify/functions/pipelines`, reachable as `/api/pipelines` (`/api/*`
+→ `/.netlify/functions/:splat`, `.framework/public/_redirects`).
+Dispatch is by `?action=` + method:
+
+| Call | Handler |
+|---|---|
+| `GET /api/pipelines` | `list` |
+| `GET /api/pipelines?id=<uuid>` | `get` |
+| `GET /api/pipelines?action=by-trigger&trigger_type=<t>` | `listByTrigger` |
+| `GET /api/pipelines?action=executions&pipeline_id=<uuid>` | `getExecutions` |
+| `POST /api/pipelines` | `create` |
+| `POST /api/pipelines?action=toggle` | `toggle` |
+| `PATCH /api/pipelines` (`id` in body or query) | `update` |
+| `DELETE /api/pipelines?id=<uuid>` | `remove` |
+
+A matched action with the wrong method falls through to
+`Invalid action or method` — e.g. `POST ?action=executions`.
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list`/`listByTrigger`/`create`/`update`/`toggle` require
+  `ctx.accountId` (or person+account context).
+- No role gate — system admins use `adminDb`, other humans use
+  JWT-scoped `ctx.db` (RLS); machines run service-role.
+- Reads are sanitized: non-admins get `{ id }` per row (pipeline rows
+  carry no `design_schema`). `getExecutions` rows are returned
+  **unsanitized**.
+
+## Request contract
+
+**list** (query): `app_id`. `include_inactive` is destructured but
+**never applied** — `list` always returns all pipelines including
+inactive ones (only `listByTrigger` honors it). Ordered by `name`.
+
+**listByTrigger** (query): `trigger_type` required; `app_id`,
+`include_inactive` (`'true'`) optional.
+
+**get** (query): `id`.
+
+**getExecutions** (query): `pipeline_id` required; `limit` (default 50),
+`offset` — reads `public.pipeline_executions` ordered `created_at` desc.
+
+**create** (body): `name`, `trigger_type`, `stages` required. Optional:
+`app_id`, `description`, `config` `{}`, `metadata` `{}`.
+`account_id`/`created_by` stamped. (`trigger_type` and `stages` were
+added by `.framework/migrations/020_schema_reconciliation.sql`.)
+
+**update** (`id` in body or query + body): named fields only — `name`,
+`description`, `config`, `stages`, `metadata`, `trigger_type`,
+`is_active`, `app_id`.
+
+**toggle** (body): `id` and `is_active` **both required** — unlike the
+`timers`/`triggers` toggles, this sets an explicit target state.
+
+**remove** (query): `id` — **hard delete**.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope. `list`/`listByTrigger`/
+`get`/`create`/`update`/`toggle` → sanitized row(s); `getExecutions` →
+raw `pipeline_executions` array; `remove` → `{ success: true }`.
+
+## Side effects
+
+- `emitLog` writes `pipeline.created` / `.updated` / `.toggled` /
+  `.deleted` audit rows to `public.logs`.
+- `is_active = false` stops the pipeline at dispatch time —
+  `runPipeline` throws when the pipeline is missing or inactive, so
+  queued dispatches fail rather than queue silently.
+- No execution side effects: creating/updating a pipeline does not
+  enqueue anything. Enqueue paths are triggers (event → dispatch),
+  timers (cron → `runPipeline`), and other pipelines' `run_pipeline`
+  stages.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| `by-trigger` without `trigger_type` | 500 | `trigger_type is required` |
+| No account context | 500 | `Account context required` |
+| Missing create fields | 500 | `name, trigger_type, and stages are required` |
+| Missing toggle fields | 500 | `Pipeline ID and is_active are required` |
+| Missing `id` | 500 | `Pipeline ID is required` |
+| Missing row | 500 | `Pipeline not found` |
+| `executions` without `pipeline_id` | 500 | `Pipeline ID is required` |
+| Bad action/method | 500 | `Invalid action or method` |
+
+## Agent notes
+
+- `stages` is a free-form JSON array — nothing here validates stage
+  `stage_type`/`config`; unknown stage types fail at run time inside
+  `runPipeline`, not at write time. Author against the stage handler set
+  in `.framework/functions/_shared/pipeline-runner.ts`.
+- `trigger_type` is a coarse grouping used by `listByTrigger`; actual
+  event→pipeline matching is on `triggers.event_type`, a different
+  column on a different table.
+- `remove` hard-deletes the pipeline row — `pipeline_executions`
+  history is not cascaded or checked, so deleting a pipeline orphans its
+  run records.
+- `toggle` differs from siblings: `timers.toggle`/`triggers.toggle`
+  flip the current value; `pipelines.toggle` requires the target
+  `is_active` in the body.

package/.framework/src/instructions/reference/functions/prompt-configs.md

@@ -0,0 +1,121 @@
+---
+title: prompt-configs
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/prompt-configs.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/public/_redirects
+---
+
+# prompt-configs
+
+## What it does
+
+CRUD over `public.prompt_configs` — reusable prompt/model
+configurations (`system_prompt`, `context_template`, `model`,
+temperature/token limits, escalation and output bindings,
+`knowledge_sources`, `available_tools`) that agents resolve at run time
+(see [AI and prompts](../../concepts/ai-and-prompts.md)).
+
+## Route and methods
+
+`/.netlify/functions/prompt-configs`, reachable as
+`/api/prompt-configs` (`/api/*` → `/.netlify/functions/:splat`,
+`.framework/public/_redirects`). `?action=` is **ignored** — the
+dispatcher has only a `default` branch keyed on method:
+
+| Call | Handler |
+|---|---|
+| `GET /api/prompt-configs` | `list` |
+| `GET /api/prompt-configs?id=<uuid>` | `get` |
+| `POST /api/prompt-configs` | `create` |
+| `PATCH /api/prompt-configs` (`id` in body or query) | `update` |
+| `DELETE /api/prompt-configs?id=<uuid>` | `remove` |
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list`/`create` additionally require `ctx.accountId` (`Account context
+  required`).
+- There is **no role check** in this file. System admins use `adminDb`;
+  everyone else uses `ctx.db` — JWT-scoped (RLS) for humans, service
+  role for machine principals. Non-admin row access is whatever RLS
+  allows, and returned rows are sanitized to `{ id }` (prompt-config
+  rows carry no `design_schema`).
+
+## Request contract
+
+**list** (query): `model`, `is_active` (`'true'`/`'false'`), `limit`
+(default 100), `offset` (default 0). Ordered by `name`.
+
+**get** (query): `id`.
+
+**create** (body): `name`, `slug` required. Optional with defaults:
+`app_id` `null`, `description`/`system_prompt`/`context_template`
+`null`, `model` `'gpt-4o'`, `temperature` `0.7`, `max_tokens` `4000`,
+`is_multi_turn` `true`, `max_history_messages` `20`,
+`confidence_threshold`/`escalation_action`/`escalation_target`/
+`output_mode`/`output_field` `null`, `requires_review` `false`,
+`knowledge_sources` `[]`, `available_tools` `[]`, `tool_constraints`
+`{}`, `metadata` `{}`. `account_id` is stamped from context.
+
+**update** (`id` in body or query + body): allowlist only — `name`,
+`slug`, `description`, `app_id`, `system_prompt`, `context_template`,
+`model`, `temperature`, `max_tokens`, `is_multi_turn`,
+`max_history_messages`, `confidence_threshold`, `escalation_action`,
+`escalation_target`, `output_mode`, `output_field`, `requires_review`,
+`knowledge_sources`, `available_tools`, `tool_constraints`, `metadata`,
+`is_active`. Unknown keys are ignored; `updated_at` is stamped.
+
+**remove** (query): `id` — **hard delete**.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list`/`get`/`create`/`update` → row(s) passed through
+  `sanitizeRecordData`: full row for system admins, `{ id }` for
+  non-admins (first-surface path, no `design_schema` on the row).
+- `remove` → `{ success: true }`.
+
+## Side effects
+
+- `create` inserts into `public.prompt_configs` with the caller's
+  `account_id`.
+- `remove` issues a real `DELETE` — unlike `types`/`apps`/`roles`/
+  `integrations`, deletion here is permanent.
+- `emitLog` writes `prompt_config.created` / `.updated` / `.deleted`
+  audit rows to `public.logs`.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No account context (list, create) | 500 | `Account context required` |
+| Missing create fields | 500 | `name and slug are required` |
+| Missing `id` | 500 | `Config ID is required` |
+| Row missing on delete | 500 | `Prompt config not found` |
+| Unmatched method | 500 | `Invalid action or method` |
+
+Validation failures surface as HTTP 500 — thrown `Error`s without a
+`statusCode` map to 500 in the shared error path.
+
+## Agent notes
+
+- `?action=get&id=…` works only by accident — every action value lands
+  in the `default` branch. Don't rely on action names here; dispatch is
+  method + `id` presence.
+- `remove` is a hard delete; there is no `is_active` restore path.
+  Prefer `PATCH { is_active: false }` if reversibility matters.
+- Create stamps `account_id` from the caller's context — there is no
+  way to create a config for another account through this endpoint.
+- Consumers resolve configs at run time by `prompt_config_id` stored on
+  threads/agents, not through this endpoint; this function is pure
+  config management.

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

@@ -0,0 +1,121 @@
+---
+title: roles
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/roles.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/009_roles_slug_unique.sql
+  - .framework/public/_redirects
+---
+
+# roles
+
+## What it does
+
+CRUD over `public.roles` — role definitions (slug, `permissions` JSON,
+`is_system`, `is_protected`) that principals carry and the permission
+engine matches against `design_schema.record_permissions`.
+
+## Route and methods
+
+`/.netlify/functions/roles`, reachable as `/api/roles` (`/api/*` →
+`/.netlify/functions/:splat`, `.framework/public/_redirects`). Dispatch
+is by HTTP method only (`?action=` is ignored):
+
+| Call | Handler |
+|---|---|
+| `GET /api/roles` | `list` |
+| `GET /api/roles?id=<uuid>` | `get` |
+| `POST /api/roles` | `create` |
+| `PATCH /api/roles` (`id` in **body**) | `update` |
+| `DELETE /api/roles` (`id` in **body**) | `remove` |
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `create` requires `system_admin`, or a `canCreate` grant from
+  `resolveFirstSurfacePermissions(..., 'role', 'create')`. Creating the
+  `system_admin` slug itself always requires `system_admin`.
+- `update`/`remove` have no explicit role gate — writes go through
+  `adminDb` for system admins and `ctx.db` (JWT-scoped, RLS) for other
+  humans, so a non-admin's update fails at the database as
+  `Role not found or access denied`.
+- `list`/`get` are readable by any authenticated principal.
+
+## Request contract
+
+**list** (query): `app_id` (`'null'` filters to global roles),
+`is_system` (`'true'`/`'false'`), `limit` (default 50), `offset`
+(default 0). Active rows only, ordered `is_system` desc then `name`,
+joining `app:apps(id, slug, name)`.
+
+**get** (query): `id` — active rows only.
+
+**create** (body): `slug`, `name` required. Optional: `app_id`,
+`description`, `permissions` (default `{}`), `is_system` (default
+`false`). `is_active: true` is forced.
+
+**update** (body): `id` plus any subset of role columns — **no field
+allowlist**; every key except `id` is written plus `updated_at`, after
+`validateUpdatePermissions(ctx, updates, current, 'role')` passes.
+
+**remove** (body): `id` — soft delete (`is_active = false`).
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list` → array of role rows; `get`/`create`/`update`/`remove` → single
+  row.
+- System admins get raw rows. Other principals get `sanitizeRecordData`
+  output — role records carry no `design_schema`, so non-admin reads
+  collapse to `{ id }` (and `list` returns an array of `{ id }`
+  objects). Row-level access for humans is additionally bounded by RLS
+  on `ctx.db`.
+
+## Side effects
+
+- `create` inserts into `public.roles` after a duplicate-slug pre-check
+  scoped to `slug` + `app_id` (or `app_id IS NULL` for global roles).
+- `remove` is a soft delete; `update`/`remove` stamp `updated_at`.
+- `emitLog` writes `role.created` / `role.updated` / `role.deleted`
+  audit rows to `public.logs` with before/after payloads.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing create fields | 500 | `slug and name are required` |
+| Non-admin creating `system_admin` | 500 | `system_admin role can only be created by system administrators` |
+| Non-admin without create grant | 500 | `Insufficient permissions to create roles` |
+| Duplicate slug for app scope | 500 | `Role slug already exists for this app` |
+| Missing/inaccessible row | 500 | `Role not found or access denied` |
+| Missing `id` | 500 | `Role ID is required` |
+| 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
+
+- `update` and `remove` read `id` from the **body** only — a
+  `?id=` query param is not consulted (unlike most sibling functions).
+- The pre-check scopes slug uniqueness to `app_id`, but the database
+  enforces a **global** unique index on `roles(slug)`
+  (`roles_slug_key`, `.framework/migrations/009_roles_slug_unique.sql`)
+  — a slug already used by another app passes the pre-check then fails
+  the insert. The pre-check also ignores `is_active`, so soft-deleted
+  slugs still conflict.
+- `update` accepts arbitrary columns (no allowlist): `slug`,
+  `is_system`, `is_protected`, `permissions` can all be rewritten by a
+  caller that passes `validateUpdatePermissions`.
+- Role `permissions` is a free-form JSON column — the grant semantics
+  live in `design_schema.record_permissions` matching on role **slug**,
+  not in this table.

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

@@ -0,0 +1,140 @@
+---
+title: security
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/security.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/audit.ts
+  - .framework/public/_redirects
+---
+
+# security
+
+## What it does
+
+Security-admin console API: aggregates abuse signals into a
+"flagged accounts" report, bans/unbans people across three enforcement
+layers (the `security_blocklist` table, Supabase auth ban, and the Netlify
+edge firewall), and manages blocklist entries directly.
+
+## Route and methods
+
+`/.netlify/functions/security`, reachable as `/api/security` (`/api/*` →
+`/.netlify/functions/:splat`). No method check — the action comes from
+`?action=` or `body.action`:
+
+| `action` | Purpose |
+|---|---|
+| `flagged_accounts` | 30-day rollup of security signals per person/account |
+| `ban_user` | Blocklist + Supabase ban + edge IP deny |
+| `unban_user` | Revoke blocklist rows + lift Supabase ban + remove edge rule |
+| `blocklist` | List `security_blocklist` rows (latest 500) |
+| `blocklist_add` | Upsert a blocklist entry |
+| `blocklist_revoke` | Stamp `revoked_at` on entries |
+
+Unknown action → `Unknown security action: <action>` (HTTP 400).
+
+## Authentication
+
+Standard `createHandler` plus `requireSystemContextWithAudit` — only
+`system_admin` principals (human `system_admin` role, `*:*` machine key,
+or internal secret) get in; anonymous → 401. All DB access uses `adminDb`.
+
+## Request contract
+
+**`flagged_accounts`** — no parameters. Scans `logs` for `span_name` in
+`security.rate_limit_exceeded`, `security.injection_detected`,
+`security.registration_blocked` over the last 30 days (limit 500), buckets
+by `person_id` (falling back to account), and joins `people`, `accounts`,
+and active blocklist rows.
+
+**`ban_user`** (body): at least one of `person_id`, `email`, `ip`
+required. Optional: `reason`, `block_ip` (default `true`), `block_email`
+(default `true`).
+
+**`unban_user`** (body): `person_id` required.
+
+**`blocklist`** — no parameters.
+
+**`blocklist_add`** (body): `type` ∈ `ip | email | email_domain |
+person_id | account_id` and `value` required; optional `severity`
+(default `'hard'`), `reason`, `expires_at`. Email and email-domain values
+are lowercased.
+
+**`blocklist_revoke`** (body): `id` *or* (`type`, `value`).
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `flagged_accounts` → `{ rows: [...] }`, each row
+  `{ person_id, email, account_id, account_name, last_ip, last_country,
+  person_status, signals, kinds, patterns, last_seen_at, banned }`
+  sorted by signal count descending. `banned` is true when any matching
+  person/email/IP/account blocklist entry is active.
+- `ban_user` → `{ ok: true, person_id, email, ip, layers }` where `layers`
+  reports `blocklist` / `auth` / `edge` as `applied`, `skipped`, or
+  `error: <msg>` per layer.
+- `unban_user` → `{ ok: true, person_id, layers }`.
+- `blocklist` → `{ rows: [...] }`.
+- `blocklist_add` → `{ ok: true }`; `blocklist_revoke` → `{ ok: true,
+  revoked: <n> }`.
+
+## Side effects
+
+- `security_blocklist` upserts keyed on `(type, value)` with
+  `banned_by`, `severity`, `reason`, `expires_at`; revoke stamps
+  `revoked_at` (rows are never deleted).
+- `ban_user`/`unban_user` call `auth.admin.updateUserById` with
+  `ban_duration: '876600h'` (~100 years) / `'none'` when the person has an
+  `auth_uid`.
+- **Netlify edge sync**: when `NETLIFY_ACCESS_TOKEN` + `NETLIFY_SITE_ID`
+  are set, IP entries are added to/removed from a managed
+  `spine-security:blocklist` deny rule on the site's firewall ruleset.
+  Without those env vars the edge layer reports `skipped`. Failures are
+  reported in `layers.edge`, not thrown.
+- `emitAudit` writes `security.user_banned`, `security.user_unbanned`,
+  `security.blocklist_add`, `security.blocklist_revoked` audit rows.
+- The blocklist is enforced elsewhere: `isBlockedRequest`/`isBlockedIp`
+  in the request middleware and `checkRegistrationBlocklist` during
+  registration read `security_blocklist` — this endpoint only writes it.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Unknown action | 400 | `Unknown security action: <action>` |
+| Missing ban target | 500 | `person_id, email, or ip is required` |
+| Person not found | 500 | `Person not found: <id>` |
+| Missing blocklist fields | 500 | `type and value are required` / `id or (type, value) is required` |
+| Invalid `type` | 500 | `invalid type: <type>` |
+| Blocklist write failures | 500 | `security_blocklist upsert failed: …` etc. |
+
+The system-admin denial is returned as the handler result, so it lands
+inside `data` (a `{ statusCode, headers, body }` object) with HTTP 200 —
+not as a real 403. See "Agent notes".
+
+## Agent notes
+
+- Banning by bare `email` works even when no `people` row exists — the
+  email/domain still lands on the blocklist and blocks future
+  registrations via `checkRegistrationBlocklist`.
+- `ban_user` also blocklists the person's whole `account_id` — banning a
+  person can lock out their entire account. Check `layers` in the
+  response to confirm what was applied.
+- `unban_user` revokes only the rows matching `person_id`, the person's
+  current email, and their current IP — the `account_id` row written by
+  `ban_user` is **not** revoked, and neither are manually added
+  `email_domain` entries. Revoke those separately via `blocklist_revoke`.
+- Per-layer results mean "success" is conditional: `layers.edge:
+  'skipped'` just means Netlify env vars are absent, while
+  `layers.auth: 'skipped'` means the person has no `auth_uid` (e.g. an
+  unregistered invite stub).
+- Denial quirk: a non-system-admin caller gets HTTP 200 with the denial
+  response object nested under `data`, because
+  `requireSystemContextWithAudit(ctx)` returns a response-shaped value
+  that the outer envelope wraps. Check `data.statusCode === 403` rather
+  than the HTTP status.