spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/timers.md

@@ -0,0 +1,82 @@
+---
+title: Timers
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/timers.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TimersPage.tsx
+  - .framework/src/pages/admin/TimerDetailPage.tsx
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+---
+
+## What this is for
+
+A **timer** is a scheduled job that invokes a pipeline when it comes due — Spine's recurring/one-off background task primitive. `system-cron` (invoked every minute by the `trigger-scheduler` Netlify scheduled function) asks the `get_due_timers` RPC for due timers and runs each one's pipeline.
+
+## Fields and settings
+
+- **Name** — string. Display name; required (`name` and `timer_type` are the API's required fields).
+- **Type** — select: `interval`, `cron`, `once`. **Stored but not read by the scheduler** — it labels intent only; see Downstream effects.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select. The pipeline invoked when the timer fires. `get_due_timers` skips rows where `pipeline_id IS NULL`, so a blank pipeline means the timer never runs.
+- **Active** — checkbox. Inactive timers are skipped by `get_due_timers`.
+- **Description** — string, optional.
+- **Config (JSON)** — the schedule. The only key the rescheduler reads today is `interval_minutes` (minutes between runs). The form seeds `{ "schedule": "", "interval_seconds": 3600 }` — neither key is honored by the current RPCs.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- `get_due_timers` returns active timers with `pipeline_id IS NOT NULL` and `next_execution <= now()`. The timers API arms `next_execution` automatically on create/activate when `config.interval_minutes` (or `interval_seconds`) resolves to a positive interval — or pass `next_execution` explicitly.
+- `update_timer_after_run` reschedules `next_execution = now() + interval` only when `config.interval_minutes` is a positive number; otherwise it sets `next_execution = NULL` and the timer becomes one-shot/dead. `timer_type`, `interval_seconds`, `schedule`, and `run_at` are ignored by the RPC.
+- Each firing also stamps `last_execution` and increments `execution_count` / `success_count` / `failure_count` — the source of the list page's Executions and Success Rate columns.
+- True cron expressions live on the separate `public.schedules` table (read by `get_due_schedules`), not on `timers` — a `cron`-type timer is a label, not a working cron.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Hourly sync",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 60 }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Nightly-ish rollup",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 1440 },
+  "metadata": { "owner": "platform", "notes": "fires ~daily once next_execution is seeded" }
+}
+```
+
+## Example
+
+A support app keeps an `interval` timer with `interval_minutes: 360` to re-check stale tickets every six hours, and a second timer whose `interval_minutes` was left blank to run a one-off backfill — after its first fire, `update_timer_after_run` writes `next_execution = NULL` so it never re-fires.
+
+## Core files
+
+- `.framework/functions/timers.ts` — API (list/get/create/update/delete; does not set `next_execution`)
+- `.framework/functions/system-cron.ts` — per-tick driver: calls `get_due_timers`, runs `runPipeline` as a `timer:<id>` principal, then `update_timer_after_run`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point that delegates to `system-cron`
+- `.framework/migrations/068_cron_schedule_timer_rpcs.sql` — the `get_due_timers` / `update_timer_after_run` RPCs
+- `.framework/src/pages/admin/TimersPage.tsx` / `TimerDetailPage.tsx` — admin UI
+- Table: `public.timers` (`timer_type`, `pipeline_id`, `next_execution`, `execution_count` added by migration 020)
+
+## Agent notes
+
+- The list's "Next Execution" column shows `Not scheduled` when `next_execution` is NULL — an active timer in that state cannot fire until it is re-armed (edit its interval or toggle it off/on).
+- A timer with a blank `pipeline_id` saves fine but is filtered out by `get_due_timers` — always pick the pipeline.
+- To arm a new timer, set `next_execution` in the DB (e.g. `now() + interval`); after the first successful run, `interval_minutes` keeps it rescheduling.
+- "Success Rate" is `success_count / execution_count`; failures still reschedule — a broken pipeline does not stop the cadence.

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

@@ -0,0 +1,69 @@
+---
+title: Triggers
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/triggers.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TriggersPage.tsx
+  - .framework/src/pages/admin/TriggerDetailPage.tsx
+  - .framework/migrations/064_episode_leases.sql
+---
+
+## What this is for
+
+A **trigger** listens for a Spine event and, when active, hands the event payload to a pipeline for processing. It is the link between emitted platform events (e.g. `item_created`) and the workflows that react to them.
+
+## Fields and settings
+
+- **Name** — string. Display name; missing name prevents saving.
+- **Event Type** — string. The event to listen to, e.g. `item_created`. Must match the emitted event name **exactly** — a typo means the trigger never fires.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select, required at create (`name`, `event_type`, `pipeline_id` are all required by the API). The pipeline invoked when the trigger fires; a stale ID means the queued execution fails instead of running.
+- **Active** — checkbox. Inactive triggers are skipped at fire time — matching events produce no run.
+- **Description** — string, optional.
+- **Config (JSON)** — trigger-engine configuration, e.g. filters or payload mapping.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- The trigger engine (`admin-data` writes → `_shared/trigger-engine`) matches emitted events to active triggers by `event_type`; real event names use underscores — `item_created`, `item_updated`, `item_deleted`, `thread_created`, `message_created`, etc. (see the `EventType` union in `_shared/trigger-engine.ts`).
+- `config` filters narrow which matching events actually invoke the pipeline.
+- A wrong or stale `pipeline_id` means the trigger fires, queues an execution row, and the run fails — check Pipeline Executions, not just the trigger, when "nothing happened".
+
+## Minimal configuration
+
+```json
+{
+  "name": "On item created",
+  "event_type": "item_created",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true
+}
+```
+
+## Full configuration
+
+Adds `config` with payload filters (e.g. match only `item_created` where `type_slug = "ticket"`), field mappings into the pipeline input, and `metadata` documenting the contract the event producer is expected to emit.
+
+## Example
+
+A support app fires `item_created` filtered to `type_slug = "ticket"`; the trigger invokes its triage pipeline, which assigns the ticket and posts a thread message. A second trigger on `item_updated` handles SLA warnings — both share the same pipeline pattern but different filters.
+
+## Core files
+
+- `.framework/functions/triggers.ts` — API
+- `.framework/functions/_shared/trigger-engine.ts` — event matching and dispatch to `pipeline-runner-background`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point (delegates to `system-cron`)
+- `.framework/src/pages/admin/TriggersPage.tsx` / `TriggerDetailPage.tsx` — admin UI
+- Table: `public.triggers`
+
+## Agent notes
+
+- Event names are `<entity>_<past tense>` (`item_created`, `message_deleted`, ...) — the Event Type input's own placeholder still shows the stale `item.created` form; use underscores.
+- `config` filters (`entity_type`, `type_slug`, `filters` with `$eq`/`$ne`/`$gt`/etc.) narrow which matching events actually invoke the pipeline.
+- The list's "Total Fires" stat and "Fires"/"Last Fired" columns count trigger firings (the `record_trigger_fire` RPC), not successful pipeline runs — a trigger can fire while its pipeline fails.
+- `config` must be a JSON **object**, not a string — the second most common save failure after event-type typos.

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

@@ -0,0 +1,93 @@
+---
+title: Types
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/types.ts
+  - .framework/src/pages/admin/TypesPage.tsx
+  - .framework/src/pages/admin/TypeDetailPage.tsx
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/migrations/015_types_kind_slug_unique.sql
+---
+
+## What this is for
+
+A **type** is the design schema for a runtime record kind. It defines the fields, default list/detail views, record permissions, icon, and color that the generic admin and runtime UIs use to create, validate, and display records. Every `items`/`threads`/`messages`/etc. record is stamped with its type's `design_schema` at creation.
+
+## Fields and settings
+
+- **Name** — string. Display label for the type. Empty name blocks save.
+- **Slug** — string. URL-friendly identifier, unique per `kind`. Callers resolve types by slug; duplicates break `resolveTypeId`/`.single()` lookups. Rarely change after records exist.
+- **Description** — string, optional. Human-readable context.
+- **Kind** — select: `item`, `account`, `person`, `thread`, `message`, `link`, `attachment`, `watcher`. Determines which runtime table the type governs.
+- **Ownership** — select: `system` (platform types, protected from deletion), `app` (owned by an app), `tenant` (account-specific).
+- **Is Active** — checkbox. Inactive types are hidden from lists and cannot have records created.
+- **App ID** — select. Required whenever ownership is not `system` — the form rejects save otherwise.
+- **Icon / Color** — UI presentation stored on the `types` row.
+- **Design Schema (JSON)** — the full schema: `fields`, `views` (`default_list`, `default_detail`), `record_permissions`, `scope`, `functionality`.
+- **Validation Schema** — read-only, regenerated from `design_schema` on every save by the API.
+
+**Downstream effects**
+
+- Generic list/detail pages render directly from `views`. A missing `default_list`/`default_detail` or unknown `display_type` breaks those pages.
+- `record_permissions` is the **base, most restrictive grant**: if a role can read/update a record, all fields default to read/write. `fields.*.permissions` only *loosen* access per field or restrict `system: true` fields.
+- `system: true` fields are read from `record.<field>`; non-system fields from `record.data.<field>`.
+- Changing `data_type` on a field with existing records does not migrate data — old values remain until rewritten.
+- Type seeds use `conflict: "kind,slug"` with `inject_app_id: false` — types are global, not duplicated per app install.
+
+## Minimal configuration
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title": { "data_type": "text", "label": "Title", "required": true, "system": true }
+  },
+  "views": {
+    "default_list": {
+      "type": "list", "display": "table", "label": "List",
+      "fields": {
+        "title": { "sortable": true, "display_type": "text" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail", "label": "Detail",
+      "sections": [{ "title": "Details", "fields": { "title": { "display_type": "input" } } }]
+    }
+  },
+  "record_permissions": { "system_admin": ["create", "read", "update", "delete"] },
+  "functionality": null
+}
+```
+
+## Full configuration
+
+Adds typed fields, select `options`, per-field `permissions` overrides, multiple views with sorting/badges, and per-role record grants (`admin`, `member`). See the [design schema reference](reference/design-schema.md) for the full `data_type` list (`text`, `number`, `select`, `multiselect`, `reference`, `json`, `date`, `boolean`, ...) and `display_type` list (`badge`, `timestamp`, `select`, `currency`, ...).
+
+## Example
+
+A support app defines a `ticket` type (kind `item`, ownership `app`): `title` (system text), `status` (select: open/pending/closed), `priority` (select), `assignee_id` (reference). `record_permissions` grants `system_admin` all actions, `admin` create/read/update, `member` read. `fields.assignee_id.permissions` loosens `write` to `member` so agents can self-assign.
+
+## Core files
+
+- `.framework/functions/types.ts` — API (list/get/create/update/delete; regenerates `validation_schema`)
+- `.framework/src/pages/admin/TypesPage.tsx` / `TypeDetailPage.tsx` — admin UI
+- `.framework/src/components/app-shell/GenericListPage.tsx` / `GenericDetailPage.tsx` — generic renderer
+- `.framework/functions/_shared/permissions.ts` — record/field permission evaluation
+- [Design schema reference](reference/design-schema.md) — full field/view schema reference in this book
+- Table: `public.types`
+
+## Agent notes
+
+- Never hand-edit `validation_schema`; change `design_schema` and the API regenerates it.
+- Slug uniqueness is per `(kind, slug)` — reuse across kinds is fine, reuse within a kind breaks lookups.
+- Every field needs `data_type`, `label`, `required`; `select`/`multiselect`/`radio` also need `options`.
+- Don't add `fields.*.permissions` unless overriding the base grant — the common mistake is re-stating record-level permissions per field.
+- Custom apps CRUD runtime records through `/api/admin-data` — never custom wrappers.

package/.framework/src/pages/NotFoundPage.tsx

@@ -1,35 +1,65 @@
 // CIL[BEGIN stable_id="~/.framework/src/pages/NotFoundPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-MACRO purpose="Import dependencies used by the NotFoundPage 404 component"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide React, react-router-dom Link, and lucide-react Home icon for the page"]
-// CIL[DOC-CONTEXT module=".framework/src/pages" layer="page" related_files=".framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-CONTRACT inputs="N/A" outputs="N/A" errors="N/A" side_effects="N/A"]
-// CIL[DOC-MICRO logic_summary="Imports React, Link, and Home icon; no runtime logic" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="Spine framework page authors"]
+/**
+ * @module   NotFoundPage
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module renders a Not Found page for the application, providing users with a friendly message when they navigate to an undefined route. It serves as a fallback UI component, enhancing user experience by guiding them back to the home page. INVARIANT: The Not Found page should always be accessible for any invalid routes.
+ *
+ * @seeAlso react-router-dom (provides routing capabilities).
+ * @seeAlso lucide-react (used for icons).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
+
 
 
 
 import React from 'react'
 import { Link } from 'react-router-dom'
 import { Home } from 'lucide-react';
-// CIL[DOC-VECTOR type="context" content="purpose='Import dependencies used by the NotFoundPage 404 component'; No verified external callers; imports: none"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/NotFoundPage.tsx:module_header:module_header"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/pages/NotFoundPage.tsx:NotFoundPage:component" type="component" identity="NotFoundPage" parent="~/.framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-MACRO purpose="Render a friendly 404 not found page with a link back to sign in"]
-// CIL[DOC-RESPONSIBILITY responsibility="Display a centered 404 message and a Home icon link that navigates to /login"]
-// CIL[DOC-CONTEXT module=".framework/src/pages" layer="page" related_files=".framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-CONTRACT inputs="None" outputs="JSX 404 page" errors="None" side_effects="None"]
-// CIL[DOC-MICRO logic_summary="Renders a full-screen 404 page with a heading, description, and a Link to /login" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="End users who reach an unknown route"]
+/**
+ * The NotFoundPage component displays a 404 error message when a page is not found, providing a user-friendly interface to guide users back to the home page.
+ *
+ * @macro       React functional component responsible for rendering a 404 error page.
+ * @micro       Utilizes JSX to structure the layout and styling of the error message and navigation link.
+ * @outputSpec  JSX.Element
+ * @sideEffects none
+ * @stability   internal
+ * @calls       Link
+ * @cil-generated
+ */
 export function NotFoundPage() {
   return (
     <div className="min-h-screen bg-slate-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
@@ -43,11 +73,11 @@ export function NotFoundPage() {
           
           <div className="mt-6">
             <Link
-              to="/login"
+              to="/"
               className="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md shadow-sm text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
             >
               <Home className="w-4 h-4 mr-2" />
-              Go to sign in
+              Go home
             </Link>
           </div>
         </div>
@@ -55,10 +85,11 @@ export function NotFoundPage() {
     </div>
   )
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Render a friendly 404 not found page with a link back to sign in'; No verified external callers; imports: none"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/NotFoundPage.tsx:NotFoundPage:component"]
+// CIL[END stable_id="~/.framework/src/pages/NotFoundPage.tsx:NotFoundPage:component"]
+
+
+
+
+
+
+