spine-framework 0.4.4 → 0.5.0-rc.5

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.

package/.framework/src/instructions/guide/00-orientation.md

@@ -0,0 +1,106 @@
+---
+title: Orientation — what Spine Framework is
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - package.json
+  - netlify.toml
+  - .env.example
+  - .framework/cli/commands/init.ts
+  - .framework/templates/project.json
+  - .framework/src/components/admin/PageInstructions.tsx
+  - .framework/src/instructions/README.md
+---
+
+# Orientation
+
+Spine Framework is a multi-tenant application platform you install into an npm
+project. It gives you the "boring 80%" of a SaaS product — the infrastructure
+every app needs and nobody wants to rebuild — so your code can be the
+interesting 20%.
+
+## What you get out of the box
+
+- **A typed runtime data layer.** Accounts, people, and typed records (items,
+  threads, messages, links, attachments, watchers) stored in Supabase Postgres,
+  all reachable through one CRUD/permissions API (`.framework/functions/admin-data.ts`).
+- **Auth and tenancy.** Supabase Auth for sign-in, an invite/registration
+  pipeline (`.framework/functions/invites.ts`), hierarchical accounts, and a
+  first-user bootstrap that seeds a system administrator.
+- **RBAC.** Roles plus per-type `record_permissions` evaluated on every request
+  (`.framework/functions/_shared/permissions.ts`).
+- **Automation.** Declarative pipelines, event triggers, timers, integrations,
+  and AI agents — all database rows, all driven by the same runtime
+  (`.framework/functions/_shared/pipeline-runner.ts`,
+  `.framework/functions/_shared/trigger-engine.ts`).
+- **An admin UI.** A schema-driven admin surface at `/spine-framework/admin`
+  built from `.framework/src/apps/admin/index.tsx`, plus generic list/detail
+  pages that render directly from each type's views.
+- **Operations.** API keys for machine principals, delivery tracking, logs,
+  metrics, and pipeline execution history.
+
+The stack is deliberately conventional: a React + Vite frontend, Netlify
+Functions as the API layer, and Supabase (Postgres + Auth) as the database.
+`netlify.toml` points functions at `.assembled/netlify/functions` and publishes
+`dist`; `.env.example` lists the Supabase keys the app needs.
+
+## What `npm install spine-framework` + `npx spine-framework init` gave you
+
+`init` copies a framework-owned file set — declared in
+`.framework/templates/project.json` — into your project: the `.framework/`
+tree (frontend source, Netlify functions, migrations, CLI, seeds, schemas),
+`config/` build files, root `scripts/`, `bin/`, a neutral `spine.config.json`,
+a merged `package.json`, `netlify.toml`, `.gitignore`, and a frozen
+`.spine-manifest.json` recording the hash of every protected file. It also
+creates an empty `custom/` workspace — the one place your code lives.
+
+Two consequences follow:
+
+1. **`.framework/` (plus `config/` and `scripts/`) is sealed.** Every file is
+   hashed into `.spine-manifest.json`; `npx spine-framework upgrade` refuses to
+   overwrite a locally modified tree unless you pass `--force`.
+2. **`custom/` is yours.** Apps, functions, components, and migrations you
+   write go there; the framework never touches it.
+
+See [02-project-map.md](./02-project-map.md) for the full anatomy.
+
+## How this instruction book is organized
+
+This book ships inside the package at `.framework/src/instructions/` and is
+also rendered inside the admin UI — admin pages mount a
+`PageInstructions` sheet that loads these files as raw markdown and renders
+them with `react-markdown` + `remark-gfm`
+(`.framework/src/components/admin/PageInstructions.tsx`). Diagrams are plain
+ASCII; the renderer does not load mermaid.
+
+| Section | Kind | Contents |
+|---|---|---|
+| `guide/` | guide | End-to-end walkthroughs — you are here. |
+| `concepts/` | concept | Mental models (tenancy, permissions, schema). |
+| `tasks/` | task | Single-goal procedures with verification steps. |
+| `reference/` | reference | Exhaustive lookups (env vars, CLI, endpoints). |
+| `operations/` | ui | Admin-UI surfaces and operational runbooks. |
+| `internal/` | mixed | Repo-only notes; exempt from shipped-doc rules. |
+| book root | entity | One file per Spine entity — [types](../types.md), [apps](../apps.md), [roles](../roles.md), [pipelines](../pipelines.md), [triggers](../triggers.md), [timers](../timers.md), [integrations](../integrations.md), [ai-agents](../ai-agents.md), [prompts](../prompts.md), [api-keys](../api-keys.md), [deliveries](../deliveries.md). |
+
+Entity files all use the same seven sections — *What this is for → Fields and
+settings → Minimal configuration → Full configuration → Example → Core files →
+Agent notes* — so once you have read one, you know the shape of all of them.
+
+## How to read it
+
+- **Developers:** read this guide section in order
+  ([install](./01-install-and-first-run.md) →
+  [project map](./02-project-map.md) →
+  [domain model](./03-domain-model.md) →
+  [first app](./04-first-app.md)), then the entity file for whatever you are
+  building, then `reference/` for exact spellings.
+- **Agents:** [03-domain-model.md](./03-domain-model.md) gives you the
+  primitives and how they compose; each entity file's *Agent notes* section
+  lists the mistakes that actually break things; [05-glossary.md](./05-glossary.md)
+  pins down terminology.
+- Every page is verified against the code at the `verified_against` commit in
+  its frontmatter. Where the docs disagree with code, code wins — treat that as
+  a bug and check `Core files` on the relevant entity page.