spine-framework 0.4.4 → 0.5.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (305) hide show
  1. package/.env.example +13 -3
  2. package/.framework/cli/commands/bootstrap.ts +392 -0
  3. package/.framework/cli/commands/dev.ts +91 -218
  4. package/.framework/cli/commands/doctor.ts +132 -26
  5. package/.framework/cli/commands/generate.ts +38 -298
  6. package/.framework/cli/commands/init.ts +20 -1
  7. package/.framework/cli/commands/install-app.ts +183 -13
  8. package/.framework/cli/commands/migrate.ts +36 -30
  9. package/.framework/cli/commands/migrations.ts +16 -56
  10. package/.framework/cli/commands/upgrade.ts +35 -0
  11. package/.framework/cli/commands/validate-app.ts +127 -1
  12. package/.framework/cli/commands/validate-schema.ts +147 -0
  13. package/.framework/cli/context.ts +223 -110
  14. package/.framework/cli/index.ts +6 -0
  15. package/.framework/cli/lib/project-files.ts +241 -1
  16. package/.framework/functions/_shared/app-manifest.ts +2 -0
  17. package/.framework/functions/_shared/hash-api-key.ts +183 -79
  18. package/.framework/functions/_shared/logging.ts +562 -224
  19. package/.framework/functions/_shared/middleware.ts +47 -44
  20. package/.framework/functions/_shared/permissions.ts +4 -0
  21. package/.framework/functions/admin-data.ts +51 -28
  22. package/.framework/functions/ai-agents.ts +10 -6
  23. package/.framework/functions/api-keys.ts +301 -122
  24. package/.framework/functions/apps.ts +63 -29
  25. package/.framework/functions/cil-ingest.ts +48 -15
  26. package/.framework/functions/debug-auth.ts +14 -8
  27. package/.framework/functions/deliveries.ts +39 -12
  28. package/.framework/functions/embeddings.ts +149 -78
  29. package/.framework/functions/integration-outbound.ts +67 -27
  30. package/.framework/functions/integrations.ts +254 -127
  31. package/.framework/functions/logs.ts +273 -133
  32. package/.framework/functions/observability.ts +278 -148
  33. package/.framework/functions/pipeline-executions.ts +1 -1
  34. package/.framework/functions/pipelines.ts +14 -9
  35. package/.framework/functions/prompt-configs.ts +7 -4
  36. package/.framework/functions/roles.ts +8 -5
  37. package/.framework/functions/security.ts +30 -17
  38. package/.framework/functions/system-cron.ts +240 -127
  39. package/.framework/functions/tests.ts +7 -6
  40. package/.framework/functions/timers.ts +310 -107
  41. package/.framework/functions/triggers.ts +28 -13
  42. package/.framework/functions/types.ts +13 -10
  43. package/.framework/migrations/069_log_stats_window.sql +54 -0
  44. package/.framework/migrations/070_app_type_schema_rpcs.sql +166 -0
  45. package/.framework/migrations/071_timer_interval_keys.sql +96 -0
  46. package/.framework/migrations/072_slug_autofill.sql +77 -0
  47. package/.framework/migrations/073_seed_member_roles.sql +26 -0
  48. package/.framework/migrations/074_app_route_prefix_domains.sql +168 -0
  49. package/.framework/migrations/075_security_definer_grants.sql +157 -0
  50. package/.framework/src/apps/admin/index.tsx +1141 -775
  51. package/.framework/src/components/ErrorBoundary.tsx +136 -0
  52. package/.framework/src/components/admin/AdminListPage.tsx +81 -73
  53. package/.framework/src/components/admin/AdminSidebar.tsx +88 -79
  54. package/.framework/src/components/admin/EntitySelect.tsx +181 -0
  55. package/.framework/src/components/admin/PageInstructions.tsx +86 -127
  56. package/.framework/src/components/app-shell/GenericDetailPage.tsx +37 -13
  57. package/.framework/src/components/app-shell/GenericListPage.tsx +28 -32
  58. package/.framework/src/components/layout/Sidebar.tsx +300 -177
  59. package/.framework/src/components/runtime/DataDetailPage.tsx +67 -35
  60. package/.framework/src/components/runtime/DataHeader.tsx +96 -48
  61. package/.framework/src/components/runtime/DataListPage.tsx +3 -26
  62. package/.framework/src/components/runtime/DataStats.tsx +10 -10
  63. package/.framework/src/components/runtime/DataTable.tsx +12 -10
  64. package/.framework/src/components/ui/sheet.tsx +24 -26
  65. package/.framework/src/components/ui/textarea.tsx +74 -48
  66. package/.framework/src/contexts/AppContext.tsx +5 -12
  67. package/.framework/src/contexts/AuthContext.tsx +17 -9
  68. package/.framework/src/hooks/useApps.ts +18 -22
  69. package/.framework/src/hooks/useEntityList.ts +12 -9
  70. package/.framework/src/hooks/useListSchema.ts +108 -58
  71. package/.framework/src/instructions/README.md +74 -0
  72. package/.framework/src/instructions/accounts.md +97 -0
  73. package/.framework/src/instructions/ai-agents.md +69 -0
  74. package/.framework/src/instructions/alerts.md +80 -0
  75. package/.framework/src/instructions/api-keys.md +87 -0
  76. package/.framework/src/instructions/apps.md +77 -0
  77. package/.framework/src/instructions/concepts/ai-and-prompts.md +150 -0
  78. package/.framework/src/instructions/concepts/apps-and-renderers.md +228 -0
  79. package/.framework/src/instructions/concepts/auth-and-api-keys.md +133 -0
  80. package/.framework/src/instructions/concepts/automation.md +186 -0
  81. package/.framework/src/instructions/concepts/concurrency-and-idempotency.md +125 -0
  82. package/.framework/src/instructions/concepts/core-vs-custom.md +124 -0
  83. package/.framework/src/instructions/concepts/design-schema.md +152 -0
  84. package/.framework/src/instructions/concepts/integrations-and-webhooks.md +127 -0
  85. package/.framework/src/instructions/concepts/observability.md +116 -0
  86. package/.framework/src/instructions/concepts/permissions.md +150 -0
  87. package/.framework/src/instructions/concepts/runtime-records.md +111 -0
  88. package/.framework/src/instructions/concepts/scope-and-accounts.md +112 -0
  89. package/.framework/src/instructions/concepts/spine-way.md +172 -0
  90. package/.framework/src/instructions/deliveries.md +59 -0
  91. package/.framework/src/instructions/guide/00-orientation.md +106 -0
  92. package/.framework/src/instructions/guide/01-install-and-first-run.md +253 -0
  93. package/.framework/src/instructions/guide/02-project-map.md +147 -0
  94. package/.framework/src/instructions/guide/03-domain-model.md +223 -0
  95. package/.framework/src/instructions/guide/04-first-app.md +227 -0
  96. package/.framework/src/instructions/guide/05-glossary.md +183 -0
  97. package/.framework/src/instructions/integrations.md +96 -0
  98. package/.framework/src/instructions/internal/cil-markers.md +83 -0
  99. package/.framework/src/instructions/internal/docs-contract.md +158 -0
  100. package/.framework/src/instructions/invites.md +60 -0
  101. package/.framework/src/instructions/kb.md +80 -0
  102. package/.framework/src/instructions/logs.md +77 -0
  103. package/.framework/src/instructions/notifications.md +77 -0
  104. package/.framework/src/instructions/observability.md +61 -0
  105. package/.framework/src/instructions/operations/deployment.md +115 -0
  106. package/.framework/src/instructions/operations/migrations.md +125 -0
  107. package/.framework/src/instructions/operations/security-checklist.md +170 -0
  108. package/.framework/src/instructions/operations/troubleshooting.md +170 -0
  109. package/.framework/src/instructions/operations/upgrade.md +116 -0
  110. package/.framework/src/instructions/people.md +91 -0
  111. package/.framework/src/instructions/pipeline-executions.md +62 -0
  112. package/.framework/src/instructions/pipelines.md +78 -0
  113. package/.framework/src/instructions/prompts.md +95 -0
  114. package/.framework/src/instructions/reference/api/admin-data.md +162 -0
  115. package/.framework/src/instructions/reference/api/auth.md +113 -0
  116. package/.framework/src/instructions/reference/api/errors-and-envelopes.md +113 -0
  117. package/.framework/src/instructions/reference/app-manifest.md +184 -0
  118. package/.framework/src/instructions/reference/cli.md +124 -0
  119. package/.framework/src/instructions/reference/database.md +132 -0
  120. package/.framework/src/instructions/reference/design-schema.md +280 -0
  121. package/.framework/src/instructions/reference/env-vars.md +133 -0
  122. package/.framework/src/instructions/reference/frontend-sdk.md +207 -0
  123. package/.framework/src/instructions/reference/functions/account-nodes.md +75 -0
  124. package/.framework/src/instructions/reference/functions/admin-data.md +197 -0
  125. package/.framework/src/instructions/reference/functions/admin-funnel.md +90 -0
  126. package/.framework/src/instructions/reference/functions/admin-install-funnel.md +107 -0
  127. package/.framework/src/instructions/reference/functions/admin-signals.md +102 -0
  128. package/.framework/src/instructions/reference/functions/ai-agents.md +148 -0
  129. package/.framework/src/instructions/reference/functions/ai-interactions.md +156 -0
  130. package/.framework/src/instructions/reference/functions/api-keys.md +130 -0
  131. package/.framework/src/instructions/reference/functions/apps.md +140 -0
  132. package/.framework/src/instructions/reference/functions/auth.md +99 -0
  133. package/.framework/src/instructions/reference/functions/debug-auth.md +91 -0
  134. package/.framework/src/instructions/reference/functions/deliveries.md +110 -0
  135. package/.framework/src/instructions/reference/functions/embeddings.md +166 -0
  136. package/.framework/src/instructions/reference/functions/eval-harness.md +149 -0
  137. package/.framework/src/instructions/reference/functions/index.md +103 -0
  138. package/.framework/src/instructions/reference/functions/integration-outbound.md +200 -0
  139. package/.framework/src/instructions/reference/functions/integration-routes.md +151 -0
  140. package/.framework/src/instructions/reference/functions/integrations.md +130 -0
  141. package/.framework/src/instructions/reference/functions/invites.md +182 -0
  142. package/.framework/src/instructions/reference/functions/item-progress.md +107 -0
  143. package/.framework/src/instructions/reference/functions/kb.md +166 -0
  144. package/.framework/src/instructions/reference/functions/logs.md +141 -0
  145. package/.framework/src/instructions/reference/functions/observability.md +105 -0
  146. package/.framework/src/instructions/reference/functions/pipeline-executions.md +132 -0
  147. package/.framework/src/instructions/reference/functions/pipeline-runner-background.md +121 -0
  148. package/.framework/src/instructions/reference/functions/pipelines.md +136 -0
  149. package/.framework/src/instructions/reference/functions/prompt-configs.md +121 -0
  150. package/.framework/src/instructions/reference/functions/roles.md +121 -0
  151. package/.framework/src/instructions/reference/functions/security.md +140 -0
  152. package/.framework/src/instructions/reference/functions/system-cron.md +136 -0
  153. package/.framework/src/instructions/reference/functions/system.md +106 -0
  154. package/.framework/src/instructions/reference/functions/tests.md +97 -0
  155. package/.framework/src/instructions/reference/functions/timers.md +117 -0
  156. package/.framework/src/instructions/reference/functions/trigger-scheduler.md +102 -0
  157. package/.framework/src/instructions/reference/functions/triggers.md +140 -0
  158. package/.framework/src/instructions/reference/functions/types.md +146 -0
  159. package/.framework/src/instructions/reference/seeds.md +126 -0
  160. package/.framework/src/instructions/reference/shared-modules.md +127 -0
  161. package/.framework/src/instructions/reference/spine-config.md +114 -0
  162. package/.framework/src/instructions/roles.md +80 -0
  163. package/.framework/src/instructions/runtime-collaboration.md +106 -0
  164. package/.framework/src/instructions/runtime-detail.md +70 -0
  165. package/.framework/src/instructions/runtime-list.md +77 -0
  166. package/.framework/src/instructions/security.md +67 -0
  167. package/.framework/src/instructions/tasks/add-a-pipeline.md +110 -0
  168. package/.framework/src/instructions/tasks/add-a-role.md +96 -0
  169. package/.framework/src/instructions/tasks/add-a-timer.md +114 -0
  170. package/.framework/src/instructions/tasks/add-a-trigger.md +106 -0
  171. package/.framework/src/instructions/tasks/add-a-type.md +151 -0
  172. package/.framework/src/instructions/tasks/add-a-webhook.md +108 -0
  173. package/.framework/src/instructions/tasks/add-an-ai-agent.md +108 -0
  174. package/.framework/src/instructions/tasks/add-an-integration.md +124 -0
  175. package/.framework/src/instructions/tasks/build-a-custom-page.md +118 -0
  176. package/.framework/src/instructions/tasks/document-your-app.md +117 -0
  177. package/.framework/src/instructions/tasks/package-and-install-an-app.md +136 -0
  178. package/.framework/src/instructions/tasks/register-an-app.md +137 -0
  179. package/.framework/src/instructions/tasks/test-your-code.md +108 -0
  180. package/.framework/src/instructions/tasks/write-a-function.md +132 -0
  181. package/.framework/src/instructions/tasks/write-a-migration.md +110 -0
  182. package/.framework/src/instructions/testing.md +59 -0
  183. package/.framework/src/instructions/timers.md +84 -0
  184. package/.framework/src/instructions/triggers.md +69 -0
  185. package/.framework/src/instructions/types.md +93 -0
  186. package/.framework/src/lib/app-mount.ts +88 -0
  187. package/.framework/src/pages/NotFoundPage.tsx +62 -31
  188. package/.framework/src/pages/admin/AIAgentDetailPage.tsx +117 -106
  189. package/.framework/src/pages/admin/AIAgentsPage.tsx +86 -48
  190. package/.framework/src/pages/admin/APIKeyDetailPage.tsx +153 -152
  191. package/.framework/src/pages/admin/APIKeysPage.tsx +91 -90
  192. package/.framework/src/pages/admin/AlertsConfigPage.tsx +29 -18
  193. package/.framework/src/pages/admin/AppDetailPage.tsx +6 -60
  194. package/.framework/src/pages/admin/AppsPage.tsx +104 -66
  195. package/.framework/src/pages/admin/DeliveriesPage.tsx +5 -5
  196. package/.framework/src/pages/admin/EmbeddingDetailPage.tsx +5 -23
  197. package/.framework/src/pages/admin/EmbeddingsPage.tsx +5 -26
  198. package/.framework/src/pages/admin/IntegrationDetailPage.tsx +7 -7
  199. package/.framework/src/pages/admin/IntegrationsPage.tsx +85 -43
  200. package/.framework/src/pages/admin/LogsPage.tsx +144 -76
  201. package/.framework/src/pages/admin/ObservabilityDashboard.tsx +223 -140
  202. package/.framework/src/pages/admin/PipelineDetailPage.tsx +134 -113
  203. package/.framework/src/pages/admin/PipelineExecutionsPage.tsx +108 -45
  204. package/.framework/src/pages/admin/PipelinesPage.tsx +160 -115
  205. package/.framework/src/pages/admin/PromptConfigDetailPage.tsx +96 -98
  206. package/.framework/src/pages/admin/PromptConfigsPage.tsx +101 -59
  207. package/.framework/src/pages/admin/RoleDetailPage.tsx +90 -79
  208. package/.framework/src/pages/admin/RolesPage.tsx +86 -43
  209. package/.framework/src/pages/admin/SecurityPage.tsx +1 -1
  210. package/.framework/src/pages/admin/TestingDashboard.tsx +16 -28
  211. package/.framework/src/pages/admin/TimerDetailPage.tsx +117 -100
  212. package/.framework/src/pages/admin/TimersPage.tsx +90 -62
  213. package/.framework/src/pages/admin/TriggerDetailPage.tsx +90 -83
  214. package/.framework/src/pages/admin/TriggersPage.tsx +124 -99
  215. package/.framework/src/pages/admin/TypeDetailPage.tsx +152 -138
  216. package/.framework/src/pages/admin/TypesPage.tsx +90 -48
  217. package/.framework/src/pages/admin/cil/CILAgentPage.tsx +17 -25
  218. package/.framework/src/pages/admin/cil/CILChunkDetailPage.tsx +17 -27
  219. package/.framework/src/pages/admin/cil/CILDashboardPage.tsx +72 -40
  220. package/.framework/src/pages/admin/cil/CILFileListPage.tsx +321 -129
  221. package/.framework/src/pages/admin/cil/CILFileSelectPage.tsx +18 -29
  222. package/.framework/src/pages/admin/cil/CILGraphPage.tsx +26 -38
  223. package/.framework/src/pages/admin/cil/CILIngestionPage.tsx +34 -46
  224. package/.framework/src/pages/admin/cil/CILProjectsPage.tsx +189 -103
  225. package/.framework/src/pages/admin/cil/CILSearchPage.tsx +246 -136
  226. package/.framework/src/pages/admin/cil/CILSuggestionsPage.tsx +11 -22
  227. package/.framework/src/pages/admin/cil/CILVersionsPage.tsx +9 -20
  228. package/.framework/src/pages/admin/cil/FlexiblePipelinePage.tsx +26 -38
  229. package/.framework/src/pages/admin/kb/KBAdminPage.tsx +7 -26
  230. package/.framework/src/pages/auth/LoginPage.tsx +3 -2
  231. package/.framework/src/pages/auth/RegisterPage.tsx +16 -8
  232. package/.framework/templates/agent/AGENTS.md +167 -0
  233. package/.framework/templates/agent/skills/spine-add-ai-agent/SKILL.md +58 -0
  234. package/.framework/templates/agent/skills/spine-add-automation/SKILL.md +62 -0
  235. package/.framework/templates/agent/skills/spine-add-integration/SKILL.md +63 -0
  236. package/.framework/templates/agent/skills/spine-architect/SKILL.md +86 -0
  237. package/.framework/templates/agent/skills/spine-install-app/SKILL.md +79 -0
  238. package/.framework/templates/agent/skills/spine-migration/SKILL.md +75 -0
  239. package/.framework/templates/agent/skills/spine-new-app/SKILL.md +79 -0
  240. package/.framework/templates/agent/skills/spine-new-function/SKILL.md +71 -0
  241. package/.framework/templates/agent/skills/spine-new-type/SKILL.md +72 -0
  242. package/.framework/templates/agent/skills/spine-schema/SKILL.md +77 -0
  243. package/.framework/templates/agent/skills/spine-test/SKILL.md +67 -0
  244. package/.framework/templates/agent/skills/spine-troubleshoot/SKILL.md +74 -0
  245. package/.framework/templates/agent/skills/spine-upgrade/SKILL.md +69 -0
  246. package/.framework/templates/project.json +4 -1
  247. package/.framework/tests/unit/account-scoping-gates.test.ts +394 -0
  248. package/.framework/tests/unit/agent-files.test.ts +355 -0
  249. package/.framework/tests/unit/agent-runner.test.ts +479 -44
  250. package/.framework/tests/unit/api-keys-create-scope-gate.test.ts +160 -0
  251. package/.framework/tests/unit/api-keys-omit-secret-fields.test.ts +38 -0
  252. package/.framework/tests/unit/app-mount.test.ts +80 -0
  253. package/.framework/tests/unit/bootstrap.test.ts +242 -0
  254. package/.framework/tests/unit/cli-context-api-key.test.ts +114 -0
  255. package/.framework/tests/unit/debug-auth.test.ts +38 -0
  256. package/.framework/tests/unit/deliveries-account-scoping.test.ts +185 -0
  257. package/.framework/tests/unit/integration-outbound-credentials.test.ts +167 -0
  258. package/.framework/tests/unit/integrations-audit-redaction.test.ts +130 -0
  259. package/.framework/tests/unit/logging-app-id.test.ts +75 -0
  260. package/.framework/tests/unit/security-definer-grants.test.ts +154 -0
  261. package/.framework/tests/unit/system-context-denial.test.ts +145 -0
  262. package/.framework/tests/unit/system-cron.test.ts +240 -0
  263. package/.framework/tests/unit/timers.test.ts +159 -0
  264. package/README.md +125 -166
  265. package/config/tsconfig.cli.json +2 -2
  266. package/package.json +15 -4
  267. package/templates/project/package-lock.json +2 -2
  268. package/.framework/docs/admin-routes.md +0 -76
  269. package/.framework/docs/api-docs-progress.md +0 -38
  270. package/.framework/docs/api-governance.md +0 -146
  271. package/.framework/docs/api-testing-results.md +0 -212
  272. package/.framework/docs/assembly-launch-guide.md +0 -138
  273. package/.framework/docs/audit-results.md +0 -590
  274. package/.framework/docs/db-api-inventory.md +0 -95
  275. package/.framework/docs/gap-remediation-backlog.md +0 -103
  276. package/.framework/docs/ui-adoption-verification.md +0 -111
  277. package/.framework/docs/ui-api-coverage.md +0 -84
  278. package/.framework/docs/v2-compatibility-audit.md +0 -228
  279. package/.framework/mcp/index.ts +0 -133
  280. package/.framework/mcp/load-env.ts +0 -60
  281. package/.framework/mcp/shared/app-manifest.ts +0 -275
  282. package/.framework/mcp/shared/db.ts +0 -477
  283. package/.framework/mcp/shared/kb.ts +0 -118
  284. package/.framework/mcp/tools/architect.ts +0 -431
  285. package/.framework/mcp/tools/cil/context.ts +0 -345
  286. package/.framework/mcp/tools/cil/graph.ts +0 -242
  287. package/.framework/mcp/tools/cil/ingest.ts +0 -1217
  288. package/.framework/mcp/tools/cil/pipeline-orchestrator.ts +0 -693
  289. package/.framework/mcp/tools/cil/pipeline.ts +0 -767
  290. package/.framework/mcp/tools/cil/project.ts +0 -791
  291. package/.framework/mcp/tools/cil/retrieval.ts +0 -336
  292. package/.framework/mcp/tools/cil/search-core.ts +0 -454
  293. package/.framework/mcp/tools/cil/search.ts +0 -97
  294. package/.framework/mcp/tools/cil/suggest.ts +0 -186
  295. package/.framework/mcp/tools/cil/validate.ts +0 -1369
  296. package/.framework/mcp/tools/kb/delete.ts +0 -139
  297. package/.framework/mcp/tools/kb/index.ts +0 -52
  298. package/.framework/mcp/tools/kb/ingest.ts +0 -84
  299. package/.framework/mcp/tools/kb/list-types.ts +0 -102
  300. package/.framework/mcp/tools/kb/publish.ts +0 -100
  301. package/.framework/mcp/tools/kb/reindex.ts +0 -86
  302. package/.framework/mcp/tools/kb/revoke.ts +0 -85
  303. package/.framework/mcp/tools/kb/search.ts +0 -101
  304. package/.framework/mcp/tools/kb/upsert.ts +0 -125
  305. package/.framework/mcp/tools/observability.ts +0 -510
@@ -0,0 +1,80 @@
1
+ ---
2
+ title: Roles
3
+ audience: both
4
+ kind: entity
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/functions/roles.ts
9
+ - .framework/functions/_shared/permissions.ts
10
+ - .framework/functions/auth.ts
11
+ - .framework/functions/_shared/principal.ts
12
+ - .framework/src/pages/admin/RolesPage.tsx
13
+ - .framework/src/pages/admin/RoleDetailPage.tsx
14
+ - .framework/migrations/003_core_system_data.sql
15
+ ---
16
+
17
+ ## What this is for
18
+
19
+ A **role** is a named principal category assigned to people (`people.role_id`). Its **slug** is what permission evaluation keys on: each type's `design_schema.record_permissions` maps role slugs to the record actions that role may perform. The role's own `permissions` column feeds `principal.permissions` for coarse gates.
20
+
21
+ ## Fields and settings
22
+
23
+ - **Name** — string, required. Display label (e.g. "Support Manager"); `slug` and `name` are the API's required fields.
24
+ - **Slug** — string, required, unique per app. **Disabled after creation** because `record_permissions` keys and `people.role_id` references depend on it.
25
+ - **Description** — string, optional.
26
+ - **System Role** — checkbox, create-only. Reserved roles can't be deleted and are protected for core functions.
27
+ - **Active** — checkbox. Inactive roles can't be assigned to people.
28
+ - **Permissions (JSON)** — the form suggests an object mapping type slugs to action arrays (`{ "ticket": ["create","read"] }`), but the permission engine does **not** evaluate this column for record access — see Downstream effects. A **flat array** form (`["read","write","admin","system"]`) is what `auth.ts` copies into `principal.permissions`.
29
+
30
+ **Downstream effects**
31
+
32
+ - Record CRUD is governed by each type's `design_schema.record_permissions`, keyed by **role slug** — e.g. `"record_permissions": { "support-agent": ["read"] }`. Assigning a person a role takes effect immediately (the engine resolves `people.role_id → roles.slug` per request, short cache).
33
+ - `record_permissions` keys are matched **verbatim** against `roles.slug` — `system-admin` is a dead key that silently denies the real `system_admin` role. The `all` key is a wildcard granting every authenticated principal.
34
+ - `auth.ts` copies `role.permissions` into `principal.permissions` **only when it is a flat array** (`system_admin` is hardcoded to `["read","write","admin","system"]`). `principal.permissions` backs coarse checks like the invites `system` gate — not per-record access.
35
+ - Malformed permissions don't lock anyone out of records (the column isn't read for that) — a wrong `record_permissions` slug on the type does.
36
+ - Creating a role with slug `system_admin` is restricted to `system_admin` principals.
37
+
38
+ ## Minimal configuration
39
+
40
+ ```json
41
+ {
42
+ "name": "Support Agent",
43
+ "slug": "support-agent",
44
+ "is_active": true,
45
+ "permissions": { "ticket": ["create", "read", "update"] }
46
+ }
47
+ ```
48
+
49
+ ## Full configuration
50
+
51
+ ```json
52
+ {
53
+ "name": "Support Manager",
54
+ "slug": "support-manager",
55
+ "is_active": true,
56
+ "is_system": false,
57
+ "permissions": { "ticket": ["create", "read", "update", "delete"] },
58
+ "metadata": { "department": "support" }
59
+ }
60
+ ```
61
+
62
+ Both examples use the object form the UI suggests — it is stored as documentation/delegated-policy data. Record access still comes from each type's `record_permissions` under the same slug.
63
+
64
+ ## Example
65
+
66
+ A support app ships three roles: `support-agent`, `support-manager`, and `support-viewer`. On the `ticket` type, `record_permissions` grants `support-agent` `["create","read","update"]`, `support-manager` all four actions, and `support-viewer` `["read"]`; assignment happens on `people` records via `role_id`.
67
+
68
+ ## Core files
69
+
70
+ - `.framework/functions/roles.ts` — API (list/get/create/update/delete; `system_admin` slug creation gated)
71
+ - `.framework/functions/_shared/permissions.ts` — `record_permissions`/`fields.*.permissions` evaluation (role-slug keyed; `all` wildcard)
72
+ - `.framework/functions/auth.ts` / `.framework/functions/_shared/principal.ts` — `role.permissions` → `principal.permissions` (flat array only)
73
+ - `.framework/src/pages/admin/RolesPage.tsx` / `RoleDetailPage.tsx` — admin UI
74
+ - Table: `public.roles`; assignment on `public.people.role_id`
75
+
76
+ ## Agent notes
77
+
78
+ - The Permissions textarea's own placeholder shows the object form — know that it is not what gates records. The gate is `record_permissions[role_slug]` on the type.
79
+ - Slug is immutable after create; rename = new role + reassignment. Never introduce a hyphenated `system-admin` slug — seeded slugs use underscores.
80
+ - The seeded `system_admin` role must stay assigned for admin functions; `auth.ts` hardcodes its principal permissions, it is not data-driven.
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: Collaboration records (threads, messages, links, attachments, watchers)
3
+ audience: both
4
+ kind: entity
5
+ verified_against: b3b3ae0
6
+ verified_on: 2026-11-01
7
+ source_files:
8
+ - .framework/migrations/001_core_schema.sql
9
+ - .framework/functions/admin-data.ts
10
+ - .framework/functions/_shared/notify.ts
11
+ - .framework/src/instructions/reference/database.md
12
+ ---
13
+
14
+ # Collaboration records
15
+
16
+ ## What this is for
17
+
18
+ Five runtime record kinds give any typed record a social layer: a ticket
19
+ gets a conversation (`threads`/`messages`), relationships to other records
20
+ (`links`), files (`attachments`), and subscribers who get notified
21
+ (`watchers`). They are ordinary typed records — created and read through
22
+ `/api/admin-data` like everything else — but their shapes and uniqueness
23
+ rules are fixed.
24
+
25
+ ## Fields and settings
26
+
27
+ ### `threads` — conversation containers
28
+
29
+ | Column | Notes |
30
+ |---|---|
31
+ | `type_id`, `title` | Typed record fields. |
32
+ | `target_type`, `target_id` | The record this thread is attached to (polymorphic — e.g. `item` + item id). |
33
+ | `visibility` | `internal` / `external` / `public` — who may see the conversation. |
34
+ | `status` | open/closed lifecycle. |
35
+ | UNIQUE `(target_type, target_id, visibility)` | **One thread per visibility per record** — find-or-create is the required pattern (see Agent notes). |
36
+
37
+ ### `messages` — posts inside threads
38
+
39
+ | Column | Notes |
40
+ |---|---|
41
+ | `thread_id` | required parent thread. |
42
+ | `type_id`, `content` | Typed content; the body. |
43
+ | `direction` | inbound/outbound. |
44
+ | `person_id` | author (`people.id`). |
45
+ | `visibility` | mirrors thread visibility. |
46
+ | `sequence` | ordering; UNIQUE `(thread_id, sequence)` — assign next = max+1. |
47
+
48
+ ### `links` — typed edges
49
+
50
+ | Column | Notes |
51
+ |---|---|
52
+ | `link_type_id`, `link_type` | FK + denormalized slug from `link_types` (`source_kind`/`target_kind` constrain valid endpoints). |
53
+ | `source_type`/`source_id`, `target_type`/`target_id` | Polymorphic endpoints; UNIQUE edge constraint prevents duplicates. |
54
+
55
+ ### `attachments` — files
56
+
57
+ `filename`, `file_size`, `mime_type`, `storage_path`, `storage_provider`,
58
+ `uploaded_by`. The file bytes live in storage; the row is metadata.
59
+
60
+ ### `watchers` — subscriptions
61
+
62
+ | Column | Notes |
63
+ |---|---|
64
+ | `target_type`, `target_id`, `person_id` | Who watches what; UNIQUE across all three. |
65
+ | `watch_type` | subscription kind. |
66
+ | `notification_level` | how much to notify. |
67
+
68
+ ## Minimal configuration
69
+
70
+ A conversation on a record needs: one `threads` row (`target_type`,
71
+ `target_id`, `visibility`, `type_id` → a thread kind type) then `messages`
72
+ rows (`thread_id`, `content`, `sequence`, `person_id`).
73
+
74
+ ## Full configuration
75
+
76
+ `links` for record↔record semantics, `attachments` for files, `watchers`
77
+ for per-person notification subscription.
78
+
79
+ ## Example
80
+
81
+ A support ticket (`item`) gets `visibility: 'external'` thread found-or-
82
+ created on first customer message; each reply inserts a `messages` row with
83
+ `sequence = max+1`; staff `watchers` on the ticket get `notifications` via
84
+ the pipeline stage.
85
+
86
+ ## Core files
87
+
88
+ - `.framework/migrations/001_core_schema.sql` — tables + unique constraints
89
+ - `.framework/functions/admin-data.ts` — CRUD path for all five kinds
90
+ - `.framework/functions/_shared/notify.ts` — watcher/recipient resolution
91
+ - [Database reference](reference/database.md) — column-level contract
92
+
93
+ ## Agent notes
94
+
95
+ - **Threads are find-or-create, not create.** The
96
+ `(target_type, target_id, visibility)` unique constraint rejects a second
97
+ same-visibility thread — list first, insert only when absent. Custom apps
98
+ do this via `apiFetch` → `/api/admin-data` (`action=list` then
99
+ `action=create`), never a bespoke function.
100
+ - `messages.sequence` must be computed (`max+1`) — the unique constraint
101
+ will reject collisions, and sequence gaps are fine but duplicates fail.
102
+ - `links` need a seeded `link_types` row first — `link_type` is validated
103
+ against it.
104
+ - All five kinds take `type_id` — seed a `kind: 'thread'`, `'message'`,
105
+ `'link'`, `'attachment'`, `'watcher'` type for each your app uses
106
+ (`conflict: "kind,slug"`, `inject_app_id: false`).
@@ -0,0 +1,70 @@
1
+ ---
2
+ title: Runtime Record (detail)
3
+ audience: both
4
+ kind: ui
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/src/components/runtime/DataDetailPage.tsx
9
+ - .framework/src/hooks/useEntityRecord.ts
10
+ - .framework/src/components/runtime/SchemaDetailForm.tsx
11
+ - .framework/functions/admin-data.ts
12
+ ---
13
+
14
+ ## What this is for
15
+
16
+ **Runtime detail** (`/spine-framework/admin/runtime/:entity/new` and `/runtime/:entity/:id`) is the generic create/view/edit form for one runtime record. It renders sections and fields from the record's stamped `design_schema.views.default_detail` — so any type with a detail view gets a working record page without a custom UI.
17
+
18
+ ## Fields and settings
19
+
20
+ - **Header** — record title (`design_schema.display_field`, falling back through `full_name` → `display_name` → `name` → `title` → `slug` → `email` → "Untitled"), plus Edit / Save / Cancel / Delete buttons. `?edit=true` toggles edit mode; `new` starts in edit mode.
21
+ - **Sections** — `views.default_detail.sections[*]`: each section's `fields` render as form controls per `display_type` (`input`, `textarea`, `select`, `checkbox`, `date_picker`, `json`-as-textarea, ...).
22
+ - **Field values** — `system: true` fields read `record.<field>`; everything else reads `record.data.<field>` and is written back under `data`.
23
+ - **Field permissions** — `fieldPermissions` from the record response gate which inputs are editable (field-level `read`/`write` from `fields.*.permissions` over the record grant).
24
+ - **Delete** — confirm → `admin-data` remove → back to the entity list.
25
+
26
+ **Downstream effects**
27
+
28
+ - All writes go through `/api/admin-data` (`create`/`update`/`remove`): type stamping, `validation_schema` checks, `record_permissions`, and create/update triggers all apply — the same path custom apps must use.
29
+ - Creating a record stamps the type's current `design_schema` onto it — the detail page then renders from that stamped copy (`record.design_schema || record.type.design_schema`).
30
+ - Default `type_slug` per entity on create: `accounts→account`, `people→person`, `items→item`, `threads→thread`, `messages→message`, `links→link`, `attachments→attachment`, `watchers→watcher`, `item_progress→item_progress` — a `typeSlug` route param overrides it.
31
+
32
+ ## Minimal configuration
33
+
34
+ Define `views.default_detail` on the type:
35
+
36
+ ```json
37
+ "default_detail": {
38
+ "type": "detail", "label": "Ticket",
39
+ "sections": [
40
+ { "title": "Core", "fields": {
41
+ "title": { "display_type": "input" },
42
+ "status": { "display_type": "select" }
43
+ } }
44
+ ]
45
+ }
46
+ ```
47
+
48
+ ## Full configuration
49
+
50
+ Split fields across multiple named sections, choose richer `display_type` controls (`textarea`, `select`, `multiselect`, `date_picker`, `checkbox`, `color_picker`, `file_upload`, `range_slider`), and set `display_field` on the schema so the header shows a meaningful title. Field-level `permissions` on `design_schema.fields` restrict which roles can write a field even when the record grant allows updates.
51
+
52
+ ## Example
53
+
54
+ `/spine-framework/admin/runtime/items/<id>?edit=true` renders the ticket: a "Core" section with Title (input), Status (select), Priority (select), and a "Notes" section with a `json` field shown as a monospaced textarea. Save → `admin-data` validates against `validation_schema` and fires `item_updated` triggers.
55
+
56
+ ## Core files
57
+
58
+ - `.framework/src/components/runtime/DataDetailPage.tsx` — this page
59
+ - `.framework/src/components/runtime/SchemaDetailForm.tsx` — renders sections/fields from the schema
60
+ - `.framework/src/components/runtime/DataDetailHeader.tsx` — title + action buttons
61
+ - `.framework/src/hooks/useEntityRecord.ts` — record fetch (`design_schema` fallback), save/delete via `admin-data`
62
+ - `.framework/functions/admin-data.ts` — get/create/update/remove backend
63
+ - `.framework/src/apps/admin/index.tsx` — `instructionKeyFor`: `runtime/:entity/...` (≥4 segments) → `runtime-detail`
64
+
65
+ ## Agent notes
66
+
67
+ - Error card "Failed to load record or schema" = the record has no stamped `design_schema` or the type's `default_detail` view is missing — fix the type's schema, not this page.
68
+ - `system: true` fields (e.g. `title`) are top-level record columns; a field defined in `design_schema.fields` but absent from a section won't render — the form only shows what `default_detail` declares.
69
+ - A record stamped under an old schema renders the old view — re-save it to re-stamp the current schema.
70
+ - `new` with no `typeSlug` uses the default type slug map above; creating a different type's record needs the `typeSlug` route param or a different entry point.
@@ -0,0 +1,77 @@
1
+ ---
2
+ title: Runtime Records (list)
3
+ audience: both
4
+ kind: ui
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/src/components/runtime/DataListPage.tsx
9
+ - .framework/src/hooks/useListSchema.ts
10
+ - .framework/src/hooks/useEntityList.ts
11
+ - .framework/functions/admin-data.ts
12
+ ---
13
+
14
+ ## What this is for
15
+
16
+ **Runtime list** (`/spine-framework/admin/runtime/:entity`) is the generic, schema-driven list page for any runtime entity table — `items`, `threads`, `messages`, `links`, `attachments`, `watchers`, `people`, `accounts`, `item_progress`. It renders whatever the entity's type `design_schema.views.default_list` declares, so every type gets a working admin list for free.
17
+
18
+ ## Fields and settings
19
+
20
+ - **Header** — entity name, description, and a New button → `runtime/:entity/new`.
21
+ - **Stats cards** — driven by `views.default_list.stats` (empty when undeclared).
22
+ - **Filters** — driven by `views.default_list.filters`; values go into the `admin-data` list query.
23
+ - **Columns** — `views.default_list.fields`: label from `design_schema.fields[key].label`, sortable unless `sortable: false`, rendered per `display_type` (`text`, `badge`, `timestamp`, `currency`, ...).
24
+ - **Sort** — defaults to `views.default_list.default_sort` (fallback `created_at` desc); sent as `sort_field`/`sort_direction`.
25
+ - **Rows** — `record.data.<field>` values for non-system fields, `record.<field>` for `system: true` fields.
26
+
27
+ **How the schema is resolved** (`useListSchema`, in order)
28
+
29
+ 1. Fetch one sample record (`admin-data?action=list&entity=<entity>&limit=1`) and use its **stamped** `design_schema.views.default_list`.
30
+ 2. No stamped schema → look up `/api/types?action=list&kind=<mapped>`; used only when **exactly one** type matches the entity's kind.
31
+ 3. Otherwise a fallback view (just `id` + `created_at` columns).
32
+
33
+ **Downstream effects**
34
+
35
+ - All data flows through `/api/admin-data` — the same permission, validation, and trigger path as any other client.
36
+ - Multi-type entities (e.g. `items` with `ticket`, `threshold_alert`, `kb-article`) resolve schema from the *sample record* — the columns shown are whichever type the most recent matching record carries, and `type_slug` filtering is available via the route's `typeSlug` param.
37
+ - A type with no `default_list` view (or a fresh table with no records and >1 candidate type) renders the fallback two-column view — fix the type's `design_schema`, not this page.
38
+
39
+ ## Minimal configuration
40
+
41
+ Define `views.default_list` on the type:
42
+
43
+ ```json
44
+ "default_list": {
45
+ "type": "list", "display": "table", "label": "Tickets",
46
+ "fields": {
47
+ "title": { "sortable": true, "display_type": "text" },
48
+ "status": { "sortable": true, "display_type": "badge" },
49
+ "created_at": { "sortable": true, "display_type": "timestamp" }
50
+ },
51
+ "default_sort": { "field": "created_at", "direction": "desc" }
52
+ }
53
+ ```
54
+
55
+ ## Full configuration
56
+
57
+ Add `stats` and `filters` arrays to the view for stat cards and filter controls, choose `display_type` per column to control rendering, and set a different `default_sort` (e.g. `priority asc`). Valid `entity` path segments are the `admin-data` whitelist: `accounts`, `people`, `items`, `threads`, `messages`, `links`, `attachments`, `watchers`, `item_progress`, plus config entities (`types`, `link_types`, `ai_agents`, `prompt_configs`, ...).
58
+
59
+ ## Example
60
+
61
+ `/spine-framework/admin/runtime/items` shows the ticket list: columns Title/Status/Priority/Created from `default_list.fields`, status rendered as a badge, sorted by `created_at` desc; the New button lands on `runtime/items/new`.
62
+
63
+ ## Core files
64
+
65
+ - `.framework/src/components/runtime/DataListPage.tsx` — this page
66
+ - `.framework/src/components/runtime/DataTable.tsx` / `DataFilters.tsx` / `DataStats.tsx` / `DataHeader.tsx` — subcomponents
67
+ - `.framework/src/hooks/useListSchema.ts` — stamped-schema → type → fallback resolution
68
+ - `.framework/src/hooks/useEntityList.ts` — the `admin-data` list query (filters, sort)
69
+ - `.framework/functions/admin-data.ts` — list/get backend (`VALID_ENTITIES` whitelist)
70
+ - `.framework/src/apps/admin/index.tsx` — `instructionKeyFor`: `runtime/:entity` → `runtime-list`
71
+
72
+ ## Agent notes
73
+
74
+ - The schema comes from a **record's stamped** `design_schema` first — old records stamped before a schema change keep old views; the list can flip shape depending on which record it samples.
75
+ - If the page shows only `id`/`created_at`, the type's `default_list` view is missing or ambiguous — check the type, then check that the entity has records.
76
+ - Non-system fields live under `record.data` — a column for a `system: true` field reads `record.<field>`; mixing these up shows blank cells.
77
+ - Filter/sort state is client-side over the fetched page — this is a browsing surface, not a reporting tool.
@@ -0,0 +1,67 @@
1
+ ---
2
+ title: Security
3
+ audience: both
4
+ kind: entity
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/src/pages/admin/SecurityPage.tsx
9
+ - .framework/functions/security.ts
10
+ - .framework/functions/_shared/security.ts
11
+ - .framework/migrations/049_security_blocklist.sql
12
+ ---
13
+
14
+ ## What this is for
15
+
16
+ The **Security** page (`/spine-framework/admin/security`) is the system-admin console for abusive actors: a report of flagged users/accounts/IPs built from security signal logs, plus the platform blocklist. Its actions apply a three-layer ban — internal `security_blocklist` rows, a Supabase Auth ban, and a Netlify edge IP-deny rule.
17
+
18
+ ## Fields and settings
19
+
20
+ - **Flagged actors table** — Actor (email or "(no person)"), Account, IP / Country, Signals (count + kind badges e.g. `rate_limit`, `prompt_injection`, `blocked_registration`), Last seen, Status (`active`/person status or `banned`).
21
+ - **Row checkboxes + Add to Blacklist** — issues one `ban_user` call per selected row and prints per-layer results (`blocklist`, `auth`, `edge`) inline.
22
+ - **Unban** — per-row on banned actors with a `person_id`; revokes their blocklist rows and lifts the auth ban and edge rule.
23
+ - **Active blocklist table** — Type (`ip`/`email`/`person`/`account`), Value, Severity, Reason, Created, with per-row Revoke (`blocklist_revoke` sets `revoked_at`).
24
+ - All calls go to `/api/security?action=…` (POST): `flagged_accounts`, `blocklist`, `ban_user`, `unban_user`, `blocklist_add`, `blocklist_revoke`.
25
+
26
+ **Downstream effects**
27
+
28
+ - `ban_user` accepts `person_id`, `email`, or `ip` — anonymous-signal rows (no person) still ban by account/IP. Layer 1 (internal blocklist) is authoritative; the Supabase Auth and Netlify edge layers report `applied`/`skipped`/`error` per call — the edge layer degrades gracefully when Netlify API credentials aren't configured.
29
+ - Blocked principals are rejected at request time by `isBlockedRequest`/`isBlockedIp` in `_shared/security.ts` (checked in middleware and at registration).
30
+ - Every action emits `security.*` audit events into `logs` — the same table the flagged report is aggregated from.
31
+ - Every action requires a `system_admin` principal.
32
+
33
+ ## Minimal configuration
34
+
35
+ Nothing to configure — the report fills itself from security signals (rate-limit violations, prompt-injection detections, blocked registrations). To act: select flagged rows → Add to Blacklist.
36
+
37
+ ## Full configuration
38
+
39
+ Direct API calls for finer control:
40
+
41
+ ```
42
+ POST /api/security?action=blocklist_add { type: "ip", value: "203.0.113.7", severity: "high", reason: "credential stuffing", expires_at: null }
43
+ POST /api/security?action=blocklist_revoke { id: "<row uuid>" }
44
+ POST /api/security?action=ban_user { email: "abuser@example.com", ip: "203.0.113.7", reason: "..." }
45
+ POST /api/security?action=unban_user { person_id: "<uuid>" }
46
+ ```
47
+
48
+ `expires_at` may be set for temporary bans; entries with `revoked_at` are hidden from the Active blocklist.
49
+
50
+ ## Example
51
+
52
+ A burst of `rate_limit` signals from one IP appears in Flagged actors. Select the row, Add to Blacklist — the result line shows `banned (auth:applied edge:applied)`; subsequent requests from that IP 403 at the edge and at `isBlockedIp`. If it was a false positive, Unban restores the person and revokes the rows.
53
+
54
+ ## Core files
55
+
56
+ - `.framework/src/pages/admin/SecurityPage.tsx` — this page
57
+ - `.framework/functions/security.ts` — flagged report, three-layer ban/unban, blocklist CRUD, Netlify edge sync
58
+ - `.framework/functions/_shared/security.ts` — `isBlockedRequest`/`isBlockedIp` enforcement, `emitSecurityEvent`, injection patterns
59
+ - `.framework/migrations/049_security_blocklist.sql` — `security_blocklist` schema
60
+ - Tables: `public.security_blocklist`, `public.logs` (signal source)
61
+
62
+ ## Agent notes
63
+
64
+ - The Netlify edge layer needs Netlify API credentials in env — without them `edge: skipped` is normal, not a failure; the internal blocklist still enforces.
65
+ - Banning by `email`/`ip` does not stop a determined actor from rotating — treat the edge deny as a speed bump and watch for re-registration signals.
66
+ - Unban requires a `person_id` — rows banned only by IP/email must be lifted via `blocklist_revoke` on the blocklist entries.
67
+ - This page is marked experimental and is system-admin only; all writes are audited.
@@ -0,0 +1,110 @@
1
+ ---
2
+ title: Add a pipeline
3
+ audience: developers, agents
4
+ kind: task
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/functions/pipelines.ts
9
+ - .framework/functions/_shared/pipeline-runner.ts
10
+ - .framework/migrations/053_builtin_action_seeds.sql
11
+ - .framework/functions/system-cron.ts
12
+ ---
13
+
14
+ # Add a pipeline
15
+
16
+ ## Goal
17
+
18
+ Create a `public.pipelines` row: an ordered `stages` array the runner
19
+ executes when something (a trigger, a timer, or a manual run) invokes it.
20
+
21
+ ## Steps
22
+
23
+ 1. **Choose the `trigger_type`.** `manual` (run by button/API), `event`
24
+ (fired by a trigger), `scheduled` (fired by a timer), or `webhook`. This
25
+ is metadata for callers — what actually runs a pipeline is whatever
26
+ invokes `runPipeline`, so the type should match how you plan to wire it
27
+ ([Automation](../concepts/automation.md)).
28
+
29
+ 2. **Draft the `stages` array.** Each stage needs a `stage_type` matching an
30
+ active slug in `public.actions` plus a `config`. Built-in stage types
31
+ (seeded by `.framework/migrations/053_builtin_action_seeds.sql`):
32
+
33
+ `update_item`, `create_record`, `http_request`, `send_notification`,
34
+ `send_email`, `run_pipeline`, `search_knowledge`, `query_items`,
35
+ `agent_inference`, `generate_embeddings`, `revoke_embeddings`,
36
+ `kb_ingest`, `kb_revoke`, `create_interaction`
37
+ (`.framework/functions/_shared/pipeline-runner.ts`).
38
+
39
+ ```json
40
+ [
41
+ {
42
+ "stage_type": "query_items",
43
+ "config": { "entity": "items", "type_slug": "ticket",
44
+ "filters": { "status": "open" } }
45
+ },
46
+ {
47
+ "stage_type": "http_request",
48
+ "config": { "url": "https://example.com/hook", "method": "POST",
49
+ "body": { "title": "{{record.data.title}}" } }
50
+ }
51
+ ]
52
+ ```
53
+
54
+ - Stage config merges `action.config` (defaults on the actions row) under
55
+ `stage.config`, plus injected `_pipelineId` / `_executionId` /
56
+ `_stageIndex` / `_triggerData`
57
+ (`.framework/functions/_shared/pipeline-runner.ts`).
58
+ - `{{trigger.*}}` resolves into the trigger-data envelope; `{{record.*}}`
59
+ resolves into `triggerData.entity.data` — the record that fired the
60
+ run (`.framework/functions/_shared/pipeline-runner.ts`).
61
+ - `continue_on_error: true` on a stage lets the run continue after a
62
+ failure; otherwise a failed stage aborts the whole run
63
+ (`.framework/functions/_shared/pipeline-runner.ts`).
64
+
65
+ 3. **Create the pipeline.** Admin UI → **Configs → Pipelines → New**
66
+ (`configs/pipelines/new`), or `POST /api/pipelines` with
67
+ `{ name, trigger_type, stages }` — all three required
68
+ (`.framework/functions/pipelines.ts`). Set `is_active: true`;
69
+ `runPipeline` refuses inactive pipelines.
70
+
71
+ 4. **Wire the entry point.** A pipeline with `trigger_type: "event"` needs a
72
+ trigger ([Add a trigger](./add-a-trigger.md)); `scheduled` needs a timer
73
+ ([Add a timer](./add-a-timer.md)); `manual` runs on demand. Changing
74
+ `trigger_type` later does not rewire existing triggers or timers — relink
75
+ them separately.
76
+
77
+ ## Verify
78
+
79
+ - Run it directly: `npx spine-framework pipelines run <id> --data '{"x":1}'`
80
+ — see [CLI reference](../reference/cli.md).
81
+ - Check **Observability → Executions** (`observability/executions`) or
82
+ `pipelines executions <id>` for a `completed` row with per-stage results.
83
+ - A missing `stage_type` fails fast with
84
+ `Action not found for stage type: <type>` — the runner looks the slug up
85
+ in `public.actions` with `is_active = true` before executing
86
+ (`.framework/functions/_shared/pipeline-runner.ts`).
87
+
88
+ ## Common mistakes
89
+
90
+ - **Nonexistent stage_type.** Seed validation and the runner both reject
91
+ unknown slugs; stick to the built-ins or seed your own `actions` row
92
+ (see [Package and install an app](./package-and-install-an-app.md)).
93
+ - **Expecting stage outputs to chain into the next stage.** Each stage gets
94
+ the merged `action.config` + `stage.config` + `_triggerData`; previous
95
+ stage outputs are collected into the execution result, not injected into
96
+ later configs. Templates only see `{{trigger.*}}` and `{{record.*}}`.
97
+ - **`scheduled` with no timer, or `event` with no trigger.** The pipeline
98
+ is then unreachable — `get_due_timers` only returns timers with
99
+ `pipeline_id` set, and triggers dispatch by `pipeline_id`.
100
+ - **Editing `stages` while runs are queued.** The runner reads the pipeline
101
+ row at execution time; a queued execution picks up whatever `stages`
102
+ exist when it starts, not when it was queued.
103
+
104
+ ## Reference
105
+
106
+ - [pipelines entity page](../pipelines.md) ·
107
+ [Automation](../concepts/automation.md)
108
+ - [pipeline-executions reference](../reference/functions/pipeline-executions.md) ·
109
+ [pipeline-runner-background reference](../reference/functions/pipeline-runner-background.md)
110
+ - [Add a trigger](./add-a-trigger.md) · [Add a timer](./add-a-timer.md)
@@ -0,0 +1,96 @@
1
+ ---
2
+ title: Add a role
3
+ audience: developers, agents
4
+ kind: task
5
+ verified_against: e13127d
6
+ verified_on: 2026-10-30
7
+ source_files:
8
+ - .framework/functions/roles.ts
9
+ - .framework/functions/_shared/permissions.ts
10
+ - .framework/migrations/001_core_schema.sql
11
+ - .framework/migrations/003_core_system_data.sql
12
+ - .framework/migrations/009_roles_slug_unique.sql
13
+ ---
14
+
15
+ # Add a role
16
+
17
+ ## Goal
18
+
19
+ Create a `public.roles` row whose slug you can reference from
20
+ `record_permissions` in type design schemas, `min_role`/`required_roles` on
21
+ apps, and `role:<slug>` notification recipients.
22
+
23
+ ## Prerequisites
24
+
25
+ - A `system_admin` login — role create/update/remove requires it
26
+ (`.framework/functions/roles.ts`).
27
+
28
+ ## Steps
29
+
30
+ 1. **Pick the slug.** Lowercase snake_case (`support_agent`). It is matched
31
+ verbatim as a key inside every type's `record_permissions` and is
32
+ effectively immutable — the admin UI disables slug editing after creation.
33
+ Uniqueness is enforced at both the API layer (duplicate-slug check before
34
+ insert) and the database (`UNIQUE(slug)`,
35
+ `.framework/migrations/009_roles_slug_unique.sql`).
36
+
37
+ 2. **Decide the permissions payload.** `roles.permissions` is a JSON
38
+ document on the role row (`permissions jsonb` on the table,
39
+ `.framework/migrations/001_core_schema.sql`). Seeded roles carry
40
+ `'["*"]'` — a wildcard grant. Per-type grants are expressed on the
41
+ **type** side (`design_schema.record_permissions` keys are role slugs),
42
+ which is what `admin-data` evaluates per request — see
43
+ [Permission model](../concepts/permissions.md).
44
+
45
+ 3. **Create the role.** Admin UI → **Configs → Roles → New**
46
+ (`configs/roles/new`), or `POST /api/roles` with
47
+ `{ slug, name, permissions, is_system }` — `slug` and `name` are required
48
+ (`.framework/functions/roles.ts`). The `system_admin` slug itself
49
+ is protected: only a system admin may create it
50
+ (`.framework/functions/roles.ts`).
51
+
52
+ 4. **Reference the role.** Add its slug to each type's
53
+ `design_schema.record_permissions`, to `apps.min_role` /
54
+ `apps.required_roles`, and to `send_notification` stage recipients as
55
+ `role:<slug>` (resolved via `people.role_id → roles.slug` — see
56
+ [Automation](../concepts/automation.md)).
57
+
58
+ 5. **Assign it to people.** A person's `role_id` joins to `roles`; the
59
+ permission engine resolves `people.role:role_id(slug)` and evaluates
60
+ `record_permissions` against that slug
61
+ (`.framework/functions/_shared/permissions.ts`).
62
+
63
+ ## Verify
64
+
65
+ - `GET /api/roles?action=list` returns the row; `slug` is unique and active.
66
+ - Create or update a type whose `record_permissions` includes the new slug,
67
+ then perform an `admin-data` call as a person holding the role — the
68
+ action is permitted.
69
+ - `system_admin` users see all roles regardless of `is_active` filters.
70
+
71
+ ## Common mistakes
72
+
73
+ - **`system-admin` vs `system_admin`.** All seeded slugs are snake_case:
74
+ `system_admin`, `member`, `member_admin`, `engineering`,
75
+ `engineering_admin`, `product`, `docs`, `qa`, `devops`, `management`,
76
+ `sales`, `csm`, `tam`, `support`, `support_admin`
77
+ (`.framework/migrations/003_core_system_data.sql`,
78
+ `.framework/migrations/073_seed_member_roles.sql`).
79
+ Using hyphens in `record_permissions` grants nothing.
80
+ - **Expecting `roles.permissions` to gate `admin-data`.** Record-level
81
+ grants live on the type's `record_permissions`; the role row's
82
+ `permissions` JSON is not consulted per-request for record CRUD.
83
+ - **Renaming a slug later.** Every type's `record_permissions` and every
84
+ app's `min_role`/`required_roles` reference the slug verbatim — a rename
85
+ orphans the grants. Create a new role and migrate people instead.
86
+ - **Creating `system_admin` via API as a non-admin** — explicitly blocked.
87
+ - **Deactivating a role with live assignees** — the slug stops resolving to
88
+ a grant for those people; check `people.role_id` usage first.
89
+
90
+ ## Reference
91
+
92
+ - [roles entity page](../roles.md) ·
93
+ [roles function reference](../reference/functions/roles.md)
94
+ - [Permission model](../concepts/permissions.md) ·
95
+ [Add a type](./add-a-type.md)
96
+ - [Database reference](../reference/database.md) for the `roles` columns