spine-framework 0.3.124 → 0.3.126

package/.framework/functions/invites.ts

@@ -1,83 +1,97 @@
-/**
- * @module invites
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * Invite and access-request management. All invite/access-request state is
- * stored directly on `people` rows — no separate table. Invite metadata lives
- * in `people.data` under `invite_*` keys.
- *
- * **Routed by:** `GET/POST /.netlify/functions/invites?action=<action>`
- *
- * **Public actions (no auth required):**
- * | action            | method | description |
- * |-------------------|--------|-------------|
- * | check-first-user  | GET    | Boolean: is this the first user registration? |
- * | check-domain      | GET    | Boolean: does this email domain have existing accounts? |
- * | validate-token    | GET    | Validate invite token, return preview |
- * | complete-registration | POST | Finalise walk-up registration after Supabase auth |
- *
- * **Protected actions (require *_admin or system_admin):**
- * | action         | method | description |
- * |----------------|--------|-------------|
- * | create-invite  | POST   | Create invite stub + return shareable URL |
- * | list-invites   | GET    | List invites scoped to account (or all for system_admin) |
- * | revoke-invite  | POST   | Mark invite inactive |
- * | reinvite       | POST   | Issue new token on existing stub |
- * | block-invite   | POST   | Manually block an invite token |
- * | approve        | POST   | Approve access_request → activate person |
- * | deny           | POST   | Deny access_request → deactivate person |
- *
- * **Invite metadata in people.data:**
- * ```json
- * {
- *   "invite_token":       "abc123...",
- *   "invite_kind":        "invite" | "access_request",
- *   "invite_expires_at":  "2026-06-24T...",
- *   "invite_attempts":    0,
- *   "invite_blocked_at":  null,
- *   "invite_invited_by":  "person-uuid"
- * }
- * ```
- *
- * **people.status values used here:**
- *   invited  — unclaimed admin invite
- *   pending  — walk-up access request awaiting approval
- *   active   — approved / invite redeemed
- *   inactive — denied / revoked
- *
- * @seeAlso migrations/016_invites.sql   (indexes)
- * @seeAlso migrations/005_auth_user_trigger.sql  (stub resolution on signup)
- * @seeAlso src/pages/auth/RegisterPage.tsx  (frontend)
- * @seeAlso src/components/shared/InviteManager.tsx  (UI)
- */
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="invites_moduleheader_1783968140" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for invite management API"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import handler utilities and database access"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="Import failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, createPublicHandler, adminDb, emitLog" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler, createPublicHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
-
-// ─── CONSTANTS ────────────────────────────────────────────────────────────────
-
+import { create as adminDataCreate, list as adminDataList, update as adminDataUpdate } from './admin-data'
+// CIL[END chunk_id="invites_moduleheader_1783968140"]
+// CIL[BEGIN chunk_id="invites_constants_1783968140" type="constants" identity="constants" parent="none"]
+// CIL[DOC-MACRO purpose="Define constants for invite token generation and validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure invite security parameters and domain exclusions"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Constants" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Sets token length, max attempts, expiry days, and personal email domains" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const TOKEN_LENGTH = 16
 const MAX_ATTEMPTS = 5
 const INVITE_EXPIRY_DAYS = 7
 
-// Personal/free email domains — excluded from domain-match logic
 const PERSONAL_DOMAINS = new Set([
   'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com',
   'aol.com', 'protonmail.com', 'me.com', 'mac.com', 'live.com',
   'msn.com', 'ymail.com', 'googlemail.com', 'fastmail.com',
 ])
-
-// ─── HELPERS ──────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_constants_1783968140"]
+// CIL[BEGIN chunk_id="invites_generatetoken_1783968140" type="function" identity="generateToken" parent="none"]
+// CIL[DOC-MACRO purpose="Generate cryptographically secure random token for invites"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create unique invite tokens"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Random token string" errors="Crypto API failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses crypto.getRandomValues to generate alphanumeric token" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function generateToken(): string {
   const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
   const bytes = crypto.getRandomValues(new Uint8Array(TOKEN_LENGTH))
   return Array.from(bytes).map(b => chars[b % chars.length]).join('')
 }
-
+// CIL[END chunk_id="invites_generatetoken_1783968140"]
+// CIL[BEGIN chunk_id="invites_generateaccountslug_1783968140" type="function" identity="generateAccountSlug" parent="none"]
+// CIL[DOC-MACRO purpose="Generate unique account slug from name with random suffix"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create URL-safe account identifiers"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Unique account slug" errors="Invalid name format" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Normalizes name to lowercase, adds hyphens, appends random hash" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function generateAccountSlug(name: string): string {
   const base = name
     .toLowerCase()
@@ -87,20 +101,42 @@ function generateAccountSlug(name: string): string {
   const hash = Math.random().toString(36).slice(2, 8)
   return `${base}-${hash}`
 }
-
+// CIL[END chunk_id="invites_generateaccountslug_1783968140"]
+// CIL[BEGIN chunk_id="invites_isadminrole_1783968140" type="function" identity="isAdminRole" parent="none"]
+// CIL[DOC-MACRO purpose="Check if role slug indicates admin privileges"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate admin role permissions"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean - admin status" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks for system_admin or role ending with _admin" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function isAdminRole(roleSlug: string | undefined): boolean {
   return !!roleSlug && (
     roleSlug === 'system_admin' ||
     roleSlug.endsWith('_admin')
   )
 }
-
-// ─── PUBLIC: check-first-user ─────────────────────────────────────────────────
-
-/**
- * Returns { is_first_user: boolean } — true if there are zero people in the system.
- * Used by RegisterPage to show simplified first-user flow.
- */
+// CIL[END chunk_id="invites_isadminrole_1783968140"]
+// CIL[BEGIN chunk_id="invites_checkfirstuser_1783968140" type="function" identity="checkFirstUser" parent="none"]
+// CIL[DOC-MACRO purpose="Check if system has any users - enables first-user flow"]
+// CIL[DOC-RESPONSIBILITY responsibility="Determine if this is initial system setup"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{is_first_user: boolean}" errors="DB query failures" side_effects="DB read operation"]
+// CIL[DOC-MICRO logic_summary="Counts people records, returns true if count is zero" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const checkFirstUser = createHandler(async (_ctx, _body) => {
   const { count, error } = await adminDb
     .from('people')
@@ -110,14 +146,21 @@ export const checkFirstUser = createHandler(async (_ctx, _body) => {
 
   return { is_first_user: (count ?? 0) === 0 }
 })
-
-// ─── PUBLIC: check-domain ─────────────────────────────────────────────────────
-
-/**
- * Returns { match: boolean } — whether any active people rows exist with the
- * same email domain AND it's not a known personal domain.
- * Does NOT return account names or IDs to avoid leaking structure.
- */
+// CIL[END chunk_id="invites_checkfirstuser_1783968140"]
+// CIL[BEGIN chunk_id="invites_checkdomain_1783968140" type="function" identity="checkDomain" parent="none"]
+// CIL[DOC-MACRO purpose="Check if email domain has existing active accounts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate domain for account matching logic"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{match: boolean}" errors="Invalid email, DB errors" side_effects="DB read operation"]
+// CIL[DOC-MICRO logic_summary="Excludes personal domains, checks for active accounts with same domain" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const checkDomain = createHandler(async (_ctx, _body) => {
   const email = _ctx.query?.email as string | undefined
   if (!email || !email.includes('@')) {
@@ -139,13 +182,21 @@ export const checkDomain = createHandler(async (_ctx, _body) => {
 
   return { match: (data?.length ?? 0) > 0 }
 })
-
-// ─── PUBLIC: validate-token ───────────────────────────────────────────────────
-
-/**
- * Looks up a people row by invite_token. Returns a safe preview (no UUIDs).
- * Increments invite_attempts; blocks the token after MAX_ATTEMPTS failures.
- */
+// CIL[END chunk_id="invites_checkdomain_1783968140"]
+// CIL[BEGIN chunk_id="invites_validatetoken_1783968140" type="function" identity="validateToken" parent="none"]
+// CIL[DOC-MACRO purpose="Validate invite token and return safe preview data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Authenticate invite tokens and track attempts"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Invite preview data" errors="Token invalid/expired/blocked" side_effects="Updates attempt count, blocks after max attempts"]
+// CIL[DOC-MICRO logic_summary="Validates token, checks expiry/blocked status, increments attempts, blocks after max" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const validateToken = createHandler(async (_ctx, _body) => {
   const token = _ctx.query?.token as string | undefined
   if (!token) throw new Error('Token is required')
@@ -163,17 +214,14 @@ export const validateToken = createHandler(async (_ctx, _body) => {
 
   const meta = person.data || {}
 
-  // Check blocked
   if (meta.invite_blocked_at) {
     throw new Error('This invite link has been blocked. Please contact the administrator.')
   }
 
-  // Check expiry
   if (meta.invite_expires_at && new Date(meta.invite_expires_at) < new Date()) {
     throw new Error('This invite link has expired. Please request a new one.')
   }
 
-  // Increment attempts
   const attempts = (meta.invite_attempts || 0) + 1
   const blocked = attempts >= MAX_ATTEMPTS
 
@@ -204,16 +252,23 @@ export const validateToken = createHandler(async (_ctx, _body) => {
     kind: meta.invite_kind,
   }
 })
-
-// ─── PUBLIC: complete-registration ───────────────────────────────────────────
-
-/**
- * Called by RegisterPage after Supabase auth.signUp completes.
- * Handles three walk-up paths:
- *   new_account   — creates account + activates person as *_admin
- *   join_request  — creates access_request stub (person stays pending)
- *   (invite path is handled entirely in the DB trigger)
- */
+// CIL[END chunk_id="invites_validatetoken_1783968140"]
+// CIL[BEGIN chunk_id="invites_completeregistration_1783968140" type="function" identity="completeRegistration" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:person/person" content="completeRegistration creates people records stamped with the person type's design_schema: full_name(text,required,system), email(email,required,system), phone(phone,system), status(text,required,system), is_active(boolean,required,system), avatar_url(url,system), created_at/updated_at(datetime,readonly,system). record_permissions allows member/member_admin/support/support_admin create/read/update and system_admin delete."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="The person record must have an account_id and role. The person type uses system=true for all fields, so values live on the people row, not in person.data."]
+// CIL[DOC-MACRO purpose="Complete user registration after Supabase auth with multiple paths"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle walk-up registration flows and account assignment"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Registration result" errors="Invalid path, missing params, DB errors" side_effects="DB updates, role resolution"]
+// CIL[DOC-MICRO logic_summary="Handles new_account, existing_account, and join_request paths with role resolution" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const completeRegistration = createHandler(async (ctx, body) => {
   const { path, account_name, email, role_slug, target_account } = body
 
@@ -224,7 +279,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
   if (path === 'existing_account') {
     if (!target_account) throw new Error('target_account is required for existing_account path')
 
-    // Resolve the target account
     const { data: targetAccount } = await adminDb
       .from('accounts')
       .select('id, slug')
@@ -235,7 +289,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       throw new Error(`Target account '${target_account}' not found`)
     }
 
-    // Resolve person type_id
     const { data: personType } = await adminDb
       .from('types')
       .select('id, design_schema, validation_schema')
@@ -243,7 +296,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       .eq('slug', 'person')
       .single()
 
-    // Resolve role from role_slug param
     const targetRoleSlug = role_slug || 'member'
     
     let { data: roles } = await adminDb
@@ -254,7 +306,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
 
     let role = roles?.[0]
 
-    // If specific role not found, try member_admin or member as fallback
     if (!role) {
       const { data: fallbackRoles } = await adminDb
         .from('roles')
@@ -265,7 +316,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       role = fallbackRoles?.[0]
     }
 
-    // Update the walk-up shell to be an active user on the target account
     const { error: updateErr } = await adminDb
       .from('people')
       .update({
@@ -291,7 +341,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
   if (path === 'new_account') {
     if (!account_name) throw new Error('account_name is required for new_account path')
 
-    // Resolve person type_id
     const { data: personType } = await adminDb
       .from('types')
       .select('id, design_schema, validation_schema')
@@ -299,7 +348,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       .eq('slug', 'person')
       .single()
 
-    // Resolve account type_id
     const { data: accountType } = await adminDb
       .from('types')
       .select('id')
@@ -307,7 +355,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       .eq('slug', 'account')
       .single()
 
-    // Resolve role from role_slug param, or fall back to member_admin/member lookup
     const targetRoleSlug = role_slug || 'member'
     
     let { data: roles } = await adminDb
@@ -318,7 +365,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
 
     let role = roles?.[0]
 
-    // If specific role not found, try member_admin or member as fallback
     if (!role) {
       const { data: fallbackRoles } = await adminDb
         .from('roles')
@@ -329,8 +375,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       role = fallbackRoles?.[0]
     }
 
-    // If no roles exist yet and no specific role was requested, create a default member role
-    // But only if we're not trying to assign a specific app role
     if (!role && !role_slug) {
       const { data: newRole, error: roleErr } = await adminDb
         .from('roles')
@@ -349,7 +393,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       }
     }
 
-    // Create account
     const slug = generateAccountSlug(account_name)
     const { data: account, error: accErr } = await adminDb
       .from('accounts')
@@ -364,7 +407,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
 
     if (accErr || !account) throw new Error('Failed to create account: ' + accErr?.message)
 
-    // Update the walk-up person shell (created by trigger as minimal record)
     const { error: pErr } = await adminDb
       .from('people')
       .update({
@@ -375,7 +417,7 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       })
       .eq('email', email)
       .eq('status', 'active')
-      .is('role_id', null)   // only the newly created shell
+      .is('role_id', null)
 
     if (pErr) throw new Error('Failed to update person: ' + pErr.message)
 
@@ -386,7 +428,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
     const { target_account_id, role_slug } = body
     if (!target_account_id) throw new Error('target_account_id is required for join_request')
 
-    // Resolve role from role_slug param, or fall back to member
     const targetRoleSlug = role_slug || 'member'
     let { data: roles } = await adminDb
       .from('roles')
@@ -396,7 +437,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
 
     let role = roles?.[0]
 
-    // Fallback to member if specific role not found
     if (!role) {
       const { data: fallbackRoles } = await adminDb
         .from('roles')
@@ -406,7 +446,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       role = fallbackRoles?.[0]
     }
 
-    // Resolve type_id
     const { data: personType } = await adminDb
       .from('types')
       .select('id, design_schema, validation_schema')
@@ -414,7 +453,6 @@ export const completeRegistration = createHandler(async (ctx, body) => {
       .eq('slug', 'person')
       .single()
 
-    // Update the walk-up shell to be a pending access request on the target account
     const { error: pErr } = await adminDb
       .from('people')
       .update({
@@ -439,21 +477,21 @@ export const completeRegistration = createHandler(async (ctx, body) => {
 
   throw new Error('Unknown registration path: ' + path)
 })
-
-// ─── PROTECTED: create-invite ─────────────────────────────────────────────────
-
-/**
- * Creates a stub people row (status: 'invited') with invite metadata.
- * Returns the shareable token URL.
- * Requires *_admin role scoped to the target account, or system_admin.
- *
- * @param full_name        - Invitee's name (admin-entered, shown on register page)
- * @param email            - Invitee's email address (locked on register page)
- * @param account_id       - Account to invite into
- * @param role_slug        - Role slug to assign (e.g. 'member', 'support')
- * @param allowed_role_slugs - Optional whitelist of permitted role slugs for this context
- * @param base_url         - Origin to use for the invite URL (window.location.origin from client)
- */
+// CIL[END chunk_id="invites_completeregistration_1783968140"]
+// CIL[BEGIN chunk_id="invites_createinvite_1783968140" type="function" identity="createInvite" parent="none"]
+// CIL[DOC-MACRO purpose="Create invite stub with metadata and return shareable URL"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate new invite tokens and create person records"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{id, token, invite_url, expires_at}" errors="Auth required, permission denied, DB errors" side_effects="DB insert, audit logging"]
+// CIL[DOC-MICRO logic_summary="Validates admin permissions, creates person stub with invite metadata, generates token" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const createInvite = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') {
     throw new Error('Authentication required')
@@ -464,7 +502,6 @@ export const createInvite = createHandler(async (ctx, body) => {
     throw new Error('email, account_id, and role_slug are required')
   }
 
-  // Verify caller is admin for this account
   const { data: caller } = await adminDb
     .from('people')
     .select('role:roles(slug)')
@@ -483,12 +520,10 @@ export const createInvite = createHandler(async (ctx, body) => {
     throw new Error('Insufficient permissions — *_admin role required to create invites')
   }
 
-  // Enforce allowed_role_slugs whitelist if provided
   if (allowed_role_slugs && Array.isArray(allowed_role_slugs) && !allowed_role_slugs.includes(role_slug)) {
     throw new Error(`Role '${role_slug}' is not permitted in this context`)
   }
 
-  // Resolve role_id from slug
   const { data: roleRows } = await adminDb
     .from('roles')
     .select('id, slug')
@@ -498,7 +533,6 @@ export const createInvite = createHandler(async (ctx, body) => {
   const resolvedRole = roleRows?.[0]
   if (!resolvedRole) throw new Error(`Role '${role_slug}' not found`)
 
-  // Check for existing unclaimed invite for this email+account
   const { data: existing } = await adminDb
     .from('people')
     .select('id')
@@ -511,7 +545,6 @@ export const createInvite = createHandler(async (ctx, body) => {
     throw new Error('A person with this email already exists or has a pending invite for this account')
   }
 
-  // Resolve type_id for person
   const { data: personType } = await adminDb
     .from('types')
     .select('id, design_schema, validation_schema')
@@ -523,31 +556,27 @@ export const createInvite = createHandler(async (ctx, body) => {
   const expiresAt = new Date(Date.now() + INVITE_EXPIRY_DAYS * 86400 * 1000).toISOString()
   const stubName = (full_name && full_name.trim()) ? full_name.trim() : email.split('@')[0]
 
-  const { data: stub, error: insertErr } = await adminDb
-    .from('people')
-    .insert({
-      email,
-      full_name: stubName,
-      account_id,
-      role_id: resolvedRole.id,
-      type_id: personType?.id,
-      status: 'invited',
-      is_active: true,
-      design_schema: personType?.design_schema ?? {},
-      validation_schema: personType?.validation_schema ?? {},
-      data: {
-        invite_token: token,
-        invite_kind: 'invite',
-        invite_expires_at: expiresAt,
-        invite_attempts: 0,
-        invite_blocked_at: null,
-        invite_invited_by: ctx.principal.id,
-      },
-    })
-    .select('id')
-    .single()
+  const adminCtx = { ...ctx, query: { ...ctx.query, entity: 'people' } }
+  const stub = await adminDataCreate(adminCtx, {
+    entity: 'people',
+    type_id: personType?.id,
+    account_id,
+    full_name: stubName,
+    email,
+    role_id: resolvedRole.id,
+    status: 'invited',
+    is_active: true,
+    data: {
+      invite_token: token,
+      invite_kind: 'invite',
+      invite_expires_at: expiresAt,
+      invite_attempts: 0,
+      invite_blocked_at: null,
+      invite_invited_by: ctx.principal.id,
+    },
+  })
 
-  if (insertErr || !stub) throw new Error('Failed to create invite: ' + insertErr?.message)
+  if (!stub) throw new Error('Failed to create invite')
 
   const appBaseUrl = base_url || process.env.APP_BASE_URL || 'https://yourapp.com'
   const inviteUrl = `${appBaseUrl}/register?t=${token}`
@@ -558,17 +587,21 @@ export const createInvite = createHandler(async (ctx, body) => {
 
   return { id: stub.id, token, invite_url: inviteUrl, expires_at: expiresAt }
 })
-
-// ─── PROTECTED: list-invites ──────────────────────────────────────────────────
-
-/**
- * Lists people rows with invite metadata.
- * system_admin sees all accounts; others see only their account.
- *
- * @param account_id   - Filter to a specific account (required for non-system_admin)
- * @param role_slugs   - Comma-separated role slugs to filter by (e.g. 'support,support_admin')
- *                       When provided only people with one of these roles are returned.
- */
+// CIL[END chunk_id="invites_createinvite_1783968140"]
+// CIL[BEGIN chunk_id="invites_listinvites_1783968140" type="function" identity="listInvites" parent="none"]
+// CIL[DOC-MACRO purpose="List invite records with filtering and role-based access control"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query and return scoped invite data"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of invite records" errors="Auth required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Filters by account scope, role slugs, returns mapped invite data" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const listInvites = createHandler(async (ctx, _body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') {
     throw new Error('Authentication required')
@@ -577,12 +610,10 @@ export const listInvites = createHandler(async (ctx, _body) => {
   const isSystemAdmin = ctx.principal.permissions?.includes('system')
   const { account_id: queryAccountId, role_slugs: queryRoleSlugs } = ctx.query || {}
 
-  // Parse optional role slug filter (comma-separated string from query param)
   const roleSlugsFilter: string[] | null = queryRoleSlugs
     ? (queryRoleSlugs as string).split(',').map((s: string) => s.trim()).filter(Boolean)
     : null
 
-  // If role slug filter is provided, resolve to role IDs first
   let roleIdFilter: string[] | null = null
   if (roleSlugsFilter && roleSlugsFilter.length > 0) {
     const { data: roleRows } = await adminDb
@@ -592,7 +623,6 @@ export const listInvites = createHandler(async (ctx, _body) => {
 
     roleIdFilter = (roleRows || []).map(r => r.id)
     if (roleIdFilter.length === 0) {
-      // No matching roles — return empty list rather than unfiltered
       return []
     }
   }
@@ -610,7 +640,6 @@ export const listInvites = createHandler(async (ctx, _body) => {
     .order('created_at', { ascending: false })
 
   if (!isSystemAdmin) {
-    // Scoped to caller's account
     const scopedAccountId = queryAccountId || ctx.accountId
     if (!scopedAccountId) throw new Error('Account scope required')
     query = query.eq('account_id', scopedAccountId)
@@ -638,9 +667,21 @@ export const listInvites = createHandler(async (ctx, _body) => {
     role: Array.isArray(row.role) ? row.role[0] : row.role,
   }))
 })
-
-// ─── PROTECTED: revoke-invite ─────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_listinvites_1783968140"]
+// CIL[BEGIN chunk_id="invites_revokeinvite_1783968140" type="function" identity="revokeInvite" parent="none"]
+// CIL[DOC-MACRO purpose="Soft-delete invite by setting status to inactive"]
+// CIL[DOC-RESPONSIBILITY responsibility="Revoke pending or invited person records"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{success: boolean}" errors="Auth required, person not found, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Sets person status to inactive, clears invite token, logs revocation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const revokeInvite = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
 
@@ -672,9 +713,21 @@ export const revokeInvite = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-
-// ─── PROTECTED: reinvite ──────────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_revokeinvite_1783968140"]
+// CIL[BEGIN chunk_id="invites_reinvite_1783968140" type="function" identity="reinvite" parent="none"]
+// CIL[DOC-MACRO purpose="Issue new token for existing invite record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Regenerate invite tokens for expired invites"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{token, invite_url, expires_at}" errors="Auth required, person not found, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Generates new token, resets attempts, updates expiry, returns new URL" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const reinvite = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
 
@@ -721,9 +774,21 @@ export const reinvite = createHandler(async (ctx, body) => {
 
   return { token: newToken, invite_url: inviteUrl, expires_at: expiresAt }
 })
-
-// ─── PROTECTED: approve ───────────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_reinvite_1783968140"]
+// CIL[BEGIN chunk_id="invites_approve_1783968140" type="function" identity="approve" parent="none"]
+// CIL[DOC-MACRO purpose="Approve pending access request and activate person"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert pending access requests to active users"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{success: boolean}" errors="Auth required, request not found, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Sets status to active, strips invite metadata, logs approval" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const approve = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
 
@@ -739,7 +804,6 @@ export const approve = createHandler(async (ctx, body) => {
 
   if (!person) throw new Error('Access request not found or already processed')
 
-  // Strip invite metadata on approval
   const { invite_token, invite_kind, invite_expires_at, invite_attempts, invite_blocked_at, invite_invited_by, ...remainingData } =
     (person.data as any) || {}
 
@@ -761,14 +825,21 @@ export const approve = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-
-// ─── PROTECTED: block-invite ─────────────────────────────────────────────────
-
-/**
- * Manually blocks an invite — sets invite_blocked_at on the people.data JSONB.
- * The token remains but validate-token will refuse it.
- * Useful for flagging suspicious or failed invite attempts before they auto-block.
- */
+// CIL[END chunk_id="invites_approve_1783968140"]
+// CIL[BEGIN chunk_id="invites_blockinvite_1783968140" type="function" identity="blockInvite" parent="none"]
+// CIL[DOC-MACRO purpose="Manually block an invite token from being used"]
+// CIL[DOC-RESPONSIBILITY responsibility="Flag suspicious or failed invite attempts"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{success: boolean}" errors="Auth required, person not found, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Sets invite_blocked_at timestamp to prevent token validation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const blockInvite = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
 
@@ -804,9 +875,21 @@ export const blockInvite = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-
-// ─── PROTECTED: deny ──────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_blockinvite_1783968140"]
+// CIL[BEGIN chunk_id="invites_deny_1783968140" type="function" identity="deny" parent="none"]
+// CIL[DOC-MACRO purpose="Deny pending access request and deactivate person"]
+// CIL[DOC-RESPONSIBILITY responsibility="Reject access requests and mark users inactive"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{success: boolean}" errors="Auth required, request not found, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Sets status to inactive and is_active false, logs denial" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const deny = createHandler(async (ctx, body) => {
   if (!ctx.principal || ctx.principal.id === 'anonymous') throw new Error('Authentication required')
 
@@ -839,19 +922,29 @@ export const deny = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="invites_deny_1783968140"]
+// CIL[BEGIN chunk_id="invites_handler_1783968140" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route invite actions to appropriate handler functions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch invite API requests to correct handlers"]
+// CIL[DOC-CONTEXT module="invites" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by action" errors="Unknown action" side_effects="Delegates to handlers"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes action parameter to appropriate handler function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createPublicHandler(async (ctx, body) => {
   const action = ctx.query?.action
 
   switch (action) {
-    // Public endpoints (no auth required)
     case 'check-first-user':    return await checkFirstUser(ctx, body)
     case 'check-domain':        return await checkDomain(ctx, body)
     case 'validate-token':      return await validateToken(ctx, body)
     case 'complete-registration': return await completeRegistration(ctx, body)
-    // Protected endpoints (require auth)
     case 'create-invite':       return await createInvite(ctx, body)
     case 'list-invites':        return await listInvites(ctx, body)
     case 'revoke-invite':       return await revokeInvite(ctx, body)
@@ -859,7 +952,114 @@ export const handler = createPublicHandler(async (ctx, body) => {
     case 'block-invite':        return await blockInvite(ctx, body)
     case 'approve':             return await approve(ctx, body)
     case 'deny':                return await deny(ctx, body)
+    case 'list-members':        return await listMembers(ctx, body)
+    case 'update-member':       return await updateMember(ctx, body)
+    case 'deactivate-member':   return await deactivateMember(ctx, body)
     default:
       throw new Error(`Unknown action: ${action}`)
   }
 })
+// CIL[END chunk_id="invites_handler_1783968140"]
+
+// ─── Member management actions (runtime CRUD via admin-data) ─────────────────
+
+function canManageMembers(ctx: any) {
+  if (!ctx.principal || ctx.principal.id === 'anonymous') return false
+  if (ctx.principal.permissions?.includes('system')) return true
+  return (ctx.principal.roles || []).some((r: string) => isAdminRole(r))
+}
+
+async function listMembers(ctx: any, body: any) {
+  if (!canManageMembers(ctx)) {
+    throw new Error('Insufficient permissions — *_admin role required to list members')
+  }
+
+  const accountId = ctx.query?.account_id || body?.account_id || ctx.principal?.accountId
+  if (!accountId) throw new Error('account_id is required')
+
+  const adminCtx = { ...ctx, query: { ...ctx.query, entity: 'people', type_slug: 'person', account_id: accountId } }
+  const records = await adminDataList(adminCtx, {})
+
+  const roleIds = (records || [])
+    .map((r: any) => r.role_id)
+    .filter(Boolean)
+  const roleMap: Record<string, { slug: string; name: string }> = {}
+  if (roleIds.length) {
+    const { data: roles } = await adminDb
+      .from('roles')
+      .select('id, slug, name')
+      .in('id', roleIds)
+    for (const r of roles || []) {
+      roleMap[r.id] = { slug: r.slug, name: r.name }
+    }
+  }
+
+  const data = (records || []).map((r: any) => ({
+    ...r,
+    role: r.role_id ? roleMap[r.role_id] || { id: r.role_id } : null
+  }))
+
+  return { data }
+}
+
+async function resolveRoleId(slug: string) {
+  const { data: roleRows } = await adminDb
+    .from('roles')
+    .select('id, slug')
+    .eq('slug', slug)
+    .limit(1)
+  const resolved = roleRows?.[0]
+  if (!resolved) throw new Error(`Role '${slug}' not found`)
+  return resolved.id
+}
+
+async function updateMember(ctx: any, body: any) {
+  if (!canManageMembers(ctx)) {
+    throw new Error('Insufficient permissions — *_admin role required to update members')
+  }
+
+  const { person_id, full_name, role_slug } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const recordData: any = {}
+  if (full_name !== undefined) recordData.full_name = full_name
+  if (role_slug !== undefined) recordData.role_id = await resolveRoleId(role_slug)
+
+  if (Object.keys(recordData).length === 0) {
+    throw new Error('No update fields provided')
+  }
+
+  const adminCtx = {
+    ...ctx,
+    query: { ...ctx.query, entity: 'people', id: person_id }
+  }
+
+  const updated = await adminDataUpdate(adminCtx, recordData)
+  if (!updated) throw new Error('Failed to update member')
+
+  await emitLog(ctx, 'member.updated', { type: 'person', id: person_id }, { after: recordData })
+  return { success: true, data: updated }
+}
+
+async function deactivateMember(ctx: any, body: any) {
+  if (!canManageMembers(ctx)) {
+    throw new Error('Insufficient permissions — *_admin role required to deactivate members')
+  }
+
+  const { person_id } = body
+  if (!person_id) throw new Error('person_id is required')
+
+  const adminCtx = {
+    ...ctx,
+    query: { ...ctx.query, entity: 'people', id: person_id }
+  }
+
+  const updated = await adminDataUpdate(adminCtx, {
+    status: 'inactive',
+    is_active: false,
+  })
+  if (!updated) throw new Error('Failed to deactivate member')
+
+  await emitLog(ctx, 'member.deactivated', { type: 'person', id: person_id }, {})
+  return { success: true, data: updated }
+}