spine-framework 0.1.61 → 1.0.0

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

@@ -1,170 +0,0 @@
-# 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

@@ -1,95 +0,0 @@
-# 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

@@ -1,77 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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.