spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/concepts/permissions.md

@@ -0,0 +1,150 @@
+---
+title: Permission Model
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/admin-data.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/002_core_rls_and_functions.sql
+  - .framework/migrations/003_core_system_data.sql
+---
+
+# Permission Model
+
+Spine authorization is two independent layers, and the code says so verbatim:
+**"RLS controls row access; design_schema controls what the principal can do.
+No permissions granted = none given."** (`.framework/functions/_shared/permissions.ts`)
+
+- **Row visibility (RLS):** Postgres policies scope every tenant table to the
+  accounts the caller can reach — see [Scope and Accounts](scope-and-accounts.md).
+- **Action authorization (`record_permissions`):** per request, the permission
+  engine evaluates the caller's role against the schema **stamped on the
+  record** to decide create/read/update/delete and per-field read/write.
+
+## Principals
+
+`.framework/functions/_shared/principal.ts` resolves two principal types:
+
+- **Human** — Supabase JWT → `people` row → `role_id` join to `roles`; the
+  principal carries `roles: [slug]` and gets a JWT-scoped DB client (`ctx.db`),
+  so RLS applies.
+- **Machine** — `x-api-key` header → `api_keys` row → `scopes` array and the
+  key's `account_id`. Machine principals get `adminDb` (service role), which
+  **bypasses RLS entirely**; their only authorization is the scope check.
+
+## The three surfaces
+
+`detectSurface` in `.framework/functions/_shared/permissions.ts` buckets the
+target by table name:
+
+| Surface | Covers | Rule |
+|---|---|---|
+| First (default) | runtime records — items, threads, messages, people, accounts, … | `record_permissions` on the record's stamped `design_schema` |
+| Second | config objects — `apps`, `pipelines`, `triggers`, `ai_agents`, `embeddings`, `timers`, `integrations`, `roles`, `types`, `prompt_configs` | `system_admin` full access; machine principals read-only; everyone else denied |
+| Third | system metadata — `logs`, `pipeline_executions`, `trigger_executions`, `link_types`, `links` | `system_admin`/machine full; humans read only their own/account rows |
+
+## First-surface evaluation
+
+`resolveFirstSurfacePermissions` runs on every runtime-record access:
+
+1. **Schema source is the record.** The stamped `design_schema` on the record
+   is authoritative; there is deliberately no fallback to the type row — a
+   record with no schema or no `record_permissions` is denied.
+2. **Role resolution.** The caller's role slug comes from
+   `people.role_id → roles.slug` (one role per person, cached ~60s). No role,
+   no permissions.
+3. **Record grant.** `record_permissions[roleSlug]` is an array of actions
+   (`create`, `read`, `update`, `delete`). The special key `'all'` is a
+   wildcard evaluated for every authenticated principal — grants to `all`
+   apply to anyone who passed RLS.
+4. **Field merge.** For each declared field, `fields.<name>.permissions[role]`
+   — an array drawn from `read`/`write` only — replaces the default. Fields
+   **without** an entry default to `{ read: canRead, write: canUpdate }` from
+   the record grant. That is why `record_permissions` is the base, most
+   restrictive grant and field entries are *overrides*: an explicit `["read"]`
+   on a field removes write access that `update` would otherwise give.
+
+> **Role keys are matched verbatim.** `record_permissions` keys must be real
+> `roles.slug` values — nothing normalizes them. The seeded admin slug is
+> `system_admin` (underscore, `.framework/migrations/003_core_system_data.sql`);
+> a `system-admin` key silently matches nobody and denies the admin.
+
+## Enforcement points
+
+- **Read** (`sanitizeFirstSurfaceRecordData`): `canRead` gates the record;
+  `data` is filtered per field by `fieldPermissions[name].read`; values are
+  formatted through `validation_schema` (`formatFieldData`); legacy `metadata`
+  is stripped from responses. Records with an empty `fields` map pass through
+  whole at the record grant.
+- **Update** (`validateFirstSurfaceUpdatePermissions`): `canUpdate` gates the
+  record, then **every key inside `data` must have `write`** — one denied field
+  fails the whole update with a per-field error. Values are sanitized through
+  `sanitizeFieldData` (type coercion + constraint checks; violations are
+  errors, not silent drops). Top-level non-`data` keys pass through the gate.
+  Writes therefore require both the record action *and* field-level write —
+  undeclared fields have no `fieldPermissions` entry and 403.
+- **Create** (`admin-data` `create`): permission is checked against the type's
+  `design_schema` (which becomes the record's stamp) before insert;
+  `type_id`/`type_slug` is required. A machine principal with `*:*` scope
+  bypasses the create check.
+
+## `system_admin` bypass
+
+`isSystemAdmin` (`roles` contains `system_admin`) short-circuits record
+access, sanitization, and update validation in `permissions.ts`, and gates the
+`types.ts`/`roles.ts`/`apps.ts` write APIs entirely. The same slug drives the
+RLS bypass inside `get_accessible_accounts` — system admins see all accounts.
+
+## Machine (API key) scopes
+
+`checkMachineScope` grants an action when the key's `scopes` contain
+`resource:action` exactly, `resource:*`, or `*:*` (e.g. `items:read`,
+`items:*`, `*:*`). Scopes are the *only* thing standing between a leaked API
+key and `adminDb`, so issue the narrowest scope that works — `*:*` also
+bypasses the create permission check in `admin-data`.
+
+## Canonical example
+
+The seeded pattern from the framework migrations — base grant first, field
+override only where needed:
+
+```json
+{
+  "record_permissions": {
+    "system_admin": ["create", "read", "update", "delete"],
+    "member_admin": ["create", "read", "update"],
+    "member":       ["create", "read", "update"]
+  },
+  "fields": {
+    "title":    { "data_type": "text",   "label": "Title",    "required": true,  "system": true },
+    "status":   { "data_type": "select", "label": "Status",   "required": true,
+                  "options": ["open", "closed"],
+                  "permissions": { "member": ["read"] } },
+    "internal_notes": { "data_type": "textarea", "label": "Internal Notes",
+                  "required": false,
+                  "permissions": { "member": [] } }
+  }
+}
+```
+
+Reading it: `member` can create and update records, so every declared field
+defaults to read+write — except `status`, whose `["read"]` override strips
+`member`'s write, and `internal_notes`, whose empty override hides it from
+`member` entirely. `member_admin` touches neither override, so it inherits
+record-level read+write on both. That is the whole discipline: **add a
+`fields.*.permissions` entry only where the base grant is wrong for that
+field** — usually to restrict a sensitive or `system: true` field, occasionally
+to loosen one the base grant closes.
+
+## See also
+
+- [Design Schema](design-schema.md) — where `record_permissions` lives
+- [Scope and Accounts](scope-and-accounts.md) — the RLS layer beneath this one
+- [../roles.md](../roles.md) — the role entity (`permissions` on roles bound
+  the *subject* side at the app/UI level)

package/.framework/src/instructions/concepts/runtime-records.md

@@ -0,0 +1,111 @@
+---
+title: Runtime Records
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/src/hooks/useEntityRecord.ts
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+---
+
+# Runtime Records
+
+Runtime records are the rows your users and apps actually create — as opposed
+to config entities (`types`, `apps`, `roles`, `pipelines`, …) that describe
+the system itself. They share one storage contract: a type, an account, a
+stamped schema, and a split between framework-owned columns and app-owned
+`data`.
+
+## The record kinds
+
+`admin-data` maps entity names to type `kind`s via `ENTITY_TO_KIND`
+(`.framework/functions/admin-data.ts`):
+
+| Entity (table) | `kind` | What it is |
+|---|---|---|
+| `items` | `item` | The workhorse — tickets, tasks, articles, any typed business object |
+| `threads` | `thread` | A conversation bound to a target (`target_type` + `target_id`); unique per `(target_type, target_id, visibility)` |
+| `messages` | `message` | An entry in a thread (`thread_id` + `sequence`, unique together) |
+| `links` | `link` | A polymorphic edge between two records (`source_type`/`source_id` → `target_type`/`target_id`, optional `link_type`) |
+| `attachments` | `attachment` | A stored file reference (filename, size, mime, `storage_path`) |
+| `watchers` | `watcher` | A person subscribed to a target (unique per target+person) |
+| `people` | `person` | Users/contacts — also carry `auth_uid`, `role_id`, `email` |
+| `accounts` | `account` | Tenants — the only table without `account_id` (it *is* the account) |
+| `item_progress` | `item_progress` | Progress/status snapshots for items |
+
+`VALID_ENTITIES` also accepts `logs`, `test_runs`, `observability`, and
+`test_cases` — the `RAW_ENTITIES` path: whitelisted raw-column inserts with no
+type requirement and no `design_schema`. `types` and `link_types` are accepted
+too but are config, not runtime records.
+
+## The shared row shape
+
+Every runtime table in `.framework/migrations/001_core_schema.sql` carries the
+same spine:
+
+- `id`, `created_at`, `updated_at`, `created_by` (+ `updated_by` on most)
+- `type_id uuid NOT NULL` — every record must reference a type
+- `account_id` — the owning tenant (all except `accounts`)
+- `app_id` — optional attribution to the app that created it
+- `data jsonb` — app-defined field values
+- `design_schema jsonb`, `validation_schema jsonb` — **stamped at creation**
+  from the type; the runtime source of truth for permissions and validation
+  (see [Design Schema](design-schema.md))
+- `is_active` — soft-delete flag; `remove` flips it rather than deleting
+
+`admin-data` create requires `type_id` *or* `type_slug` — `resolveTypeRecord`
+in `.framework/functions/_shared/resolve-ids.ts` resolves `(kind, slug)` to
+the type row, and the record is stamped before permission evaluation and
+insert.
+
+## `system: true` columns vs `record.data`
+
+The field declaration's `system` flag decides where a value lives:
+
+- **`system: true`** → a top-level record column (`record.title`,
+  `record.status`, `record.email`). These are framework-owned or
+  schema-critical fields.
+- **`system: false` / omitted** → inside `record.data.<field>`.
+
+Consumers split on the flag — this is the authoritative convention:
+
+- `useEntityRecord.save` partitions form data into `systemData` (top-level
+  keys) and `customData` (packed into `data`) by `fieldDef.system`
+  (`.framework/src/hooks/useEntityRecord.ts`).
+- `GenericDetailPage` initializes each field from `record[field]` when
+  `fieldDef.system` and `record.data[field]` otherwise
+  (`.framework/src/components/app-shell/GenericDetailPage.tsx`).
+- The permission engine's write gate evaluates every key inside `data`
+  against `fieldPermissions[name].write` and sanitizes through
+  `validation_schema` (`.framework/functions/_shared/permissions.ts`).
+
+**Fact:** send system fields as top-level keys and non-system fields inside a
+`data` object. A non-system field sent top-level is stored but invisible to
+schema-driven readers; a system field sent inside `data` never reaches its
+column.
+
+## Reading records back
+
+Reads pass through `sanitizeRecordData`: fields the caller can't read are
+dropped from `data`, the legacy `metadata` key is stripped from responses, and
+remaining values are formatted through `validation_schema`
+(`formatFieldData` — e.g. currency, multiselect, dates). A record the caller
+can't read at all collapses to `{id, created_at, updated_at}` — so "record
+exists but looks empty" is a permission answer, not missing data.
+
+## Writing rules of thumb
+
+- `type_slug` + `entity` on create; `id` on update/delete.
+- Never write `design_schema`, `validation_schema`, `type_id`, `account_id`,
+  or `id` in the body — create strips them before insert (`account_id` in the
+  body is honored as a *targeting* hint, see
+  [Scope and Accounts](scope-and-accounts.md)).
+- Deletes are soft (`is_active = false`) for the standard entities; only a few
+  entities hard-delete.
+- Creates fire triggers (`fireCreateTriggers`) and per-type rate limits after
+  permission checks — a custom insert path loses both.

package/.framework/src/instructions/concepts/scope-and-accounts.md

@@ -0,0 +1,112 @@
+---
+title: Scope and Accounts
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/002_core_rls_and_functions.sql
+  - .framework/migrations/011_spine_system_account.sql
+  - .framework/migrations/013_get_account_apps_role_filter.sql
+  - .framework/migrations/015_types_kind_slug_unique.sql
+  - .framework/functions/admin-data.ts
+  - .framework/functions/apps.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/db.ts
+---
+
+# Scope and Accounts
+
+Accounts are Spine's tenancy primitive: every runtime record belongs to
+exactly one `account_id`, and that column is what both RLS and the app layer
+use to partition tenants. `design_schema.scope` is the small lever that decides
+*which* account a record belongs to.
+
+## The tenancy model
+
+- **`public.accounts`** — the tenant (organization, workspace, customer).
+  Accounts form a hierarchy through `parent_id`; the `account_paths` closure
+  table stores every ancestor→descendant pair so subtree lookups are one join.
+  Accounts have no `account_id` of their own — the table is the source of
+  truth.
+- **`public.people`** — a person belongs to exactly one account
+  (`people.account_id NOT NULL`) and holds one `role_id`. A person is *also* a
+  runtime record: `type_id`, `data`, and a stamped `design_schema`.
+- **Everything else** — `items`, `threads`, `messages`, `links`,
+  `attachments`, `watchers`, `item_progress` — carries
+  `account_id NOT NULL` (or via its parent thread for `messages`).
+
+## How scope decides `account_id`
+
+`admin-data` create resolves the record's account in order
+(`.framework/functions/admin-data.ts`, `create`):
+
+1. An explicit `account_id` in the request body, else the caller's
+   `ctx.accountId`.
+2. If the record references a parent (`thread_id`, `target_id`, `parent_id`),
+   the **parent's** `account_id` wins — and the parent's stamped `scope` is
+   inherited into the new record's `design_schema`. A child can never drift
+   into a different tenant than its parent.
+3. `design_schema.scope` then applies: `'account'` (the default) keeps the
+   resolved account; `'platform'` replaces it with the **spine-system**
+   account's id.
+
+So `scope` on a type is really "which tenant owns these records": your
+account's rows, or the platform's shared rows.
+
+## The `spine-system` account
+
+Seeded by `.framework/migrations/011_spine_system_account.sql`:
+`accounts.slug = 'spine-system'` — "Master system account for internal Spine
+operations." It is the landing account for `scope: 'platform'` records. The
+`accounts` table itself is the exception to the scoping rule: it has no
+`account_id` column for scope to land on, so for `accounts` records
+`admin-data` instead sets `parent_id` to the creator's account when none is
+given — new accounts are born as *children* of the account that created them.
+
+## How scope affects queries
+
+- **Human callers** query through `ctx.db` — a Supabase client created with the
+  caller's JWT (`.framework/functions/_shared/principal.ts`,
+  `getPrincipalDb`). RLS policies on the tenant tables filter rows to
+  `account_id IN (SELECT get_accessible_accounts(current_actor_id()))`
+  (`.framework/migrations/002_core_rls_and_functions.sql`).
+  `current_actor_id()` maps `auth.uid()` to the `people` row;
+  `get_accessible_accounts` returns that person's account **plus every
+  descendant** via `account_paths` — a parent-account user sees the whole
+  subtree. If the person holds `system_admin`, the function short-circuits and
+  returns *all* accounts.
+- **Machine callers** (API keys) use `adminDb`, which bypasses RLS; tenancy is
+  enforced only by the key's `account_id` and `scopes` — see
+  [Permissions](permissions.md). A `*:*` key reads every tenant.
+- **Platform-scoped rows** carry the `spine-system` `account_id`, so under
+  account-based RLS they are visible to the spine-system account subtree and
+  to `system_admin` (who sees all accounts) — not to ordinary tenant users
+  querying through `ctx.db`. Machine principals on `adminDb` reach them
+  regardless, subject to key scopes.
+
+## What is *not* scoped by account
+
+- **Types are global.** `public.types` uniqueness is `(kind, slug)`
+  (`.framework/migrations/015_types_kind_slug_unique.sql`) — deliberately not
+  per-app or per-account, so `resolveTypeRecord(kind, slug)` `.single()`
+  lookups stay deterministic and every account shares the same type registry.
+- **Apps are global** rows in `public.apps`, linked to accounts only through
+  `owner_account_id` and the `get_account_apps` RPC, which filters by the
+  caller's role slugs (`.framework/functions/apps.ts`;
+  `.framework/migrations/013_get_account_apps_role_filter.sql`).
+- **Roles** are global slugs matched verbatim by the permission engine.
+
+## Practical consequences
+
+- Put `scope: 'platform'` only on types whose records should exist once for the
+  whole installation (system config, shared registries) — never on tenant
+  data.
+- Child records inherit the parent's account and scope; you cannot re-tenant a
+  record by pointing it at a parent in another account — the parent's account
+  wins, silently.
+- Because types are global, pick type slugs as if they were API names:
+  `kind + slug` must be unique across every app installed in the deployment.
+- Account-scoped tests and seeds must set `account_id` on every record or RLS
+  will make them invisible to human-scoped queries.

package/.framework/src/instructions/concepts/spine-way.md

@@ -0,0 +1,172 @@
+---
+title: The Spine Way
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - scripts/boundary-check.sh
+  - config/vite.config.ts
+  - config/tsconfig.json
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/cli/commands/migrate.ts
+  - .framework/cli/commands/upgrade.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/002_core_rls_and_functions.sql
+  - .framework/migrations/011_spine_system_account.sql
+  - .framework/src/hooks/useEntityRecord.ts
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+---
+
+# The Spine Way
+
+Ten rules every app, function, migration, and type must satisfy to stay aligned
+with the framework. Each rule is stated as a quotable invariant, followed by
+why it exists and what actually breaks when you violate it. Deeper treatment of
+each topic lives in the sibling concept pages.
+
+## 1. Core never imports from custom
+
+`.framework/` must not import from `custom/`, `custom_*` modules, or hardcode
+custom app slugs.
+
+**Why:** `.framework/` is a sealed, upgradeable npm package — it must run
+identically in every project.
+
+**Breaks:** `scripts/boundary-check.sh` fails the build (checks 1–3), and the
+next `upgrade` either aborts on locally modified framework files or silently
+overwrites the coupling.
+
+## 2. Custom code imports core through `@core/*`, never relative paths
+
+Custom frontend code uses `@core/components/...`, `@core/hooks/...`; custom
+functions import `./_shared/...` after assembly (`@shared/*` in
+`config/tsconfig.functions.json`).
+
+**Why:** `@core` maps to `.framework/src` in `config/tsconfig.json` and to the
+assembled tree in `config/vite.config.ts` — the two roots custom code is
+actually built against.
+
+**Breaks:** `scripts/boundary-check.sh` check 2b flags relative `../.framework`
+imports in `custom/`, and paths that resolve today break the moment the
+assembly layout changes.
+
+## 3. Apps are registered data, not static imports
+
+An app is a `manifest.json` plus a row in `public.apps`; the shell mounts it at
+runtime by `route_prefix` and `renderer`.
+
+**Why:** registration is what makes an app discoverable, permissionable
+(`min_role` / `required_roles`), and toggleable (`is_active`) without a core
+redeploy.
+
+**Breaks:** statically importing an app component into `.framework/src/`
+violates rule 1 and bypasses the role gate in
+`.framework/src/components/AppWrapper.tsx` — the app is always visible and
+always mounted.
+
+## 4. Runtime record CRUD goes through `/api/admin-data`
+
+All creates, reads, updates, and deletes of `items`, `threads`, `messages`,
+`links`, `attachments`, `watchers`, `people`, `accounts` go through the single
+`admin-data` endpoint.
+
+**Why:** that endpoint is where type resolution, `design_schema` stamping,
+permission evaluation, audit logging, and trigger dispatch actually live — see
+`.framework/functions/admin-data.ts`.
+
+**Breaks:** a custom function wrapper skips record permissions, field-level
+write gates, `validation_schema` sanitization, audit rows, and create/update
+triggers — the record lands in the table but nothing that should have run ran.
+
+## 5. Behavior lives in `design_schema`, not handler branches
+
+Fields, views, record permissions, scope, and functionality bindings belong on
+the type's `design_schema`; the runtime stamps a copy onto every record at
+creation.
+
+**Why:** the permission engine and generic renderers read the schema off the
+record — `.framework/functions/_shared/permissions.ts` denies outright when a
+record has no stamped `record_permissions`.
+
+**Breaks:** hardcoded per-type branches can't be permissioned, can't render in
+the generic UI, and drift from the stamped schema records already carry.
+
+## 6. `record_permissions` is the base grant; field permissions are overrides
+
+Start with the most restrictive `record_permissions` per role. A field without
+a `fields.<name>.permissions` entry inherits `read` from `canRead` and `write`
+from `canUpdate`; only add a field-level entry to change that default.
+
+**Why:** the merge in `resolveFirstSurfacePermissions` applies the override
+verbatim — `["read"]` on a field removes `write` for that role even when the
+record grant allows it.
+
+**Breaks:** re-stating record-level grants per field silently locks fields, and
+leaving `system: true` fields un-overridden lets any record-writer modify
+columns like `status` or `slug`.
+
+## 7. RLS decides which rows you see; design_schema decides what you can do
+
+Every tenant table has RLS enabled and policies scope rows through
+`get_accessible_accounts(current_actor_id())`. Human requests query through
+`ctx.db` (JWT-scoped); `adminDb` bypasses RLS and is reserved for service-role
+work.
+
+**Why:** this is the second, independent layer of authorization — RLS cannot
+express per-type, per-role, per-field grants.
+
+**Breaks:** a table without RLS leaks every tenant's rows to every caller; a
+handler that uses `adminDb` "for convenience" turns your permission model into
+decoration.
+
+## 8. Migrations are idempotent and ordered
+
+Filenames are `NNN_description.sql`; every statement must be safe to re-run
+(`CREATE ... IF NOT EXISTS`, `DROP POLICY IF EXISTS`, `ON CONFLICT DO NOTHING`,
+guarded `DO $$` blocks). `migrate` applies `.framework/migrations` first, then
+`custom/migrations`, each sorted by name.
+
+**Why:** the same migration set runs against fresh and existing databases, and
+later migrations legitimately depend on earlier objects.
+
+**Breaks:** a non-idempotent migration fails on second run and wedges every
+environment that already applied it; unordered migrations crash on missing
+dependencies.
+
+## 9. `system: true` fields live on the record; everything else lives in `data`
+
+Fields declared `system: true` read and write top-level record columns
+(`record.title`); all other fields live inside `record.data.<field>`.
+
+**Why:** the split is how the platform separates framework-owned columns from
+app-defined data — `.framework/src/hooks/useEntityRecord.ts` splits form data
+by `fieldDef.system` on every save, and
+`.framework/src/components/app-shell/GenericDetailPage.tsx` reads the same way.
+
+**Breaks:** sending a non-system field as a top-level key writes it outside the
+field-permission gate's `data` object (invisible to renderers); sending a
+system field inside `data` never reaches its column.
+
+## 10. Secrets and service keys stay on the backend
+
+Browser code may use `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` only.
+`SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_DB_PASSWORD`, and app secrets appear
+only in `.framework/functions/`, `.framework/cli/`, and uncommitted env files.
+
+**Why:** `adminDb` is a service-role client — whoever holds the service key
+holds an RLS bypass for the entire database.
+
+**Breaks:** a service key bundled into frontend code is a credential leak with
+full read/write on every tenant's data; committed env files leak it to every
+clone of the repo.
+
+## Applying the rules
+
+Before shipping a change, walk the list and check each rule that could apply.
+When a rule genuinely must bend, prefer the weakest violation (data over code,
+config over core) and document it — most "exceptions" turn out to be a missing
+`design_schema` section or a missing app manifest entry.

package/.framework/src/instructions/deliveries.md

@@ -0,0 +1,59 @@
+---
+title: Deliveries
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/deliveries.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/_shared/retry-deliveries.ts
+  - .framework/src/pages/admin/DeliveriesPage.tsx
+---
+
+## What this is for
+
+**Deliveries** is the outbound delivery log — every webhook/integration delivery attempt, its status, retries, and response. It is primarily a diagnostic, read-mostly page: use it to confirm an event left Spine, to debug a failing endpoint, and to see retry behavior.
+
+## Fields and settings
+
+- **Direction** — `inbound` (external webhook into Spine) or `outbound` (Spine calling an integration).
+- **Status** — `pending`, `processing`, `delivered`, or `failed`. Pending rows with a future `next_attempt_at` are scheduled retries.
+- **Integration** — the `integration_id` the delivery ran through.
+- **Handler / Action** — `handler_name` (inbound webhook handler) or `action_slug` that produced it.
+- **Attempts** — `attempt_count / max_attempts`. `max_attempts` defaults to 3, overridable per call (`action_config.max_attempts`) or per integration (`config.retry_policy.max_attempts`).
+- **Next Attempt / Created** — scheduled retry time and queue time. `response_status` and `last_error` on the row capture the last attempt's result.
+
+**Downstream effects**
+
+- A `failed` row means the endpoint rejected or timed out and `attempt_count` reached `max_attempts` — fix the endpoint or credentials, then retry via the API (`deliveries?action=retry`, outbound only) or re-fire the event.
+- Retries reuse the same row: `attempt_count` increments and `next_attempt_at` follows exponential backoff (30s × 2^attempt, capped at 1h, +20% jitter). `system-cron` sweeps due `pending` rows each tick.
+- Deliveries are produced by `integration-outbound` (outbound) and `integration-routes` (inbound) — an empty list with active webhooks usually means no events matched, not a broken delivery layer.
+- Rows are append-only diagnostics; there is nothing to create or edit on this page.
+
+## Minimal configuration
+
+N/A — deliveries are generated by outbound calls, not authored. To produce one: create an `integration-routes`/webhook integration (or a trigger with an outbound stage), then emit its event.
+
+## Full configuration
+
+N/A — see `integrations` for endpoint/credential configuration, `triggers`/`pipelines` for what fires deliveries.
+
+## Example
+
+A support app's `customer-webhooks` integration posts every `ticket.closed` event to the customer's endpoint; a `failed` delivery with response `401` points at an expired token — rotate it in the integration's `credentials`, not here.
+
+## Core files
+
+- `.framework/functions/deliveries.ts` — API (list/get/`action=retry`)
+- `.framework/functions/integration-outbound.ts` — outbound broker that writes delivery rows
+- `.framework/functions/integration-routes.ts` — inbound webhook path that writes inbound rows
+- `.framework/functions/_shared/retry-deliveries.ts` — scheduled sweep of due `pending` rows
+- `.framework/src/pages/admin/DeliveriesPage.tsx` — admin UI
+- Table: `public.webhook_deliveries`
+
+## Agent notes
+
+- Debug order: delivery row → integration config/credentials → the event producer (trigger/pipeline). The delivery row is the *symptom*, not the cause.
+- Repeated failures across one endpoint usually mean credentials or URL drift; failures across many endpoints point at the outbound broker or networking.
+- Delivery volume doubles as an activity signal for integrations — a silent integration shows up here first.