spine-framework 0.1.0

package/.framework/docs/authorization-model.md

@@ -0,0 +1,170 @@
+# Authorization Model Overview
+
+## First Surface vs Second Surface
+
+### First Surface (User Interactions)
+- User is the actor
+- Permissions come from type.schema + DB role assignments
+- System admin bypasses all checks
+- Examples: User creates account, user creates ticket, user sends message
+
+### Second Surface (System Interactions)  
+- System is the actor
+- Runs with system role
+- Captures triggering user/system UUID for audit
+- Examples: AI agent processes ticket, timer fires, integration syncs data
+
+### System Admin
+- Complete bypass of all restrictions
+- Can read/write/lock/unlock any surface
+- Audit logs still record actions
+
+## Permission Resolution
+
+1. **Authentication** - Validate JWT, resolve personId
+2. **Account Context** - Determine acting account from headers/membership
+3. **Role Resolution** - Get active roles from v2.people_accounts + v2.people_roles
+4. **Schema Loading** - Load type.schema for target record type
+5. **Permission Evaluation** - Apply record_permissions + field overrides
+6. **Multi-role Merge** - Use highest effective permission per action
+7. **System Admin Bypass** - Skip all checks if system_admin
+
+## Master/Client Access
+
+Master account users access client records by:
+1. Being assigned roles in client accounts via v2.people_roles
+2. Having those roles recognized in client record's type.schema
+3. No special-case permission logic required
+
+## Type Schema Structure
+
+```json
+{
+  "record_permissions": {
+    "role_slug": {
+      "create": boolean,
+      "read": "all" | "account" | "own" | "none",
+      "update": "all" | "account" | "own" | "none", 
+      "delete": boolean
+    }
+  },
+  "fields": {
+    "field_name": {
+      "type": "field_type",
+      "permissions": {
+        "role_slug": {
+          "read": boolean,
+          "write": boolean
+        }
+      }
+    }
+  }
+}
+```
+
+## Access Levels
+
+### Record Access Levels
+- **all** - Can access all records regardless of ownership
+- **account** - Can access records within the same account
+- **own** - Can only access records they created
+- **none** - No access
+
+### Field Access Levels
+- **true** - Can access the field
+- **false** - Cannot access the field
+
+## Multi-Role Permission Merging
+
+When a user has multiple roles, permissions are merged using the "highest effective permission wins" rule:
+
+- For CRUD operations: if any role allows the action, the action is allowed
+- For field access: if any role allows field access, field access is allowed
+- System admin bypasses all permission checks
+
+## Implementation Details
+
+### Shared Permission Resolver
+
+The `resolveFirstSurfacePermissions()` function in `v2-core/functions/_shared/permissions.ts` handles:
+
+1. Loading type schema from database
+2. Resolving user roles for the account context
+3. Evaluating record permissions for each role
+4. Merging permissions across multiple roles
+5. Applying field-level overrides
+
+### API Integration
+
+APIs use the permission resolver through these helper functions:
+
+- `canAccessRecord()` - Check if user can perform action on a record
+- `sanitizeRecordData()` - Filter record data based on read permissions
+- `validateUpdatePermissions()` - Validate field-level write permissions
+
+### System Admin Override
+
+System admin users (`systemRole === 'system_admin'`) bypass all permission checks while maintaining audit trails.
+
+## Examples
+
+### Support Ticket Type Schema
+
+```json
+{
+  "record_permissions": {
+    "user": {
+      "create": true,
+      "read": "own",
+      "update": "own",
+      "delete": false
+    },
+    "master-support": {
+      "create": false,
+      "read": "all",
+      "update": "all",
+      "delete": false
+    },
+    "master-csm": {
+      "create": false,
+      "read": "all",
+      "update": false,
+      "delete": false
+    }
+  },
+  "fields": {
+    "arr": {
+      "type": "number",
+      "permissions": {
+        "master-support": {
+          "read": false,
+          "write": false
+        },
+        "master-csm": {
+          "read": true,
+          "write": true
+        }
+      }
+    }
+  }
+}
+```
+
+### Permission Evaluation
+
+**Customer (user role):**
+- Can create tickets
+- Can only read/update their own tickets
+- Cannot see ARR field
+
+**Master Support (master-support role):**
+- Cannot create tickets
+- Can read all client tickets
+- Can update most ticket fields
+- Cannot see ARR field (field override)
+
+**Master CSM (master-csm role):**
+- Cannot create tickets
+- Can read all client tickets
+- Can only update ARR field (field override)
+- Cannot delete tickets

package/.framework/docs/db-api-inventory.md

@@ -0,0 +1,95 @@
+# DB-First API Inventory (v2 Schema)
+
+## Core Entity Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `accounts` | accounts.ts | admin-data | complete | Full CRUD with account scoping |
+| `people` | people.ts | admin-data | complete | Full CRUD with account scoping |
+| `items` | items.ts | admin-data | complete | Full CRUD with type validation |
+| `types` | types.ts | admin-configs | complete | Unified for item/account/person types |
+| `apps` | apps.ts | admin-configs | complete | App definitions with nav items |
+| `roles` | roles.ts | admin-configs | complete | Role definitions and permissions |
+| `links` | links.ts | runtime | complete | Polymorphic entity relationships |
+| `link_types` | link_types.ts | admin-configs | complete | Link type definitions |
+
+## Workflow & Automation Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `pipelines` | pipelines.ts | admin-configs | complete | Workflow automation pipelines |
+| `pipeline_executions` | pipeline-executions.ts | runtime | complete | Pipeline execution history |
+| `triggers` | triggers.ts | admin-configs | complete | Trigger definitions |
+| `trigger_executions` | trigger_executions | runtime | RPC-only | Accessed via triggers.ts |
+| `timers` | timers.ts | admin-configs | complete | Scheduled/delayed timers |
+
+## Collaboration & Communication Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `threads` | threads.ts | runtime | complete | Conversation threads |
+| `messages` | messages.ts | runtime | complete | Thread messages |
+| `attachments` | attachments.ts | runtime | complete | File attachments |
+| `watchers` | watchers.ts | runtime | complete | Entity watching/subscriptions |
+
+## Integration & AI Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `integrations` | integrations.ts | admin-configs | complete | Integration instances |
+| `embeddings` | embeddings.ts | admin-configs | complete | Embedding vectors |
+| `ai_agents` | ai-agents.ts | admin-configs | complete | AI agent definitions |
+| `prompt_configs` | prompt-configs.ts | admin-configs | complete | AI prompt configurations |
+
+## Access Control Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `people_accounts` | people-accounts.ts | runtime | complete | People-Accounts junction |
+| `people_roles` | people-roles.ts | runtime | complete | People-Roles junction |
+| `account_paths` | account-nodes.ts | internal | RPC-only | Account hierarchy traversal |
+
+## System & Logging Tables
+
+| Table | Endpoint | Domain | Status | Notes |
+|-------|----------|--------|--------|-------|
+| `logs` | logs.ts | internal | complete | System and application logs |
+
+## v2-Incompatible Endpoints (Require Remediation)
+
+| Endpoint | Referenced Tables | Domain | Status | Action Required |
+|----------|------------------|--------|--------|-----------------|
+| ai-orchestrator.ts | `ai_orchestrator` | internal | v2-incompatible | Table does not exist in v2 schema |
+| pending-actions.ts | `pending_actions` | internal | v2-incompatible | Table does not exist in v2 schema |
+| apps-accounts.ts | `apps_accounts` | internal | v2-incompatible | Table does not exist in v2 schema |
+| apps-integrations.ts | `apps_integrations` | internal | v2-incompatible | Table does not exist in v2 schema |
+| impersonation.ts | `impersonation_sessions`, `impersonation_policies`, `impersonation_logs` | internal | v2-incompatible | Tables do not exist in v2 schema |
+| integration-health.ts | `integration_sync_logs`, `oauth_connections`, `api_keys`, `api_key_usage_logs` | internal | v2-incompatible | Tables do not exist in v2 schema |
+| thread-participants.ts | `thread_participants` | runtime | v2-incompatible | Table does not exist in v2 schema |
+| outbox.ts | `outbox` | internal | v2-incompatible | Table does not exist in v2 schema |
+| webhooks.ts | `webhooks` | internal | v2-incompatible | Table does not exist in v2 schema |
+
+## Summary
+
+### Complete Coverage: 18 tables
+- All core entity tables have proper endpoints
+- All workflow/automation tables are covered
+- All collaboration tables are covered
+- All integration/AI tables are covered
+- Access control tables are covered
+- System logging is covered
+
+### v2-Incompatible: 9 endpoints
+- These endpoints reference tables that don't exist in v2 schema
+- Must be either rewritten to use existing v2 tables or quarantined
+- Priority: High - these will cause runtime errors if called
+
+### Missing Endpoints: 0 tables
+- All v2 schema tables have corresponding endpoints
+- Some tables are accessed via RPC rather than direct queries (trigger_executions, account_paths)
+
+### Recommendations
+1. Quarantine v2-incompatible endpoints immediately
+2. Rewrite or remove incompatible endpoints
+3. Consider if missing functionality should be implemented with existing v2 tables
+4. Update any UI that might be calling incompatible endpoints

package/.framework/docs/examples/custom-app/README.md

@@ -0,0 +1,77 @@
+# Example: Custom App
+
+A minimal React app with manifest and routing, installable via `spine-framework install-app`.
+
+## Directory Structure
+
+```
+custom/apps/my-app/
+├── manifest.json       # App metadata, routes, nav items
+├── index.tsx           # React entry point (default export)
+├── seed/
+│   ├── types.json      # Item types this app provides
+│   └── triggers.json   # Automation triggers
+├── components/
+│   └── Dashboard.tsx   # App-specific components
+└── package.json        # npm package metadata (optional)
+```
+
+## manifest.json
+
+```json
+{
+  "name": "My App",
+  "slug": "my-app",
+  "version": "0.1.0",
+  "description": "A custom app for demonstration",
+  "routes": [
+    { "path": "/", "redirect": "/dashboard" },
+    { "path": "/dashboard", "component": "Dashboard" }
+  ],
+  "nav_items": [
+    { "label": "Dashboard", "path": "/dashboard", "icon": "LayoutDashboard" }
+  ],
+  "required_roles": ["member"]
+}
+```
+
+## index.tsx
+
+```tsx
+import * as React from 'react'
+import { Routes, Route, Navigate } from 'react-router-dom'
+
+function Dashboard() {
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold">My App</h1>
+    </div>
+  )
+}
+
+export default function MyApp() {
+  return (
+    <Routes>
+      <Route path="/" element={<Navigate to="dashboard" replace />} />
+      <Route path="dashboard" element={<Dashboard />} />
+    </Routes>
+  )
+}
+```
+
+## Installation
+
+```bash
+# Create the app scaffold
+spine-framework create-app my-app
+
+# Or install an existing app package
+spine-framework install-app my-app
+```
+
+## How It Works
+
+1. `CustomAppLoader` discovers apps via `import.meta.glob('custom/apps/*/index.tsx')`
+2. The app's `manifest.json` provides routing and navigation metadata
+3. Seed data is applied via `spine-framework install-app` (idempotent upserts)
+4. The app is isolated — it cannot import from other apps or core internals

package/.framework/docs/examples/custom-function/README.md

@@ -0,0 +1,27 @@
+# Example: Custom Function
+
+A minimal Netlify Function using Spine's core context system.
+
+## Setup
+
+1. Create `custom/functions/custom_my-handler.ts`
+2. Import `createHandler` and `CoreContext` from `spine-framework/_shared`
+3. Your handler receives a fully-resolved `CoreContext` with:
+   - `ctx.principal` — authenticated user/machine identity
+   - `ctx.db` — Supabase client (scoped to principal's permissions)
+   - `ctx.accountId` — resolved account UUID
+   - `ctx.requestId` — unique request trace ID
+
+## Key Points
+
+- **Naming convention:** Custom functions MUST be prefixed with `custom_`
+- **No static imports from core:** Use the `spine-framework` package exports
+- **Authentication is automatic:** `createHandler` validates the JWT/API key before your code runs
+- **Database access:** Use `ctx.db` for RLS-scoped queries, or import `adminDb` for service-role operations
+
+## API
+
+```
+GET/POST /.netlify/functions/custom_my-handler?action=list
+Authorization: Bearer <jwt>
+```

package/.framework/docs/examples/custom-function/handler.ts

@@ -0,0 +1,48 @@
+/**
+ * Example: Custom Netlify Function using Spine core context
+ *
+ * This demonstrates the minimal pattern for creating a custom function
+ * that leverages Spine's authentication, database, and principal system.
+ *
+ * File: custom/functions/custom_my-handler.ts
+ */
+
+import { createHandler, adminDb } from 'spine-framework/_shared'
+import type { CoreContext } from 'spine-framework/_shared'
+
+/**
+ * A simple handler that lists items for the current account.
+ */
+async function listAccountItems(ctx: CoreContext) {
+  const { data, error } = await ctx.db
+    .from('items')
+    .select('id, title, type_id, created_at')
+    .eq('account_id', ctx.accountId)
+    .eq('is_active', true)
+    .order('created_at', { ascending: false })
+    .limit(50)
+
+  if (error) {
+    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
+  }
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ items: data }),
+  }
+}
+
+/**
+ * Netlify Function entry point.
+ * `createHandler` resolves the principal, validates auth, and provides CoreContext.
+ */
+export const handler = createHandler(async (ctx) => {
+  const { action } = ctx.params
+
+  switch (action) {
+    case 'list':
+      return listAccountItems(ctx)
+    default:
+      return { statusCode: 400, body: JSON.stringify({ error: 'Unknown action' }) }
+  }
+})

package/.framework/docs/examples/custom-webhook/README.md

@@ -0,0 +1,68 @@
+# Example: Custom Webhook Handler
+
+Demonstrates the self-registration pattern for webhook handlers.
+
+## How It Works
+
+1. Create a handler function in `custom/functions/custom_my-webhook.ts`
+2. Register it by calling `registerWebhookHandler()` in `custom/functions/custom_webhook-handlers.ts`
+3. Core resolves handlers at runtime via the `webhook_handlers` DB table — no static imports needed
+
+## Handler Function
+
+```ts
+// custom/functions/custom_my-webhook.ts
+
+import { createHandler } from 'spine-framework/_shared'
+import type { CoreContext } from 'spine-framework/_shared'
+
+export const handler = createHandler(async (ctx: CoreContext) => {
+  const payload = ctx.body
+
+  // Process the webhook payload
+  console.log('Received webhook:', payload.event_type)
+
+  // Do something with the data
+  const { error } = await ctx.db
+    .from('items')
+    .insert({
+      title: `Webhook: ${payload.event_type}`,
+      type_id: await resolveTypeId('webhook_event'),
+      account_id: ctx.accountId,
+      data: payload,
+    })
+
+  if (error) {
+    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
+  }
+
+  return { statusCode: 200, body: JSON.stringify({ ok: true }) }
+})
+```
+
+## Registration
+
+```ts
+// In custom/functions/custom_webhook-handlers.ts
+
+import { registerWebhookHandler } from 'spine-framework/_shared/webhook-registration'
+
+registerWebhookHandler({
+  name: 'my-webhook',
+  functionName: 'custom_my-webhook',
+  description: 'Handles incoming webhooks from MyService',
+  events: ['integration.webhook'],
+}).catch(console.error)
+```
+
+## Integration Config
+
+When configuring an integration in the admin panel, set:
+- `handler.path` = `my-webhook` (matches the `name` in registration)
+
+## Key Points
+
+- **Self-registration is idempotent** — safe to call on every module load
+- **No core changes needed** — just add your handler and register it
+- **Runtime resolution** — core looks up handlers from `webhook_handlers` table via `resolveHandler()`
+- **Events array** — currently `['integration.webhook']` is the standard event type

package/.framework/docs/gap-remediation-backlog.md

@@ -0,0 +1,103 @@
+# Gap Remediation Backlog
+
+## Priority 1: Critical v2-Incompatible Endpoints
+
+### 1. Quarantine v2-Incompatible Endpoints
+**Files to quarantine:**
+- `ai-orchestrator.ts` - References non-existent `ai_orchestrator` table
+- `pending-actions.ts` - References non-existent `pending_actions` table
+- `apps-accounts.ts` - References non-existent `apps_accounts` table
+- `apps-integrations.ts` - References non-existent `apps_integrations` table
+- `impersonation.ts` - References non-existent impersonation tables
+- `integration-health.ts` - References non-existent integration log tables
+- `thread-participants.ts` - References non-existent `thread_participants` table
+- `outbox.ts` - References non-existent `outbox` table
+- `webhooks.ts` - References non-existent `webhooks` table
+
+**Action:**
+1. Move these files to `v2-core/functions/_quarantine/` directory
+2. Update any routing that might call these endpoints
+3. Document what functionality needs replacement
+
+## Priority 2: UI Adoption Issues
+
+### 2. Fix TimersPage Mock Data
+**Issue:** TimersPage uses mock data instead of calling timers.ts API
+**File:** `v2-core/src/pages/admin/TimersPage.tsx`
+**Action:** Replace mock data with `apiFetch('/.netlify/functions/timers')`
+
+## Priority 3: API Standardization
+
+### 3. Add Role Guards to Config Endpoints
+**Files to update:**
+- `types.ts` - Admin-only for create/update/delete
+- `apps.ts` - Admin-only for create/update/delete
+- `pipelines.ts` - Admin-only for create/update/delete
+- `triggers.ts` - Admin-only for create/update/delete
+- `ai-agents.ts` - Admin-only for create/update/delete
+- `embeddings.ts` - Admin-only for create/update/delete
+- `timers.ts` - Admin-only for create/update/delete
+- `integrations.ts` - Admin-only for create/update/delete
+- `prompt-configs.ts` - Admin-only for create/update/delete
+- `roles.ts` - Admin-only for create/update/delete
+
+**Action:** Add `requireAuth` middleware to all config mutation endpoints
+
+### 4. Verify Soft Delete Implementation
+**Files to check:**
+- All endpoints should use `is_active=false` for delete
+- Ensure `updated_at` is set on soft delete
+- Verify audit logging before soft delete
+
+## Priority 4: Documentation
+
+### 5. Add Inline API Documentation
+**All endpoint files need:**
+- Purpose and domain documentation
+- Auth requirements
+- Account scoping rules
+- Request/response contracts
+- Soft delete behavior
+- v2 table dependencies
+
+### 6. Generate API Reference Docs
+**Create files in `v2-core/docs/apis/`:**
+- `admin-data.md`
+- `admin-configs.md`
+- `runtime.md`
+- `internal.md`
+- `index.md` (top-level)
+
+## Implementation Order
+
+### Phase 1: Critical Fixes (Immediate)
+1. Quarantine v2-incompatible endpoints
+2. Fix TimersPage mock data issue
+
+### Phase 2: Security & Standards (High)
+1. Add role guards to config endpoints
+2. Verify soft delete implementation
+3. Add basic inline documentation
+
+### Phase 3: Documentation (Medium)
+1. Complete inline documentation for all endpoints
+2. Generate split API reference docs
+3. Create top-level index
+
+### Phase 4: Verification (Low)
+1. Verify UI adoption for all completed APIs
+2. Final compliance check against API rulebook
+
+## Success Criteria
+
+- [ ] No v2-incompatible endpoints in active routing
+- [ ] All admin UIs use proper APIs (no mock data)
+- [ ] All config endpoints have admin-only role guards
+- [ ] All endpoints use soft delete correctly
+- [ ] All endpoints have inline documentation
+- [ ] API reference docs generated and indexed
+- [ ] UI adoption verified for all APIs
+
+## Blocked Items
+
+None currently identified.