spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/reference/functions/item-progress.md

@@ -0,0 +1,107 @@
+---
+title: item-progress
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/item-progress.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/audit.ts
+  - .framework/public/_redirects
+---
+
+# item-progress
+
+## What it does
+
+Tracks a person's progress through a pipeline on a specific item —
+one `item_progress` row per `(person_id, item_id)` pair. Enforces
+forward-only status transitions defined by the row's type
+(`design_schema.pipeline`, default `['not_started', 'in_progress',
+'completed']`), stamps `started_at`/`completed_at`, and counts attempts.
+
+## Route and methods
+
+`/.netlify/functions/item-progress`, reachable as `/api/item-progress`
+(`/api/*` → `/.netlify/functions/:splat`). Dispatch is by method
+(`ctx.query.method`; `?method=` can override):
+
+| Call | Action |
+|---|---|
+| `GET /api/item-progress` | `list` |
+| `GET /api/item-progress?id=<uuid>` | `get` |
+| `POST /api/item-progress` | `upsert` |
+| `PATCH /api/item-progress?id=<uuid>` | `update` |
+
+Any other method → `Method <method> not supported`.
+
+## Authentication
+
+Standard `createHandler`: `x-api-key`, internal secret, or
+`Bearer <jwt>`; anonymous is rejected with 401. All table access goes
+through `ctx.db` (RLS-scoped for humans); type lookups and the
+item/person title fetches use the service role. There are no additional
+role checks.
+
+## Request contract
+
+**list** (query): `person_id`, `item_id`, `item_ids` (comma-separated),
+`status`, `limit` (default `100`), `offset` (default `0`). Only
+`is_active = true` rows, ordered `updated_at` desc.
+
+**get** (query): `id`.
+
+**upsert** (body): `person_id`, `item_id`, `account_id`, and `type_id`
+*or* `type_slug` are required. Optional: `status`, `score`, `data`
+(merged into `record.data`), `title`, `description`, `app_id`, `force`.
+
+**update** (body `id` or query `id`): partial row fields plus `force`.
+
+Transition rules: `status` may only move to the same or a later stage of
+the type's pipeline (`toIdx >= fromIdx`). Statuses not present in the
+pipeline pass unchecked. `force: true` bypasses the check. Backward moves
+without `force` throw.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list` → array of `item_progress` rows.
+- `get` → one row.
+- `upsert` → the upserted row (Postgres `ON CONFLICT (person_id, item_id)`
+  — repeat calls update the same row). Auto-fills `title`
+  (`"<item title> — <person name>"`) and `description`
+  (`"In Progress · score 90 · 2 attempts"`) when not given.
+- `update` → the updated row.
+
+## Side effects
+
+- Writes `item_progress` rows; `data.attempts` increments on each status
+  change, `data.started_at`/`data.completed_at` stamp on first entry to
+  `in_progress`/`completed`. `created_by`/`updated_by` track the principal.
+- Emits `item_progress.upserted` / `item_progress.updated` log entries via
+  `emitLog` with before/after payloads.
+- Reads `items`, `people`, `types` for title composition and pipeline
+  resolution.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing `id` | 500 | `Progress record ID is required` |
+| Missing required upsert fields | 500 | `person_id, item_id, type_id (or type_slug), and account_id are required` |
+| Backward/invalid transition | 500 | `Invalid status transition: <from> → <to>. Use force: true to override.` |
+| Row not found | 500 | `Progress record not found` |
+| Unsupported method | 500 | `Method <method> not supported` |
+
+## Agent notes
+
+- There is no delete action; to retire a progress row, `PATCH`
+  `{ "is_active": false }` (list filters it out).
+- `type_slug` is resolved with kind `item_progress` — use the progress
+  type's slug, not the item's type slug.
+- Because `data` is merged (not replaced) on both upsert and update,
+  remove a key by writing an explicit `null`, not by omitting it.
+- The unique key is `(person_id, item_id)` — one progress row per person
+  per item; concurrent upserts conflict-resolve onto the same row.

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

@@ -0,0 +1,166 @@
+---
+title: kb
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/kb.ts
+  - .framework/functions/_shared/kb.ts
+  - .framework/functions/_shared/llm.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/migrations/054_kb_ingest_lease.sql
+  - netlify.toml
+  - public/_redirects
+---
+
+# kb
+
+## What it does
+
+`kb` (`.framework/functions/kb.ts`) is the knowledge-base surface: a thin
+`?action=` dispatcher over the shared implementation in
+`.framework/functions/_shared/kb.ts`. It maintains `embeddings` vector rows
+for published knowledge items and serves semantic search over them, gated by
+the calling app's knowledge envelope.
+
+| Action | Handler | Purpose |
+|---|---|---|
+| `ingest` | `kbIngest` | Embed one `items` record's declared vector fields into `embeddings`. |
+| `revoke` | `kbRevoke` | Revoke + delete a document's embeddings and clear its ingest lease. |
+| `reindex` | `kbReindex` | Re-ingest every `published` item of a type (batched, 10 in flight). |
+| `search` | `kbSearch` | Vector search via `match_embeddings`, best-match-per-document. Default action. |
+| `publish` | `kbPublish` | PATCH `status: 'published'` through admin-data, then ingest. |
+
+## Route and methods
+
+- `/api/kb?action=<action>` — `public/_redirects` maps `/api/*` to
+  `/.netlify/functions/:splat`. The action comes from `ctx.query.action`
+  only — it must be a query parameter; the HTTP method itself is not
+  checked, and the body carries the parameters.
+- The function is configured with a 120s timeout in `netlify.toml` (reindex
+  sweeps a whole corpus).
+
+## Authentication
+
+`createHandler` resolves a principal and rejects anonymous requests with 401.
+There is no role gate on the actions themselves; authorization is enforced
+downstream:
+
+- `kbSearch` runs `resolveKnowledgeScope` — deny-by-default unless the
+  caller's app declares `config.knowledge` — and each result is passed
+  through `sanitizeRecordData` before returning.
+- `kbPublish` goes through admin-data `update` (a synthetic PATCH), so
+  field-level permissions and triggers apply.
+- `kbIngest`/`kbRevoke`/`kbReindex` operate via `adminDb` — they rely on the
+  caller being trusted to name a document; `body.account_id` on ingest lets
+  an operator ingest a record owned by another account.
+
+## Request contract
+
+`ingest`: `{ id (required, items.id), account_id? }`
+
+`revoke`: `{ id (required) }`
+
+`reindex`: `{ type_slug (required), app_id? }` — `app_id` narrows the items
+re-ingested.
+
+`search`:
+
+| Field | Default | Notes |
+|---|---|---|
+| `query` | — | Required. |
+| `type_slugs` | `[]` | The caller's pick — intersected with the app envelope; picks outside it deny the call. |
+| `sources` | `['kb']` | `'kb'` for knowledge items, `'code'` for code-chunk vectors (the `cil_*` item-type namespace). |
+| `app_id` | `null` | Post-filter on `metadata.app_id`. |
+| `vector_fields` | `[]` | Restrict to specific `metadata.vector_type` values. |
+| `limit` / `offset` | `10` / `0` | Page over best-match documents. |
+| `similarity_threshold` | `0.15` | Minimum cosine similarity. |
+| `filters` | `{}` | Post-filter on the resolved `items` row. |
+
+`publish`: `{ id (required) }`
+
+## Response contract
+
+- `ingest` → `{ ok, message, count?, in_progress? }`. `message` is one of
+  `embeddings generated`, `embeddings reused (unchanged content)`,
+  `record is not published; embeddings revoked if any`,
+  `embedding already in progress` (with `in_progress: true` — **not** a
+  success signal for stampers), or `no content to embed`.
+- `revoke` → `{ ok, message: 'embeddings revoked', count }`, or
+  `{ ok, skipped: true, message: 'document is published — embeddings
+  retained', count: 0 }` — revoke re-checks current status at execution time
+  and refuses to strip a now-published document.
+- `reindex` → `{ ok, count, errors?: [{ id, error }] }` — per-item failures
+  are collected, not fatal.
+- `search` → `{ results, count, error? }`; results are
+  `{ id, document_id, type_slug, title, snippet, app_id, similarity, status,
+  created_at, source, data }` sorted by similarity. `error` carries
+  `knowledge_denied: <reason>` when the envelope refuses.
+- `publish` → `{ record, ingest }` — the admin-data update result plus the
+  ingest result.
+
+## Side effects
+
+- `ingest`: reads the record's stamped `design_schema.functionality.kb` —
+  `vector_fields` (default `['title', 'content']`), `chunk_field` (default
+  `content`), `chunk_size` (800), `chunk_overlap` (100), `security_level`
+  (deny-by-default `internal`), `supersede_keys`. Field text is normalized
+  (rich-text HTML stripped, bare UUID tokens dropped) and hashed — a
+  `document_leases` row (migration `054`) dedupes unchanged re-embeds
+  (`reused`) and fences concurrent workers (`processing`). Prior embeddings
+  are cleared via `revoke_embeddings_for_item` + delete, chunks are embedded
+  in **one batched** `callOpenAIEmbeddings` call (`text-embedding-3-small`),
+  and new rows are inserted with `metadata.{type_slug, item_type, app_id,
+  vector_type, security_level, status}` and `approved_at` set. Older
+  `published` items sharing a `supersede_keys` value are archived with
+  `superseded_by`/`superseded_at` and their embeddings revoked.
+- `revoke`: `revoke_embeddings_for_item` RPC + embeddings row delete +
+  unconditional `document_leases` delete (warn-only on failure).
+- `reindex`: sweeps `published` items of the type in batches of 10, calling
+  `kbIngest` each — sequential ingest would exceed the function budget.
+- `publish`: admin-data PATCH sets `status: 'published'` (permissions,
+  audit, triggers run), then `kbIngest` runs immediately in the same
+  request.
+- `search`: one `callOpenAIEmbeddings` call for the query embedding plus
+  `match_embeddings` RPC per requested vector type.
+
+## Errors
+
+| Condition | Error |
+|---|---|
+| Missing inputs | `id is required` · `type_slug is required` · `query is required` |
+| Unknown record | `record not found` |
+| Unknown type | `type not found: <type_slug>` |
+| Bad action | `unknown kb action: <action>` |
+| RPC/insert failures | thrown — the lease is released with `failed` status |
+
+## Agent notes
+
+- **Ingest outcomes are tri-state.** `in_progress: true` means another
+  worker owns this content's embed — callers that stamp embedding state on
+  the record must not write success *or* failure; the owning worker's
+  completion reconciles the corpus. A fenced lease release (superseded
+  mid-flight) warns without throwing.
+- **Search is deny-by-default.** No `config.knowledge` envelope on the app →
+  `knowledge_denied`. The envelope declares `account` (self, or
+  `self_and_descendants` via `get_accessible_accounts`), `platform`
+  (spine-system account, own `sources` allowlist), and project-scoped code
+  chunks — the last only when an explicit project id list survives the
+  envelope∩pick intersection. When the app declares `required_roles`, the
+  principal must hold one (system_admin bypasses).
+- **`document_id` is polymorphic.** Regular records key `embeddings` by
+  their items UUID; code-chunk vectors key it by a `stable_id` string —
+  `kbSearch` splits the `items` lookup (`id` vs `data->>stable_id`) to
+  handle both.
+- **Pipelines don't call this endpoint.** The `kb_ingest`/`kb_revoke` stage
+  handlers lazy-import `kbIngest`/`kbRevoke` directly and resolve `item_id`
+  from trigger data; `search_knowledge` uses its own text-search path over
+  `embeddings`, not `kbSearch`.
+- `adminUpdate` is imported lazily to avoid a circular-import deadlock
+  through `pipeline-runner` — preserve that pattern if adding admin-data
+  calls.
+- See [AI agents, prompt configs, and embeddings](../../concepts/ai-and-prompts.md)
+  for how these vectors feed agent retrieval.

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

@@ -0,0 +1,141 @@
+---
+title: logs
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/logs.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/migrations/069_log_stats_window.sql
+---
+
+# logs
+
+## What it does
+
+Read/write API over the `public.logs` table — the shared audit, span, and
+event log every function writes into. Read actions cover account feeds,
+per-target and per-person histories, aggregate stats, and message search;
+the write path appends a single log row; `cleanup` prunes old rows.
+
+## Route and methods
+
+`/.netlify/functions/logs` — also `/api/logs` (`/api/*` →
+`/.netlify/functions/:splat` in `.framework/public/_redirects`; same
+rewrite in the dev proxy, `config/vite.config.ts`).
+
+Dispatch by `?action=` + HTTP method:
+
+| Call | Handler |
+|---|---|
+| `GET?action=account` | `listAccount` — account-scoped feed |
+| `GET?action=target` | `listTarget` — rows for one record |
+| `GET?action=person` | `listPerson` — rows for one person |
+| `GET?action=stats` | `getStats` — `get_log_stats` RPC |
+| `GET?action=search` | `search` — `message ILIKE` match |
+| `POST?action=cleanup` | `cleanup` — delete old rows |
+| `POST` (no action) | `log` — insert one row |
+
+Anything else throws `Invalid action or method`.
+
+## Authentication
+
+`createHandler` — any non-anonymous principal; anonymous → 401.
+
+Scope varies per action:
+
+- `listAccount` — `system_admin` principals read via `adminDb`
+  (cross-account); everyone else reads via `ctx.db` filtered to
+  `account_id`, and needs an account context.
+- `listTarget`, `listPerson`, `search`, `getStats` — always `ctx.db`
+  pinned to `ctx.accountId`; all throw `Account context required` without
+  one. Note `ctx.db` is `adminDb` for machine principals, so the
+  `account_id` filter is the only scope guard there.
+- `log`, `cleanup` — `ctx.db`, no role check inside the function.
+
+## Request contract
+
+Query parameters:
+
+- `account`: `event` (exact `span_name`), `event_type` (exact `level`),
+  `target_type` (`source_type`), `source`, `source_id`, `actor_id`
+  (`created_by`), `query` (`message ILIKE %…%`), `date_from`, `date_to`,
+  `trace_id`, `limit` (100), `offset` (0).
+  - Special case: `event=threshold.breached` returns alert-shaped rows
+    `{ id, metric, threshold_value, actual_value, created_at }` taken from
+    `metadata`, plus `total` — not the standard row mapping.
+- `target`: `target_type` + `target_id` (both required), `event_type`,
+  `limit` (100), `offset` (0).
+- `person`: `person_id` (defaults to the caller's principal id),
+  `include_system` (`'true'` to include `level='system'` rows, excluded by
+  default), `limit` (50), `offset` (0).
+- `stats`: `event_type`, `target_type`, `source`, `source_id`, `actor_id`,
+  `query`, `date_from`, `date_to` — all optional, mapped to the
+  `get_log_stats` RPC parameters.
+- `search`: `query` (required), `event_type`, `target_type`, `limit` (50),
+  `offset` (0).
+
+Body (`log` action only): `event_type` (required — written to `level`),
+`target_type`, `target_id`, `action` (written to `source`), `message`,
+`details` (written to `context`), `metadata`.
+
+Body (`cleanup`): `days_to_keep` (default 30).
+
+## Response contract
+
+Standard envelope `{ data, error, meta }`.
+
+- `account` → `{ data: [mapped rows], total }`.
+- `target` / `person` / `search` → array of mapped rows.
+- Rows are remapped by `mapLogRow`: `level → event_type`,
+  `person_id → actor_id`, `source_type → target_type`,
+  `source_id → target_id`, `source → action`, `context → details`, plus
+  `span_name`, `trace_id`, `span_id`, `parent_span_id`, `duration_ms`,
+  `outcome`, `event_category`, `kind`, `message`, `metadata`,
+  `created_at`.
+- `stats` → first `get_log_stats` row `{ total, error_count,
+  user_action_count, event_type_count, levels, sources, source_types }`,
+  or a zeroed object when the RPC returns nothing.
+- `log` → `{ log_id }`. `cleanup` → `{ deleted_count }`.
+
+## Side effects
+
+- `log` inserts one `logs` row stamped with `person_id` (caller),
+  `account_id`, and the mapped fields.
+- `cleanup` deletes `logs` rows with `created_at` older than
+  `days_to_keep` — permanently.
+- Read actions are pure queries. (The `get_log_stats` RPC is a read.)
+
+## Errors
+
+- `target_type and target_id are required`, `Person ID is required`,
+  `Search query is required`, `event_type is required` — validation.
+- `Account context required` — non-admin callers without `ctx.accountId`.
+- `Invalid action or method` — unmatched dispatch.
+- `person`/`target` use caller-scoped `ctx.db` — a `person_id` outside the
+  caller's account simply returns an empty page, not an error.
+
+## Agent notes
+
+- **`get_log_stats` defaults to a 7-day window.** When `date_from` is not
+  supplied the RPC uses `now() - interval '7 days'`
+  (`.framework/migrations/069_log_stats_window.sql`) — "all-time" stats
+  are really trailing-week stats. Pass `date_from` explicitly for longer
+  windows. (Audit finding F-037.)
+- `cleanup` has no admin check: it runs on `ctx.db`. Human JWTs get an
+  RLS-scoped client, but machine principals resolve to `adminDb` — a
+  machine call to `POST ?action=cleanup` deletes matching rows
+  **platform-wide**. Treat this action as operator-only.
+- The same `account_id`-vs-`adminDb` asymmetry applies to `listTarget`,
+  `listPerson`, `search`, and `getStats`: the `account_id` filter is a
+  query predicate, not RLS, for machine callers — but it is always
+  applied, so cross-account reads still require omitting account context,
+  which those handlers forbid.
+- `listAccount`'s `event=threshold.breached` branch returns a different
+  row shape — clients parsing log rows should branch on it.
+- Field names in the response are the *mapped* names (`event_type`,
+  `actor_id`, `target_type`), not the column names (`level`, `person_id`,
+  `source_type`) — a common source of confusion when correlating with the
+  table directly.

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

@@ -0,0 +1,105 @@
+---
+title: observability
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/observability.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/middleware.ts
+---
+
+# observability
+
+## What it does
+
+Aggregation API over `public.logs` and `public.pipeline_executions` — the
+metrics surface behind the observability dashboards: event volume, error
+rate, latency percentiles, pipeline stats, top actors, AI-support metrics,
+and a log-retention cleanup action.
+
+## Route and methods
+
+`/.netlify/functions/observability?action=<action>` — also `/api/…`
+(`/api/*` → `/.netlify/functions/:splat` in
+`.framework/public/_redirects`).
+
+Dispatch is on `action` only — there are no HTTP-method checks. Valid
+actions: `event_volume`, `error_rate`, `latency_percentiles`,
+`pipeline_stats`, `top_actors`, `ai_support_metrics`, `cleanup`.
+
+## Authentication
+
+`createHandler` — non-anonymous principal required (401 otherwise).
+
+`system_admin` principals query via `adminDb` across all accounts;
+everyone else uses `ctx.db` and the handlers additionally filter
+`account_id = ctx.accountId` — non-admins without account context get
+`Account context required`. `cleanup` separately requires
+`principal.roles` to include `system_admin`.
+
+## Request contract
+
+All inputs are query parameters:
+
+| Action | Params | Returns |
+|---|---|---|
+| `event_volume` | `from`, `to` (required ISO dates); `bucket` = `hour`\|`day` (default `hour`) | `[{ bucket, count }]` sorted ascending — counts of `logs` rows bucketed by `created_at` |
+| `error_rate` | `from`, `to` (required) | `{ total, errors, rate }` — rows with `outcome='failure'` or `level='error'` over total |
+| `latency_percentiles` | `from`, `to` (required); `source` (default `request`, matched against `span_name`) | `{ p50, p90, p95, p99 }` over positive `duration_ms` values |
+| `pipeline_stats` | `from`, `to` (required) | `[{ pipeline_id, success_count, failure_count, avg_duration_ms }]` over `pipeline_executions` (`completed`/`failed` statuses counted; avg over rows having both timestamps) |
+| `top_actors` | `from`, `to` (required); `limit` (default 5) | `[{ principal_id, event_count }]` — counts of `logs.created_by`, `anonymous` for null |
+| `ai_support_metrics` | `from`, `to` (optional; default last 30 days); requires account context | see below |
+| `cleanup` | `days` (default 30) | `{ deleted_count }` via `cleanup_old_logs` RPC; system-admin only |
+
+`ai_support_metrics` resolves the `ai_feedback_record` item type and
+reads `items` for the context account: feedback rows (attempted count,
+`customer_feedback='not_helpful'`, `kb_article_id`, `reuse_count`,
+`kb_candidate`), resolved items (`status='resolved'` with
+`data->>aim_escalation_reason='none'`), and escalations
+(`status='human_assigned'`). Response: `{ period: {from,to},
+ai_attempted, ai_resolved, human_escalations, thumbs_down_rate,
+kb_articles_created, kb_reuse_count, knowledge_gaps }`. It uses `adminDb`
+scoped to `ctx.accountId` and tolerates per-query failure via
+`Promise.allSettled` — a failed sub-query contributes zero, not an error.
+
+## Response contract
+
+Standard envelope `{ data, error, meta }`. Payloads per action are listed
+above; aggregation happens in memory inside the function (there are no
+SQL rollups for the metrics endpoints — full matching rows are selected
+then counted).
+
+## Side effects
+
+Read-only except `cleanup`, which deletes `logs` rows older than `days`
+via the `cleanup_old_logs` RPC. (`system-cron` performs the same cleanup
+automatically on the 00:00 UTC tick with a 30-day retention.)
+
+## Errors
+
+- `Account context required` — non-admin callers without `ctx.accountId`
+  (all actions), and `ai_support_metrics` for any caller.
+- `from and to dates are required` — all metric actions except
+  `ai_support_metrics` and `cleanup`.
+- `System admin required` — `cleanup` without the `system_admin` role.
+- `Unknown action: <x>. Valid actions: …` — unmatched `action`.
+
+## Agent notes
+
+- These are in-memory aggregations, not RPC rollups: `event_volume`,
+  `error_rate`, `latency_percentiles`, and `top_actors` pull every
+  matching row's columns and count locally. Wide `from`/`to` windows over
+  a busy `logs` table are proportional in cost — keep ranges tight.
+- `latency_percentiles` filters `span_name = source` (default `request`)
+  — the request spans emitted by `createHandler`. Passing `source=` for
+  other span names (e.g. `db.select`, `pipeline.run`) yields percentiles
+  for those operations.
+- `top_actors` keys on `created_by`, which is null for machine-emitted
+  spans — those collapse into `anonymous`.
+- `ai_support_metrics` depends on `ai_feedback_record` items and
+  `status='human_assigned'`/`'resolved'` conventions written by the AI
+  support flows; it returns zeros on installations without them rather
+  than erroring.

package/.framework/src/instructions/reference/functions/pipeline-executions.md

@@ -0,0 +1,132 @@
+---
+title: pipeline-executions
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/pipeline-executions.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+---
+
+# pipeline-executions
+
+## What it does
+
+CRUD and lifecycle surface for `public.pipeline_executions` — the durable
+ledger of pipeline runs. One row per run carries `pipeline_id`, `status`,
+`trigger_data`, `result`, `error_message`, `started_at`, `completed_at`, and
+`duration_ms`. The pipeline runner writes most transitions itself; this
+endpoint is how operators and the admin UI read run history and how scripts
+create, start, complete, cancel, or prune rows.
+
+## Route and methods
+
+`/.netlify/functions/pipeline-executions` — also reachable as
+`/api/pipeline-executions` (`/api/*` → `/.netlify/functions/:splat` in
+`.framework/public/_redirects`; same rewrite in the dev proxy,
+`config/vite.config.ts`).
+
+Dispatch is by `?action=` query parameter plus HTTP method (the middleware
+copies `event.httpMethod` into `ctx.query.method`):
+
+| Call | Handler |
+|---|---|
+| `GET` (no action, no `id`) | `list` |
+| `GET&id=` | `get` — single row by id |
+| `GET?action=list` | `list` |
+| `GET?action=running` | `getRunning` — `status = 'running'` rows |
+| `GET?action=stats` | `getStats` — status counts |
+| `POST` (no action) | `create` — insert a `pending` execution |
+| `POST?action=cleanup` | `cleanup` — delete old rows |
+| `PATCH?action=start` | `start` — set `running` + `started_at` |
+| `PATCH?action=complete` | `complete` — set terminal status |
+| `PATCH?action=cancel` | `cancel` — set `cancelled` |
+
+Any other action/method combination throws `Invalid action or method`.
+
+## Authentication
+
+Wrapped in `createHandler`, so the request must resolve to a non-anonymous
+principal — Bearer JWT (human), `x-api-key` (machine), or
+`x-internal-secret` (internal) per `resolvePrincipal`. Anonymous requests
+get 401 before the handler runs.
+
+System admins (`roles` contains `system_admin`) read through `adminDb`
+across all accounts. Everyone else reads through their scoped `ctx.db` and
+must have an account context — `list`, `running`, and `stats` throw
+`Account context required` without one.
+
+## Request contract
+
+Query parameters:
+
+- `id` — execution UUID. `get` requires it; the middleware also copies it
+  into `body.id` for write actions.
+- `pipeline_id` — filter for `list`, `running`, `stats`.
+- `status` — filter for `list`.
+- `date_from`, `date_to` — `created_at` bounds for `stats`.
+- `limit` (default 100), `offset` (default 0) — `list` pagination.
+
+Body fields:
+
+- `create`: `pipeline_id` (required), `trigger_data` (optional object).
+- `start` / `cancel`: `id` (required).
+- `complete`: `id` (required), `output_data`, `error_message`. A non-empty
+  `error_message` makes the final status `failed`; otherwise `completed`.
+- `cleanup`: `days_to_keep` (default 30), `status_filter` (optional) —
+  deletes rows with `created_at` older than the cutoff.
+
+## Response contract
+
+All successful returns are wrapped by the middleware in
+`{ data, error: null, meta: { requestId, duration } }`.
+
+- `list` / `running` — array of `pipeline_executions` rows, newest first
+  (`list` by `created_at`, `running` by `started_at`).
+- `get` — one row.
+- `stats` — `{ total, completed, failed, running }` counted in memory over
+  the filtered set.
+- `create` — `{ execution_id }`.
+- `start` / `complete` / `cancel` — `{ success: true }`.
+- `cleanup` — `{ deleted_count }`.
+
+## Side effects
+
+- `create` inserts a row with `status: 'pending'`, stamped with
+  `created_by` and `account_id`.
+- `start` / `complete` / `cancel` update status and timestamps; `complete`
+  also writes `result`, `error_message`, and `duration_ms` computed from
+  `started_at`.
+- `cleanup` deletes rows permanently.
+- Each write emits an audit log: `pipeline_execution.created`,
+  `pipeline_execution.started`, `pipeline_execution.completed`,
+  `pipeline_execution.cancelled`, `pipeline_executions.cleaned`.
+
+## Errors
+
+- `Execution ID is required` — `get`, `start`, `complete`, `cancel`
+  without `id`.
+- `Pipeline ID is required` / `Account context required` — `create`
+  validation; account check on `list`, `running`, `stats` for non-admins.
+- `Invalid action or method` — unmatched action/method pair.
+- `get` uses `.single()` — a missing id surfaces as a database error,
+  not a clean 404.
+- All thrown errors become structured 500 responses unless they carry a
+  `statusCode`.
+
+## Agent notes
+
+- `create` here stamps `status: 'pending'` — a different value from the
+  `queued` rows the trigger engine creates before dispatching to
+  `pipeline-runner-background`. Both are non-terminal.
+- Rows stuck in `queued` or `running` mean dispatch or the runner died;
+  `sweepStaleExecutions` in `.framework/functions/_shared/pipeline-runner.ts`
+  marks `running`/`pending`/`queued` rows untouched for over 10 minutes as
+  `failed`.
+- `cancel` only updates the row — nothing in this function interrupts an
+  in-flight run.
+- `stats` loads all matching `id, status` rows and counts in memory; it
+  has no `limit` guard, so very large histories are expensive.