spine-framework 0.4.4 → 0.5.0-rc.4

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

@@ -0,0 +1,78 @@
+---
+title: Pipelines
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/pipelines.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/pipeline-executions.ts
+  - .framework/src/pages/admin/PipelinesPage.tsx
+  - .framework/src/pages/admin/PipelineDetailPage.tsx
+  - .framework/migrations/053_builtin_action_seeds.sql
+---
+
+## What this is for
+
+A **pipeline** is a multi-step workflow run by the pipeline runner. It can be triggered manually, on a schedule (via a timer), by a webhook, or by an event (via a trigger). This page controls pipeline metadata, trigger type, and the JSON `stages` the runner executes.
+
+## Fields and settings
+
+- **Name** — string. Display name; missing name prevents saving.
+- **Trigger Type** — select: `manual` (run by button), `scheduled` (invoked by a timer), `webhook` (HTTP call), `event` (Spine trigger event). Determines what causes a run.
+- **Active** — checkbox. Inactive pipelines never run, regardless of trigger.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Description** — string, optional.
+- **Config (JSON)** — free-form runtime configuration passed to the runner.
+- **Stages (JSON)** — required **array** of step definitions executed in order by the runner. Each stage is `{ "stage_type": "<action slug>", "config": {...}, "continue_on_error": false }` — `stage_type` is looked up in `public.actions` (`is_active`) at run time; an unknown slug fails the run with "Action not found for stage type".
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- The runner executes `stages` in array order; the JSON is the source of truth — there is no visual step editor. Stage config can embed `{{trigger.*}}` and `{{record.*}}` placeholders, resolved recursively at run time (`record` = the entity row that fired the event).
+- A failed stage aborts the run unless the stage sets `continue_on_error: true`.
+- Triggers and timers reference pipelines by ID. Changing `trigger_type` does not rewire existing triggers/timers — relink them separately.
+- `scheduled` without a linked timer, or `event` without a matching trigger, means the pipeline never fires.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Notify on create",
+  "trigger_type": "event",
+  "is_active": true,
+  "stages": [
+    {
+      "stage_type": "send_notification",
+      "config": {
+        "recipients": ["role:admin"],
+        "message": "Record {{record.id}} created"
+      }
+    }
+  ]
+}
+```
+
+## Full configuration
+
+Multi-stage pipelines compose the seeded built-in action slugs — `update_item`, `create_record`, `http_request`, `send_notification`, `run_pipeline`, `search_knowledge`, `query_items`, `agent_inference`, `generate_embeddings`, `revoke_embeddings`, `create_interaction` — with `config` carrying shared settings (batch sizes, model names, endpoints) and `metadata` carrying ownership/version notes. Each stage's own `config` is merged over the action row's defaults.
+
+## Example
+
+A support app ships an `auto_embed_on_publish` pipeline (`trigger_type: "event"`): stage 1 fetches the published record via `admin-data`, stage 2 calls an AI agent to generate the embedding, stage 3 writes it back. Two apps can each own a same-named pipeline — the **App** column disambiguates them in the list.
+
+## Core files
+
+- `.framework/functions/pipelines.ts` — API
+- `.framework/functions/pipeline-runner-background.ts` — background executor
+- `.framework/functions/pipeline-executions.ts` — run history (`observability/executions`)
+- `.framework/src/pages/admin/PipelinesPage.tsx` / `PipelineDetailPage.tsx` — admin UI
+- Tables: `public.pipelines`, `public.pipeline_executions`
+
+## Agent notes
+
+- "Runs today" and "last run" come from `pipeline_executions` — a pipeline with no executions shows `Never`.
+- Stages must be a JSON **array**; a pasted object or string is the most common save-time mistake.
+- The runner also implements `send_email`, `kb_ingest`, and `kb_revoke` handlers, but no `actions` rows are seeded for them — a stage using those slugs throws "Action not found" until you insert a matching `public.actions` row yourself.
+- Activating/pausing is `is_active` — a paused pipeline keeps its triggers but they no-op.

package/.framework/src/instructions/prompts.md

@@ -0,0 +1,95 @@
+---
+title: Prompt Configs
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/prompt-configs.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/src/pages/admin/PromptConfigsPage.tsx
+  - .framework/src/pages/admin/PromptConfigDetailPage.tsx
+---
+
+## What this is for
+
+A **prompt config** stores the prompt body, model settings, escalation rules, knowledge sources, available tools, and metadata that AI agents and chat interfaces use at runtime. Callers select a config by slug.
+
+## Fields and settings
+
+- **Name** *(required)* — display and lookup name.
+- **Slug** *(required)* — unique key callers use to select this config.
+- **Description** — optional purpose note.
+- **App ID** — optional owning app.
+- **System Prompt** — base system instructions (composes with the agent's own `system_prompt` at run time).
+- **Context Template** — the prompt body. The agent runner substitutes only `{{user_message}}` and `{{conversation_history}}`; any other `{{placeholder}}` is left literal in the rendered prompt.
+- **Model** — default `gpt-4o`. The model used for this prompt.
+- **Temperature** — default `0.7`. `0` = deterministic; higher = more random.
+- **Max Tokens** — default `4000`. Response token limit.
+- **Is Multi Turn** — default `true`. Whether conversation history is included.
+- **Max History Messages** — default `20`. Prior messages to include when multi-turn.
+- **Confidence Threshold** — optional minimum confidence before acting.
+- **Escalation Action / Target** — where to route low-confidence results.
+- **Output Mode / Field** — how and where the model output is emitted.
+- **Requires Review** — default `false`. Outputs need human review before use.
+- **Knowledge Sources (JSON array)** — data sources the prompt can draw from.
+- **Available Tools (JSON array)** — tool definitions the prompt may invoke.
+- **Tool Constraints (JSON object)** — rules restricting tool use.
+- **Metadata (JSON object)** — extra structured data.
+- **Active** — default `true`. Inactive configs are not returned to callers.
+
+**Downstream effects**
+
+- Agents and pipelines resolve prompt configs by slug or by ID (`thread.data.prompt_config_id` → `agent.metadata.default_prompt_config_id`) — a missing or inactive config breaks those calls.
+- `requires_review` + `escalation_*` define the human-in-the-loop path; without an escalation target, low-confidence output is just flagged.
+- JSON fields must be valid and correctly shaped (arrays for sources/tools, objects for constraints/metadata).
+
+## Minimal configuration
+
+```json
+{
+  "name": "Ticket reply draft",
+  "slug": "ticket-reply-draft",
+  "context_template": "Draft a reply to this message: {{user_message}}",
+  "model": "gpt-4o",
+  "is_active": true
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Ticket triage",
+  "slug": "ticket-triage",
+  "system_prompt": "You classify support tickets.",
+  "context_template": "Message: {{user_message}}\nHistory: {{conversation_history}}",
+  "model": "gpt-4o",
+  "temperature": 0.2,
+  "max_tokens": 1500,
+  "confidence_threshold": 0.75,
+  "escalation_action": "assign",
+  "escalation_target": "support-manager",
+  "requires_review": true,
+  "knowledge_sources": [{ "type": "kb", "slug": "support-kb" }],
+  "available_tools": ["search_kb", "set_field"],
+  "tool_constraints": { "max_calls": 3 },
+  "is_active": true
+}
+```
+
+## Example
+
+A support app ships `ticket-triage` (low temperature, tools constrained to `search_kb` + `set_field`, `requires_review`) and `customer-chat` (multi-turn, `max_history_messages: 30`, `output_mode` streaming). The triage pipeline resolves `ticket-triage` by slug for every new ticket.
+
+## Core files
+
+- `.framework/functions/prompt-configs.ts` — API
+- `.framework/src/pages/admin/PromptConfigsPage.tsx` / `PromptConfigDetailPage.tsx` — admin UI
+- Table: `public.prompt_configs`
+
+## Agent notes
+
+- The `is_default`/`prompt_type`/`category` columns do **not** exist — the dead UI for them was removed (F-013); use `is_system` and `output_mode`.
+- Pair with an `ai_agents` record: the agent holds model/behavior, this config holds the prompt text.
+- Keep templates small and pass data through placeholders — large embedded blobs defeat versioning.

package/.framework/src/instructions/reference/api/admin-data.md

@@ -0,0 +1,162 @@
+---
+title: admin-data API
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/src/lib/api.ts
+  - .framework/src/hooks/useEntityRecord.ts
+---
+
+# `admin-data` API
+
+`POST|GET|PATCH|DELETE /api/admin-data` is the single generic CRUD endpoint
+custom apps use for all runtime records. It resolves types, evaluates the
+record's stamped `design_schema` permissions, stamps schemas on write,
+soft-deletes, and fires triggers. Custom apps must route record CRUD through
+it rather than shipping their own record functions — the shared permission,
+type-resolution, audit, and trigger logic lives here.
+
+Handler: `.framework/functions/admin-data.ts` via `createHandler`, so every
+request is authenticated and wrapped in the standard envelope — see
+[Authentication](auth.md) and [Errors and Envelopes](errors-and-envelopes.md).
+
+## Request model
+
+Action and entity come from the **query string**; record fields come from the
+JSON body (writes) or additional query params (reads). With no `action`, the
+HTTP method picks the verb (`GET`+`id` → get, `GET` → list, `POST` → create,
+`PATCH` → update, `DELETE` → remove).
+
+| Action | Method | Params |
+|---|---|---|
+| `list` | GET | `entity` (required), `search`, `type_slug`, `type_slugs` (csv), `sort_field` (default `created_at`), `sort_direction` (`asc`/`desc`, default `desc`), `limit` (default 50), `offset`, `view`, `flag_only`, `exclude_flag`, plus any other `key=value` as `eq` filters (`is_active`/`is_verified`/`is_primary` coerce `'true'` → boolean) |
+| `get` | GET | `entity`, `id`, `view`, `lineage=0` (items only — skips lineage attach) |
+| `stats` | GET | `entity` → `{entity, count}` |
+| `create` | POST | `entity` (query or body), `type_slug` **or** `type_id` (required for non-raw entities), record fields |
+| `update` | PATCH | `entity`, `id`, record fields (partial) |
+| `remove` | DELETE | `entity`, `id`, `soft` (default `'true'`) |
+
+Valid entities: `accounts`, `people`, `items`, `threads`, `messages`,
+`links`, `attachments`, `watchers`, `item_progress`, `logs`, `test_runs`,
+`observability`, `test_cases`, `types`, `link_types`, `ai_agents`,
+`prompt_configs`.
+
+`logs`, `test_runs`, `observability`, `test_cases` are **raw entities**:
+create takes a per-entity field allowlist, requires specific fields
+(`logs`: `level`+`message`; `test_runs`: `suite`; `observability`:
+`metric_name`+`metric_value`; `test_cases`: `slug`+`name`), and needs no
+`type_id`.
+
+## Response shapes
+
+All responses use the standard envelope `{data, error, meta:{requestId,
+duration}}`. `data` is:
+
+- `list` → array of sanitized records, or `{data, schema, view}` when
+  `view`+`type_slug` are passed and the type's `design_schema` resolves
+- `get` → the sanitized record (+`parents`/`children`/`type_slug` lineage on
+  `items` unless `lineage=0`), or `{data, schema, view}` when `view` is
+  passed and the record carries `design_schema`
+- `create`/`update` → the sanitized record
+- `remove` → `{deleted: true, soft: true, data: <record>}` on soft delete;
+  `{deleted: true, soft: false}` on hard delete
+- `stats` → `{entity, count}`
+
+Sanitization applies `design_schema.fields.*.permissions`: fields the
+principal cannot read are stripped before the row is returned.
+
+## Permission evaluation order
+
+1. `createHandler` resolves the principal (401 if anonymous).
+2. `create` → `resolveFirstSurfacePermissions(personId, accountId,
+   typeSlug, 'create', designSchema)`; machine principals with `*:*` scope
+   bypass. Denied → 403.
+3. `update` → `validateFirstSurfaceUpdatePermissions` on the **existing
+   record's** stamped `design_schema` (no `record_permissions` → deny); each
+   `data.<field>` written requires field `write`; sanitizes values through
+   `validation_schema`. `system_admin` bypasses.
+4. `remove` → `resolveFirstSurfacePermissions(..., 'delete',
+   existing.design_schema)`; `system_admin` bypasses.
+5. `list`/`get` run under `ctx.db` (RLS-scoped for humans, `adminDb` for
+   internal/system-admin), then per-record sanitization.
+
+## Stamping & account resolution on create
+
+- `type_slug` resolves via `resolveTypeRecord(kind, slug)` (kind from
+  `ENTITY_TO_KIND`); `type_id` fetches the row and requires `is_active`.
+  One of the two is mandatory — "every runtime record must reference a type".
+- The record is stamped with the type's `design_schema` and
+  `validation_schema` at insert; a missing `record_permissions` merges
+  `{all: [create,read,update,delete]}`.
+- `account_id` in the body is a **request hint**, not a field — it sets the
+  target account when permitted; otherwise `ctx.accountId`.
+- `scope: 'platform'` types are stamped with the `spine-system` account;
+  children created via `thread_id`/`target_id`/`parent_id` inherit the
+  parent's account and scope (missing parent → 403).
+- `created_by`/`updated_by` stamp `people.id` for human principals;
+  `types`/`link_types` have no audit columns and skip the stamp.
+- `checkTypeSlugRateLimit` enforces per-type create policies from
+  `apps.config.rate_limits['<type_slug>_create']`.
+
+## Soft delete
+
+`remove` with `soft=true` (default) sets `is_active=false` + `updated_by`/
+`updated_at` on `accounts`, `people`, `items`, `threads`, `messages`,
+`watchers`, `item_progress`, `test_cases`. Any other entity — or
+`soft=false` — performs a hard `DELETE`.
+
+## Visibility projection
+
+Principals without internal-audience roles never see `visibility:
+'internal'` threads (filtered or 404), and internal `messages` are projected
+to safe step summaries via `projectMessageForCustomer` — unless the parent
+thread is `external`/`public`.
+
+## Triggers
+
+`create`/`update`/`remove` await `fireCreateTriggers` / `fireUpdateTriggers`
+/ `fireDeleteTriggers` (errors logged, never fail the request). Update
+triggers receive the previous row for field-change evaluation.
+
+## Examples
+
+```bash
+# List open items of a type
+GET /api/admin-data?action=list&entity=items&type_slug=ticket&status=open&limit=25
+
+# Get one item without lineage
+GET /api/admin-data?action=get&entity=items&id=<uuid>&lineage=0
+
+# Create a ticket (type by slug)
+POST /api/admin-data?action=create
+{"entity": "items", "type_slug": "ticket", "title": "Login broken",
+ "data": {"priority": "high"}}
+
+# Partial update — only listed data fields are written, each needs field 'write'
+PATCH /api/admin-data?action=update&entity=items&id=<uuid>
+{"data": {"priority": "low"}, "status": "resolved"}
+
+# Soft then hard delete
+DELETE /api/admin-data?action=remove&entity=items&id=<uuid>
+DELETE /api/admin-data?action=remove&entity=items&id=<uuid>&soft=false
+```
+
+Client-side, `.framework/src/hooks/useEntityRecord.ts` shows the canonical
+call pattern through `apiFetch` (`.framework/src/lib/api.ts`), which attaches
+`Authorization`, `X-Account-Id`, `traceparent`, and `x-app-id`.
+
+## Common failures
+
+| Status | Cause |
+|---|---|
+| 400 | missing/invalid `entity`, missing `id`, missing `type_id`/`type_slug` on create, missing required raw-entity fields |
+| 401 | no valid credential — see [Authentication](auth.md) |
+| 403 | record/field permission denied; parent record not found or not accessible |
+| 404-style | `get`/`update`/`remove` on an inaccessible row errors "Record not found or access denied" (RLS hides it) |

package/.framework/src/instructions/reference/api/auth.md

@@ -0,0 +1,113 @@
+---
+title: API Authentication
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/hash-api-key.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/functions/api-keys.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/src/lib/api.ts
+---
+
+# API Authentication
+
+Every function wrapped by `createHandler` resolves a `Principal` from request
+headers via `resolvePrincipal` (`.framework/functions/_shared/principal.ts`)
+before your code runs. `createPublicHandler` resolves a principal too but
+does not require one. `/api/*` paths proxy to Netlify functions via
+`/.netlify/functions/:splat` (`.framework/public/_redirects`).
+
+## Credential resolution order
+
+`resolvePrincipal` checks headers in this order — **first match wins**:
+
+1. **`X-Api-Key`** → machine principal. Looks up `api_keys` rows by
+   `key_prefix` (first 8 chars of the presented key) among `is_active` keys,
+   requires `expires_at` unset-or-future, verifies `key_hash` with a
+   timing-safe pbkdf2 compare (`.framework/functions/_shared/hash-api-key.ts`
+   — `pbkdf2$100000$sha256`), enforces per-key rate limit (`rate_limit`,
+   default 100 per `config.rate_limit_window_seconds`, default 60s) and a
+   per-IP ceiling (`rate_limit_hit` RPC, default 300/60s), then logs usage to
+   `api_key_usage_logs`. Scopes come from `key.scopes`; `*:*` grants
+   `system_admin`-equivalent reach. `key.machine_type` and `is_internal` ride
+   on the principal.
+2. **`X-Internal-Secret`** → internal invocation. Compared against
+   `INTERNAL_INVOKE_SECRET` with a timing-safe hash compare. When valid,
+   `X-Cron-Id` resolves a cron principal from `schedules` (validated by the
+   `validate_schedule_creator` RPC), `X-Trigger-Id` resolves the trigger's
+   action `default_machine_principal_id` from `api_keys`, and a bare secret
+   resolves `SYSTEM_PRINCIPAL` (`*:*` scope). **Without this secret the
+   `x-cron-id`/`x-trigger-id` headers are never honored** — they exist only
+   for trusted function-to-function calls.
+3. **`Authorization: Bearer <jwt>`** → human principal.
+   `supabase.auth.getUser` validates the JWT, `resolveInternalPersonId` maps
+   `auth.users.id` → `people.id` (auth_uid binding, then email fallback),
+   and the person's `roles.slug` becomes `principal.roles`. Results are
+   cached ~60s per token hash (max 500 entries); principals with neither
+   `account_id` nor `role_id` (mid-registration) are never cached.
+4. **Nothing** → `ANONYMOUS_PRINCIPAL` → `createHandler` returns 401.
+
+## Principal shape
+
+```ts
+interface Principal {
+  id: string                      // people.id, api_keys.id, 'system', or 'anonymous'
+  type: 'human' | 'machine'
+  accountId: string | null
+  roles?: string[]                // role slugs (humans; *:* machines get system_admin)
+  scopes?: string[]               // machine scopes, e.g. 'items:read', '*:*'
+  machineType?: 'integration' | 'service_account' | 'internal' | 'timer'
+  isInternal?: boolean
+  provenance: { sourceType: 'jwt'|'api_key'|'cron'|'trigger'|'manual'|'webhook'|'timer', ... }
+  authContext?: { jwt?: string }  // transport-only — never serialize
+}
+```
+
+`getPrincipalDb(principal)` picks the request's DB client: humans with a JWT
+get an RLS-scoped client (`getUserDb`); machines/anonymous get `adminDb`.
+
+## Scope checking
+
+`machineHasScope` honors exact `resource:action`, `resource:*`, and `*:*`
+wildcards. `admin-data` create treats machine `*:*` as authorized; elsewhere
+`isSystemAdmin` (human `system_admin` role or machine `*:*`) is the bypass.
+`humanHasRole` matches role slugs.
+
+## Client headers that matter
+
+| Header | Effect |
+|---|---|
+| `Authorization: Bearer <jwt>` | human auth |
+| `X-Api-Key: <key>` | machine auth |
+| `X-Internal-Secret: <secret>` | internal function-to-function auth (+ `X-Cron-Id`/`X-Trigger-Id`) |
+| `X-Account-Id` | carried into `ctx` for account-scoped flows (set by `apiFetch` from `setAccountId`) |
+| `X-App-Id` | app slug hint for app-scoped behavior (auto-set by `apiFetch` from the route prefix) |
+| `X-Request-Id` | propagated request id (a UUID is generated when absent/invalid) |
+| `traceparent`/`tracestate` | W3C trace context, echoed back on responses |
+
+The browser client `apiFetch` (`.framework/src/lib/api.ts`) attaches
+`Authorization`, `X-Account-Id`, `traceparent`, and `x-app-id`
+automatically.
+
+## Failure modes
+
+| Status | Cause |
+|---|---|
+| 401 `Authentication required` | no credential resolved, expired/invalid JWT (`auth.getUser` fails → anonymous), or `resolvePrincipal` threw (see below) |
+| 401 `Invalid or inactive machine principal` | unknown `key_prefix`, inactive key, expired key, or hash mismatch — thrown by `resolveMachinePrincipal` |
+| 401 `Rate limit exceeded for this API key` / `for this address` | per-key or per-IP ceilings hit — thrown as errors, surfaced via the 500-unless-statusCode path (these errors carry no `statusCode`, so check function logs when a 500 appears on auth) |
+| 401 `Invalid or inactive schedule: <id>` / `Invalid trigger: <id>` | `x-cron-id`/`x-trigger-id` resolution failed after a valid internal secret |
+| 401 `Person lookup error …` / `Person not found: <id>` | JWT verified but no `people` row exists (incomplete registration or deleted person) |
+| 403 `Access denied` | principal resolved but matched `security_blocklist` (person/account/email/IP), checked by `isBlockedRequest` — fails open when the table is absent |
+| 400 `Invalid JSON in request body` | body was present but unparseable |
+
+## Related
+
+- [Errors and Envelopes](errors-and-envelopes.md) · [admin-data](admin-data.md)
+- [API Keys](../../api-keys.md) · [Auth and API Keys](../../concepts/auth-and-api-keys.md)
+- [Environment Variables](../env-vars.md) — `INTERNAL_INVOKE_SECRET`, `SPINE_IP_RATE_LIMIT`

package/.framework/src/instructions/reference/api/errors-and-envelopes.md

@@ -0,0 +1,113 @@
+---
+title: Errors and Response Envelopes
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/rate-limit.ts
+  - .framework/functions/_shared/tracing.ts
+  - .framework/src/lib/api.ts
+---
+
+# Errors and Response Envelopes
+
+Every function wrapped by `createHandler` or `createPublicHandler`
+(`.framework/functions/_shared/middleware.ts`) returns the same envelope and
+error shape. Custom functions get this for free by returning/throwing from a
+wrapped handler — never construct raw `{statusCode, body}` responses in app
+code.
+
+## Success envelope
+
+```json
+{
+  "data": <handler return value>,
+  "error": null,
+  "meta": { "requestId": "<uuid>", "duration": <ms> }
+}
+```
+
+HTTP status is always `200` for a handler that returns normally — partial
+failures the handler swallows are invisible at the status layer, so handlers
+should throw for real failures.
+
+## Error envelope
+
+```json
+{ "data": null, "error": "<message>" }
+```
+
+Two emitters produce it:
+
+- `error(message, status)` — used for auth/blocklist/parse failures before
+  the handler runs.
+- `structuredError(err, status)` — used for anything the handler throws.
+  The thrown error's `statusCode` number becomes the HTTP status; **absent
+  `statusCode` the status is `500`**, so domain errors that should surface
+  as 4xx must set `err.statusCode` (the codebase idiom is
+  `const e: any = new Error('…'); e.statusCode = 400; throw e`).
+  Whitelisted extra fields are copied onto the body when present on the
+  error: `action`, `limit`, `retry_after` (plus `retryAfter` → `retry_after`)
+  — that is how `RateLimitError` from
+  `.framework/functions/_shared/rate-limit.ts` renders a 429 with recovery
+  metadata.
+
+## Status codes in practice
+
+| Status | When |
+|---|---|
+| 200 | success; also preflight (`cors()` returns `{message:'CORS enabled'}`) |
+| 400 | `statusCode`-tagged validation failures; unparsable JSON body (`Invalid JSON in request body`) |
+| 401 | anonymous principal on a `createHandler` endpoint (`Authentication required`); credential resolution failures (see [Authentication](auth.md)) |
+| 403 | `security_blocklist` hits (`Access denied`); `statusCode`-tagged permission failures (`Insufficient permissions …`) |
+| 429 | `RateLimitError` — body carries `action`/`limit`/`retry_after` |
+| 500 | any thrown error without `statusCode` — includes most `new Error('…')` sites |
+
+Because untagged errors map to 500, a 500 does not always mean a crash — it
+can be an intentional refusal (e.g. `Invalid action or method`, `Record not
+found`) that nobody tagged. Check `error` text and function logs.
+
+## Response headers
+
+Set by `json()` on every response:
+
+| Header | Value |
+|---|---|
+| `Content-Type` | `application/json` |
+| `Access-Control-Allow-Origin` | `SITE_URL` → `URL` → `*` (in that order) |
+| `Access-Control-Allow-Headers` | `Content-Type, Authorization, X-Account-Id, X-App-Id, X-Request-ID, X-Source, X-Log-Level, traceparent, tracestate` |
+| `Access-Control-Allow-Methods` | `GET, POST, PATCH, DELETE, OPTIONS` |
+| `X-Request-ID` | the request id (echo of a valid `X-Request-Id` input, else generated UUID) |
+| `traceparent` / `tracestate` | W3C trace context for the request span |
+
+## Request context the handler receives
+
+`ctx` (`RequestContext`) carries `principal`, `accountId`, `db` (traced,
+principal-scoped client), `requestId`, `appId` (`X-App-Id`), `query`
+(query-string params plus `method` filled from the HTTP method),
+`requestPath`, lowercased `headers`, `source`/`logLevel` (from `X-Source`/
+`X-Log-Level`), and `trace`. A `?id=` query param is copied into `body.id`
+when the body lacks it.
+
+## Observability side effects
+
+Every request emits fire-and-forget spans (`emitSpan`) for
+`request.<method>` / `request.error` / `request.blocked` /
+`request.unauthenticated` / `request.parse_error`, and `traceDb` wraps
+`ctx.db` calls into `db.*` spans. Telemetry failures never fail the request.
+
+## Client handling
+
+`apiFetch` (`.framework/src/lib/api.ts`) returns the raw `Response` — callers
+read `response.json()` and inspect `error`. A `401` invokes the registered
+`onUnauthorized` callback except on `/api/auth` and `/api/admin-data` paths.
+Debug per-request tracing is opt-in via `localStorage.spine_debug_api = '1'`.
+
+## Related
+
+- [Authentication](auth.md) — credential resolution and its failure modes
+- [admin-data](admin-data.md) — the largest consumer of this contract
+- [Shared Modules](../shared-modules.md) — `middleware.ts` internals