spine-framework 0.4.3 → 0.5.0-rc.4

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

@@ -0,0 +1,140 @@
+---
+title: triggers
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/triggers.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/public/_redirects
+---
+
+# triggers
+
+## What it does
+
+CRUD plus `toggle`, `listByEvent`, and `getExecutions` over
+`public.triggers` — the config rows that bind an `event_type` to a
+`pipeline_id`. **This function never fires anything**: matching and
+dispatch happen in `.framework/functions/_shared/trigger-engine.ts`
+(`checkAndFireTriggers`/`fireCreateTriggers`/`fireUpdateTriggers`,
+invoked by `admin-data` on record writes), which reserves a
+`trigger_executions` row and POSTs the run to the
+`pipeline-runner-background` function. See
+[Automation](../../concepts/automation.md).
+
+## Route and methods
+
+`/.netlify/functions/triggers`, reachable as `/api/triggers` (`/api/*` →
+`/.netlify/functions/:splat`, `.framework/public/_redirects`). `?action=`
+takes precedence; without it the dispatcher falls back to the HTTP method —
+`GET` → `get` (with `id`) else `list`, `POST` → `create`, `PATCH` →
+`update`, `DELETE` → `remove`:
+
+| Call | Handler |
+|---|---|
+| `/api/triggers?action=list` | `list` |
+| `/api/triggers?action=listByEvent&event_type=<e>` | `listByEvent` |
+| `/api/triggers?action=get&id=<uuid>` | `get` |
+| `/api/triggers?action=getExecutions&trigger_id=<uuid>` | `getExecutions` |
+| `/api/triggers?action=create` | `create` |
+| `/api/triggers?action=update` (`id` in body or query) | `update` |
+| `/api/triggers?action=remove` (`id` in body or query) | `remove` |
+| `/api/triggers?action=toggle` (`id` in body or query) | `toggle` |
+
+A bare `GET /api/triggers` returns the active trigger list.
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list`/`listByEvent`/`getExecutions`/`create` require `ctx.accountId`.
+- `create` requires `system_admin` or a `canCreate` grant from
+  `resolveFirstSurfacePermissions(..., 'trigger', 'create')`.
+- `update`/`remove`/`toggle` have no explicit gate — humans are bounded
+  by RLS on `ctx.db`; machines run service-role.
+- Reads are sanitized: non-admins get `{ id }` per row (trigger rows
+  carry no `design_schema`).
+
+## Request contract
+
+**list** (query): `app_id`, `event_type`, `include_inactive` (`'true'`
+to include; default active only). Ordered by `name`.
+
+**listByEvent** (query): `event_type` required; `app_id`,
+`include_inactive` optional.
+
+**get** (query): `id`. **getExecutions** (query): `trigger_id`
+required; `limit` (default 50), `offset` — reads
+`public.trigger_executions` ordered `executed_at` desc.
+
+**create** (body): `name`, `event_type`, `pipeline_id` required.
+Optional: `app_id`, `description`, `trigger_type` (defaults `'event'`),
+`config` `{}`, `metadata` `{}`. `account_id`/`created_by` stamped —
+`created_by` is `null` for machine principals. (`event_type`,
+`trigger_type`, `pipeline_id` columns were added by
+`.framework/migrations/020_schema_reconciliation.sql`.)
+
+**update** (`id` in body or query + body): allowlist — `name`,
+`description`, `config`, `pipeline_id`, `metadata`, `is_active`,
+`event_type`, `trigger_type`, `app_id`.
+
+**remove** (`id` in body or query): soft delete (`is_active = false`).
+
+**toggle** (`id` in body or query): flips `is_active` — no target-state
+argument.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list`/`listByEvent`/`get`/`create`/`update`/`toggle` → sanitized
+  row(s); `remove` → `{ success: true }`; `getExecutions` → raw
+  `trigger_executions` array (unsanitized).
+- The file also exports `AGENT_EVENT_TYPES` — the `agent.*` event names
+  (`agent.inference.completed`, `agent.tool.called`,
+  `agent.message.received`, …) usable as `event_type` values — but
+  `event_type` is free-form text; any string is accepted.
+
+## Side effects
+
+- `toggle`/`update`/`remove` stamp `updated_at`; `is_active` is what the
+  trigger engine filters on when matching events.
+- `emitLog` writes `trigger.created` / `.updated` / `.deleted` /
+  `.toggled` audit rows to `public.logs`.
+- Writing a trigger has no immediate run effect — the row is only read
+  the next time `admin-data` (or another caller of the trigger engine)
+  emits a matching event.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No account context | 500 | `Account context required` |
+| `listByEvent` without `event_type` | 500 | `event_type is required` |
+| `getExecutions` without `trigger_id` | 500 | `trigger_id is required` |
+| Missing create fields | 500 | `name, event_type, and pipeline_id are required` |
+| Non-admin without create grant | 500 | `Insufficient permissions to create triggers` |
+| Missing `id` | 500 | `Trigger ID is required` |
+| Missing row | 500 | `Trigger not found` |
+| Missing/unknown action | 500 | `Unsupported action: <action>` |
+
+## Agent notes
+
+- Trigger→pipeline wiring is `pipeline_id` on the row; the engine reads
+  `config.entity_type`, `config.type_slug`, `config.filters`, and
+  `config.fire_on_transition` at match time — none of that is validated
+  by this endpoint, so a malformed `config` fails silently at match time
+  (the trigger simply never fires or always fires).
+- `getExecutions` is read-only bookkeeping written by the trigger
+  engine's `record_trigger_fire` path — execution lifecycle (queued →
+  running → complete/failed) is covered by `pipeline-executions` and
+  `pipeline-runner-background`, not this function.
+- `remove` is a soft delete; a deleted trigger stops matching on the
+  next event (the engine queries `is_active = true`).
+- `toggle` flips blindly — read first if you need a target state.

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

@@ -0,0 +1,146 @@
+---
+title: types
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/types.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/015_types_kind_slug_unique.sql
+  - .framework/public/_redirects
+---
+
+# types
+
+## What it does
+
+CRUD over `public.types` — the type-definition registry whose
+`design_schema`/`validation_schema` columns drive record validation,
+permissions, and the generic UI (see
+[Design Schema](../../concepts/design-schema.md)). Also resolves single
+types by `slug` and exposes a schema-lookup RPC pass-through.
+
+## Route and methods
+
+`/.netlify/functions/types`, reachable as `/api/types` (`/api/*` →
+`/.netlify/functions/:splat`, `.framework/public/_redirects`). Dispatch is
+by `?action=` plus the HTTP method (`?method=` can override the method):
+
+| Call | Handler |
+|---|---|
+| `GET /api/types?action=schema&kind=<k>&slug=<s>[&app_id=<uuid>]` | `getSchema` → RPC `get_type_schema` |
+| `GET /api/types?action=list` (or bare `GET` with no `id`/`slug`/`kind`) | `list` |
+| `GET /api/types?slug=<s>` | `getBySlug` (active rows only, joins `apps`) |
+| `GET /api/types?id=<uuid>` | `get` |
+| `POST /api/types` | `create` |
+| `PATCH /api/types?id=<uuid>` | `update` |
+| `DELETE /api/types?id=<uuid>` | `remove` |
+
+Quirk: a bare `GET` carrying `kind` (without `action=list` or
+`action=schema`) routes to `get`, which then fails with
+`Type ID is required` — kind-filtered listing requires `action=list`.
+
+## Authentication
+
+Standard `createHandler` auth (`resolvePrincipal` in
+`.framework/functions/_shared/principal.ts`): `x-api-key` → machine
+principal, `x-internal-secret` → internal principal,
+`Authorization: Bearer <jwt>` → human. Anonymous → 401.
+
+- `create`, `update`, `remove` require a `system_admin` role
+  (`PermissionEngine.isSystemAdmin(ctx)`) — no fallback permission path.
+- `list`/`get`/`getBySlug`/`getSchema` only require authentication.
+  System admins read via `adminDb` (all accounts); other principals use
+  `ctx.db` — JWT-scoped (RLS) for humans, service role for machines.
+
+## Request contract
+
+**list** (query): `kind`, `app_id` (`'null'` filters to global types),
+`ownership`, `active` (`'false'` → inactive only, `'all'` → everything,
+default → active only), `limit` (default 50), `offset` (default 0),
+`include_schema` (`'true'` also returns `validation_schema`).
+
+**getBySlug** (query): `slug` — active rows only.
+
+**getSchema** (query): `kind`, `slug` required; `app_id` optional
+(passed to the RPC as `null` when absent).
+
+**create** (body): `name`, `slug`, `kind` required. Optional:
+`ownership` (default `'system'`), `app_id` (default `null`),
+`design_schema` (default `{}`), `validation_schema` (default `null` →
+generated), `description`, `icon`, `color`.
+
+**update** (query `id` + body): `name`, `slug`, `description`, `icon`,
+`color`, `is_active`, `kind`, `app_id`, `ownership`, `design_schema` —
+only keys present in the body are written. An empty update returns the
+existing row unchanged.
+
+**remove** (query): `id`.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list` → array of sanitized type rows. `get`/`getBySlug`/`create`/
+  `update` → single row. `remove` → `{ success: true }`. `getSchema` →
+  `{ design_schema }`.
+- Sanitization (`sanitizeRecordData`): system admins get the full row.
+  Other principals go through first-surface logic — the row's own
+  `design_schema.record_permissions` decides visibility; rows without
+  them collapse to `{ id }`. `list` re-attaches `design_schema` to the
+  sanitized row when it was stripped, and attaches `validation_schema`
+  when `include_schema=true`.
+
+## Side effects
+
+- `create` inserts into `public.types` with `is_active: true`; when the
+  body omits `validation_schema` it is generated from `design_schema` by
+  `generateValidationSchema` (`.framework/functions/_shared/schema-utils.ts`).
+- `update` regenerates `validation_schema` **every time `design_schema`
+  is present in the body** — the derived schema is never hand-editable.
+- `remove` is a soft delete (`is_active = false`); `ownership: 'system'`
+  rows cannot be deleted, and their `ownership` cannot be changed away
+  from `'system'`.
+- `emitLog` writes `type.created` / `type.updated` / `type.deleted`
+  audit rows to `public.logs`.
+- Updating a type does **not** restamp `design_schema` onto existing
+  records — records keep the schema stamped at their own creation.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Not system admin (create/update/remove) | 500 | `System admin required` |
+| Missing create fields | 500 | `name, slug, and kind are required` |
+| Duplicate active slug/kind/app_id | 500 | `Type with slug '<s>' already exists for kind '<k>'` |
+| Missing `id` / `slug` / `kind`+`slug` | 500 | `Type ID is required` / `Type slug is required` / `kind and slug are required` |
+| Update/delete of missing row | 500 | `Type not found` |
+| Ownership change on system type | 500 | `Cannot change ownership of system types` |
+| Delete system type | 500 | `Cannot delete system types` |
+| Bad action/method | 500 | `Invalid action or method` |
+
+Validation failures surface as HTTP 500 — the shared error path maps
+thrown `Error`s without a `statusCode` to 500.
+
+## Agent notes
+
+- Slug uniqueness is global per `kind`: the `types_kind_slug_unique`
+  index on `types(kind, slug)`
+  (`.framework/migrations/015_types_kind_slug_unique.sql`) is stricter
+  than `create`'s pre-check (which scopes to `app_id` + `is_active`), so
+  a same-kind/same-slug insert under a different `app_id` passes the
+  pre-check and then fails at the database. Pick globally unique slugs.
+- `kind` must match the runtime table the type governs (`item`,
+  `thread`, `message`, …); `admin-data` resolves types by kind+slug.
+- `getSchema` delegates to the Postgres RPC
+  `get_type_schema(kind, slug, app_id)`, provided by migration
+  `070_app_type_schema_rpcs.sql` (along with `get_app_schema`,
+  `is_app_available`, `update_app_version`). Installs missing that
+  migration will see `function does not exist` errors.
+- `update` accepts `kind` and `app_id` changes — there is no guard
+  keeping `kind` aligned with already-stamped records.
+- The unauthenticated "minimal row" branch in `list` is unreachable via
+  HTTP: `createHandler` rejects anonymous callers with 401 first.

package/.framework/src/instructions/reference/seeds.md

@@ -0,0 +1,126 @@
+---
+title: Seeds Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/migrate.ts
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/seeds/types/spine_instance.json
+  - .framework/seeds/link_types/account_cli_instances.json
+  - .framework/migrations/003_core_system_data.sql
+  - .framework/migrations/053_builtin_action_seeds.sql
+---
+
+# Seeds Reference
+
+Seeds are JSON row files that materialize an app's database contract — types,
+roles, link types, agents, prompt configs, pipelines, triggers — at install
+time. They are distinct from migrations: **migrations are SQL and change
+schema; seeds are data and are applied by the app installer.**
+
+## Where seeds live
+
+| Location | Contents | Format |
+|---|---|---|
+| `custom/apps/<slug>/seed/*.json` | app-owned rows, declared in `manifest.json` `seed[]` | JSON **array** of row objects |
+| `.framework/seeds/` | framework-owned seed payloads (e.g. `.framework/seeds/types/spine_instance.json`, `.framework/seeds/link_types/account_cli_instances.json`) | single JSON object per file |
+| `.framework/migrations/` | system rows written by SQL (`003_core_system_data.sql` seeds roles/types/apps; `053_builtin_action_seeds.sql` seeds `public.actions`) | SQL `INSERT … ON CONFLICT DO NOTHING` |
+
+## When seeds run
+
+Seeds are applied by `seedApp` in `.framework/cli/commands/install-app.ts`:
+
+| Command | Runs seeds? |
+|---|---|
+| `install-app <pkg>` | yes — after `runMigrations` succeeds, unless `--no-seed`. Migration failure aborts before seeding; without `SUPABASE_URL`/`SUPABASE_DB_PASSWORD` only `--no-seed` installs may proceed |
+| `seed-app <slug>` | yes — seed block only, no npm, no file changes |
+| `update-db-app <slug>` | no — upserts the `apps` row and syncs `registration` only |
+| `update-app <pkg>` | no — refreshes files from npm only |
+| `migrate` | no — migrations apply SQL only; system seeds inside migrations run as SQL |
+| `uninstall-app <pkg>` | no — removes files and the npm dependency; it does not delete seeded rows |
+
+Requires `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`; seeding uses the
+service-role client and bypasses RLS.
+
+## Apply order
+
+Entries are stable-sorted by `SEED_TABLE_ORDER`
+(`.framework/cli/commands/install-app.ts`), regardless of declaration order:
+
+1. `roles`
+2. `types`
+3. `permissions_patch` entries (rank 1.5 — always after types)
+4. `link_types`
+5. `actions`
+6. `ai_agents`
+7. `prompt_configs`
+8. `pipelines`
+9. `triggers`
+10. unknown tables — last, in declared order
+
+Ordering exists so dependents resolve: a `triggers` row's `pipeline_slug` is
+looked up in `public.pipelines` (scoped to this app's `app_id`) and rewritten
+to `pipeline_id`, and a `pipelines` row's `stages[].stage_type` is validated
+against `public.actions` — so a bad stage type fails at install, not at first
+trigger fire.
+
+## Per-entry behavior
+
+Each record is upserted into `entry.table` with `onConflict: entry.conflict`.
+
+- **`inject_app_id`** (default `true`): stamps `app_id` on every row. Set
+  `false` for global rows — `types` seeds use `conflict: "kind,slug"` with
+  `inject_app_id: false` because type slugs are global, not per-app.
+- **`ignore_duplicates`**: rows that conflict are skipped, not updated.
+  Always forced on for `types` (the read-then-compare below decides the real
+  outcome) and opt-in per entry via `ignore_duplicates: true`.
+- **`types` rows are never silently overwritten.** Before each types upsert
+  the existing row is read: an identical `design_schema` skips cleanly; a
+  differing one throws — unless the slug is declared in
+  `manifest.owned_types` and `--reconcile-owned-types` was passed, which
+  prompts `[U]pdate / [K]eep` and merges (`seed` wins shared fields,
+  DB-only fields are preserved) with a regenerated `validation_schema`.
+- **`permissions_patch` rows** (`{kind, slug, record_permissions}`) replace
+  `design_schema.record_permissions` on an existing type after a
+  `[R]eplace / [K]eep` prompt; grant lists may only contain
+  `create`/`read`/`update`/`delete`. A `seed/type_permissions.json` file is
+  auto-declared when no patch entry exists.
+- **`types` seeds get a fresh `validation_schema`** generated from
+  `design_schema` at apply time — author `design_schema` only.
+- **`pipelines` seeds** are validated before upsert: every `stages[].stage_type`
+  must exist in `public.actions`; `send_notification`/`send_email`
+  `config.recipients` must be `role:<slug>`, `self`, `owner`, `watchers`, a
+  person UUID, or (email only) an email address.
+- **`triggers` seeds** may use `pipeline_slug`; it is resolved to
+  `pipeline_id` within the app's pipelines and removed before upsert.
+
+## Failure model
+
+Seeding is fail-closed: a malformed manifest, a missing declared seed file,
+an unparseable file, a non-array file, a missing referenced
+type/pipeline/role, or any row-write error throws and aborts the run. Files
+not declared in `manifest.seed` are skipped silently (except the auto-added
+`type_permissions.json`). All validation runs **before** the database client
+is created, so bad input produces zero writes.
+
+After all entries apply, `syncAppRegistration` writes the resolved
+`registration` policy to `apps.config.registration` and `spine.config.json`.
+
+## Authoring checklist
+
+- [ ] Every `seed[]` entry's `file` exists inside the app dir and parses as a JSON array of objects
+- [ ] `conflict` names real unique columns (`slug` for roles; `kind,slug` for types; `app_id,slug` for app-scoped config tables)
+- [ ] `types` rows have a complete `design_schema` — see [Design Schema](design-schema.md); `validation_schema` is generated
+- [ ] `inject_app_id: false` on `types` entries
+- [ ] `pipeline_slug` used in trigger seeds; pipelines seeded (they always apply first)
+- [ ] `owned_types` declared in the manifest for any type the app must reconcile
+- [ ] `manifest.seed` omitted only when the conventional trio (`seed/roles.json`, `seed/types.json`, `seed/link-types.json`) covers everything
+
+## Related files
+
+- `.framework/cli/commands/install-app.ts` — `seedApp`, `SEED_TABLE_ORDER`, `reconcileOwnedType`, `validatePipelineSeedStages`
+- `.framework/cli/commands/migrate.ts` — migration runner (SQL only)
+- [App Manifest](app-manifest.md) · [CLI](cli.md) · [Design Schema](design-schema.md)

package/.framework/src/instructions/reference/shared-modules.md

@@ -0,0 +1,127 @@
+---
+title: Shared Modules Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/_shared/index.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/logging.ts
+  - .framework/functions/_shared/audit.ts
+  - .framework/functions/_shared/tracing.ts
+  - .framework/functions/_shared/rate-limit.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/hash-api-key.ts
+  - .framework/functions/_shared/webhook-registration.ts
+  - .framework/functions/_shared/webhook-registry.ts
+  - .framework/functions/_shared/message-sequence.ts
+  - .framework/functions/_shared/security.ts
+---
+
+# Shared Modules Reference
+
+`.framework/functions/_shared/` is the library every Netlify function builds
+on — bundled per function, never deployed as an endpoint itself.
+`.framework/functions/_shared/index.ts` re-exports the common surface
+(`createHandler`, `createPublicHandler`, `requireUserContext`,
+`requireSystemContextWithAudit`, `json`, `errorResponse`, `cors`, the
+`Principal`/`RequestContext`/`CoreContext`/`HandlerFunction`/`HandlerResult`
+types). Import a sibling as `from './_shared/<module>'`.
+
+## Request handling
+
+| Module | Exports | Import when |
+|---|---|---|
+| `middleware.ts` | `createHandler`, `createPublicHandler`, `json`, `error`, `cors`, `parseBody`, `requireUserContext`, `requireSystemContextWithAudit`; `RequestContext`, `CoreContext`, `HandlerFunction`, `HandlerResult` | every function — wraps auth, tracing, envelope, and error mapping around your handler |
+| `principal.ts` | `resolvePrincipal`, `SYSTEM_PRINCIPAL`, `ANONYMOUS_PRINCIPAL`, `getPrincipalDb`, `isSystemAdmin`, `humanHasRole`, `machineHasScope`, `resolveInternalPersonId`, `formatPrincipalForAudit` | reading `ctx.principal`, checking roles/scopes, internal invocations |
+| `db.ts` | `adminDb` (service-role, bypasses RLS), `getUserDb(token)` (RLS-scoped), `joins` | direct table access — prefer `ctx.db` (already principal-scoped) inside handlers |
+
+## Permissions & data shape
+
+| Module | Exports | Import when |
+|---|---|---|
+| `permissions.ts` | `PermissionEngine`, `resolveFirstSurfacePermissions`, `sanitizeRecordData`, `validateUpdatePermissions`, `canAccessRecord`, `isSystemAdmin`, `PermissionResult` | evaluating `design_schema` grants, stripping fields a principal can't read, validating writes |
+| `schema-utils.ts` | `generateValidationSchema`, `sanitizeFieldData`, `formatFieldData`, `transformRecordData`, `ValidationSchema` | field validation/sanitization against `data_type`; generating `validation_schema` |
+| `resolve-ids.ts` | `resolveTypeId`, `resolveTypeIds`, `resolveTypeRecord`, `resolveAccountId`, `resolveLinkTypeId(s)`, `resolveAgentId`, `resolvePromptConfigId` | slug→uuid lookups for types, link types, accounts, agents, prompts |
+
+## Automation & agents
+
+| Module | Exports | Import when |
+|---|---|---|
+| `trigger-engine.ts` | `fireCreateTriggers`, `fireUpdateTriggers`, `fireDeleteTriggers`, `checkAndFireTriggers`, `dispatchTriggerPipeline`, `EventType` | firing record-change triggers; dispatching a pipeline run (needs `INTERNAL_INVOKE_SECRET`) |
+| `pipeline-runner.ts` | `runPipeline`, `sweepStaleExecutions`, `ExecutionResult`, `StageResult` | executing a pipeline's stages inside a function/background context |
+| `agent-runner.ts` | `runAgent`, `runAgentStep`, `claimAgentEpisode`, `kickAgentEpisode`, `acquireEpisodeLease`, `resolveAgentConfig`, `executeToolAction`, `retrieveKnowledge`, `AgentConfig`, `ToolCall`, `ToolResult` | running an AI agent turn against a thread |
+| `message-sequence.ts` | `insertMessageSequenced` | inserting a message outside `runAgent` — allocates `MAX(sequence)+1` and retries on the `(thread_id, sequence)` race |
+| `notify.ts` | `resolveNotificationRecipients` | resolving `role:<slug>` / `self` / UUID recipients to `people.id` |
+
+## Observability & audit
+
+| Module | Exports | Import when |
+|---|---|---|
+| `logging.ts` | `withAdminLogging`, `logAdminDataOperation`, `resolveLogLevels`, `resolveAppUuid`, `LogLevel` | wrapping handlers with the instance log-level-aware logging pipeline |
+| `audit.ts` | `emitAudit`, `emitLog`, `emitSpan`, `emitActivity` | writing structured log/audit/span rows into `public.logs` |
+| `tracing.ts` | `newTrace`, `startSpan`, `endSpan`, `withSpan(Sync)`, `traceDb`, `formatTraceParent/State`, `parseTraceParent/State`, `generateTraceId/SpanId`, `isSampled` | W3C trace-context propagation and span wrapping of DB calls |
+| `outcomes.ts` | `emitOutcome` | recording outcome audit rows |
+
+## Security
+
+| Module | Exports | Import when |
+|---|---|---|
+| `hash-api-key.ts` | `hashApiKey`, `verifyApiKey`, `omitSecretFields` | minting/verifying API keys (`pbkdf2$iter$salt$hash`, 100k sha256); stripping key material from responses |
+| `rate-limit.ts` | `checkRateLimit`, `resolveRateLimitPolicies`, `RateLimitError`, `RateLimitPolicy` | enforcing `config.rate_limits` policies via the atomic `rate_limit_hit` RPC |
+| `security.ts` | `isBlockedRequest`, `isBlockedIp`, `checkTypeSlugRateLimit`, `detectInjection`, `emitSecurityEvent`, `getAppSecurityConfig`, `checkRegistrationBlocklist`, `touchPersonGeo`, `INJECTION_PATTERNS` | blocklist checks, per-type-slug rate limits, prompt-injection screening |
+| `geo.ts` | `getClientGeo`, `ClientGeo` | best-effort client IP/geo from request headers |
+
+## Integrations & webhooks
+
+| Module | Exports | Import when |
+|---|---|---|
+| `resolve-credentials.ts` | `resolveCredential`, `resolveCredentials`, `ResolvedCredential` | resolving `integrations.config.credentials` (`value` literal or `env_var` lookup) server-side |
+| `webhook-registration.ts` | `registerWebhookHandler`, `deregisterWebhookHandler`, `isHandlerRegistered` | self-registering a custom function as a webhook handler (`webhook_handlers` upsert) |
+| `webhook-registry.ts` | `lookupHandler`, `resolveHandler`, `loadHandler`, `listRegisteredHandlers`, `clearHandlerCache` | resolving which registered handler receives an inbound event |
+| `retry-deliveries.ts` | `retryPendingDeliveries` | sweeping due `webhook_deliveries` rows for retry |
+
+## Knowledge & LLM
+
+| Module | Exports | Import when |
+|---|---|---|
+| `kb.ts` | `kbIngest`, `kbPublish`, `kbReindex`, `kbRevoke`, `kbSearch`, `resolveKnowledgeScope`, `knowledgeRowAllowed`, `resolveSecurityLevel`, `matchItemType`, `KnowledgeScope`, `KnowledgeEnvelope` | ingesting/searching embeddings with scope + security-level enforcement |
+| `llm.ts` | `callOpenAI`, `callOpenAIChat`, `callOpenAIEmbeddings`, `callEmbeddingApi`, `LlmContext` | thin wrappers over the `openai` outbound integration |
+| `funnel.ts` | `emitSignal`, `accountDataFlag`, `SignalInput` | emitting typed funnel/signal events that can fire triggers |
+| `access.ts` | `hasInternalAudience`, `projectMessageForCustomer`, `INTERNAL_AUDIENCE_ROLES`, `CUSTOMER_STEP_TYPES` | deciding whether a principal may read `visibility: 'internal'` rows and projecting customer-safe message shapes |
+
+## Framework internals
+
+| Module | Purpose |
+|---|---|
+| `app-manifest.ts` | `loadManifest`, `mergeWithManifest`, `discoverManifests`, `clearManifestCache` — `manifest.json` loading for app rows with `config_source = 'manifest'` |
+| `ast.ts` | `extractIdentities` — TypeScript compiler API for code-analysis pipelines |
+| `cil.ts` | stable-id generation, content hashing, file-tree helpers for the code-intelligence pipeline — not needed by custom apps |
+| `testing.ts` | `mockEvent`, `mockPrincipal`, `makeTestContext`, `expectSuccessResponse`, `expectErrorResponse`, `setupTests` — function-level test harness |
+
+## Usage notes
+
+- `ctx.db` is already the right client for the request's principal — humans
+  get an RLS-scoped client, machines get `adminDb`. Reach for `adminDb`
+  directly only when you must deliberately bypass RLS (system writes,
+  cross-account lookups like `types`/`accounts` resolution).
+- Never `JSON.stringify(ctx.principal)` — `authContext.jwt` rides on it; use
+  `formatPrincipalForAudit`.
+- Circular-import hazards are real in this layer (`middleware → security →
+  rate-limit → funnel → trigger-engine → pipeline-runner → kb → llm →
+  integration-outbound → admin-data → middleware`); some modules import
+  lazily on purpose — copy that pattern rather than adding a static edge.
+
+## Related
+
+- [admin-data](api/admin-data.md) · [Authentication](api/auth.md) · [Errors and Envelopes](api/errors-and-envelopes.md)
+- [Design Schema](design-schema.md) · [Database](database.md)

package/.framework/src/instructions/reference/spine-config.md

@@ -0,0 +1,114 @@
+---
+title: spine.config.json Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/schemas/spine.config.schema.json
+  - .framework/templates/spine.config.neutral.json
+  - .framework/src/lib/branding.ts
+  - .framework/src/hooks/useBranding.ts
+  - .framework/cli/commands/install-app.ts
+---
+
+# `spine.config.json` Reference
+
+`spine.config.json` is the per-project instance config. It lives at the
+project root and is served to the browser as a static public asset — the
+frontend fetches `/spine.config.json`. **Everything in it is client-visible;
+never put secrets here.** The JSON Schema is
+`.framework/schemas/spine.config.schema.json`; the neutral starting point is
+`.framework/templates/spine.config.neutral.json`.
+
+```json
+{
+  "branding": {
+    "app_name": "My Product",
+    "title": "My Product",
+    "logo_url": "/logo.svg",
+    "favicon_url": "/favicon.svg"
+  },
+  "registration": {
+    "default_app": "my-app",
+    "default_role": "member",
+    "allow_url_override": false,
+    "default_app_by_role": { "support": "my-app" },
+    "apps": {
+      "my-app": {
+        "roles": ["member", "member_admin"],
+        "default_role": "member_admin",
+        "path": "/my-app",
+        "enabled": true,
+        "account_strategy": "new",
+        "parent_account": "spine-system"
+      }
+    }
+  }
+}
+```
+
+## `branding`
+
+Read by `.framework/src/lib/branding.ts` (`loadBranding` fetches
+`/spine.config.json` and caches it) and applied to framework-owned pages —
+login, register, setup, sidebars — plus `document.title` and the favicon via
+`useBranding` (`.framework/src/hooks/useBranding.ts`). All keys optional;
+an absent block falls back to Spine defaults.
+
+| Key | Default | Effect |
+|---|---|---|
+| `app_name` | `"Spine"` | display name in headings and logo alt text |
+| `title` | `app_name` (or `"Spine Framework"`) | `document.title` and sidebar wordmark |
+| `logo_url` | `"/spine-logo.svg"` | public asset path for the brand logo |
+| `favicon_url` | `"/spine-logo.svg"` | swapped into `link[rel=icon]` at runtime |
+
+## `registration`
+
+Consumed by the registration/login pages and kept in sync with
+`apps.config.registration` by the installer (`syncAppRegistration` and
+`updateRegistrationConfig` in `.framework/cli/commands/install-app.ts` — the
+DB write lands first, then the file).
+
+| Key | Type | Effect |
+|---|---|---|
+| `default_app` | string (app slug) | where registrants land when no role rule matches; auto-set to the first enabled app when absent |
+| `default_role` | string (role slug) | role assigned when the app entry has no `default_role` |
+| `allow_url_override` | boolean | allow a `?app=`/`?role=` URL override at registration; installer sets `true` when undefined |
+| `default_app_by_role` | `{role: appSlug}` | per-role landing-app map |
+| `apps` | `{appSlug: AppEntry}` | per-app registration policy, see below |
+
+### `registration.apps.<slug>`
+
+| Key | Type | Effect |
+|---|---|---|
+| `roles` | string[] | roles registrants may be placed into through this app |
+| `default_role` | string | role assigned by default |
+| `path` | string | redirect path after registration completes |
+| `enabled` | boolean | `true` opens self-service registration for this app; explicit `false` persists a disabled policy |
+| `account_strategy` | `"new" \| "existing"` | create a new account or join `target_account` |
+| `parent_account` | string | account slug new accounts are parented under (e.g. `spine-system`) |
+| `target_account` | string (uuid) | account to join under `existing` strategy |
+| `default_workspace_name` | string | name for the workspace created at registration |
+| `allow_domain_join` | boolean | allow signups whose email domain matches an existing account to join it |
+
+## File vs. schema notes
+
+- `additionalProperties: true` at the root — extra top-level keys are allowed
+  and preserved.
+- `loadSpineConfig` throws on malformed JSON, a non-object root, a non-object
+  `registration`, or a non-object `registration.apps`; a missing file returns
+  `{registration: {apps: {}}}`.
+- The installer writes `registration.apps.<slug>` and `default_app`/`default_role`
+  when an app manifest declares `registration.enabled: true` — see
+  [App Manifest](app-manifest.md).
+- `.framework/public/spine.config.json` is the framework's copy of the served
+  asset; the project root file is what `init` scaffolds and the frontend
+  actually fetches at runtime.
+
+## Related files
+
+- `.framework/schemas/spine.config.schema.json` — validation schema
+- `.framework/templates/spine.config.neutral.json` — minimal valid config
+- `.framework/src/lib/branding.ts` — branding resolution and defaults
+- `.framework/cli/commands/install-app.ts` — `loadSpineConfig`, `saveSpineConfig`, `updateRegistrationConfig`