spine-framework 0.3.125 → 0.3.126

package/.framework/functions/admin-data.ts

@@ -1,98 +1,47 @@
-// ─── CHUNK_START: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
-/**
- * @module admin-data
- * @audience both
- * @layer api-handler
- * @stability stable
- *
- * Generic CRUD API for all runtime entities. Provides list, get, create,
- * update, delete, and stats operations over a validated set of entity tables.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/admin-data`
- *
- * **Dispatch table (query params → handler):**
- * | method | ?action | ?id present | Handler |
- * |--------|---------|-------------|---------|
- * | GET    | list    | any         | `list`  |
- * | GET    | get     | any         | `get`   |
- * | GET    | stats   | any         | `stats` |
- * | GET    | —       | yes         | `get`   |
- * | GET    | —       | no          | `list`  |
- * | POST   | —       | —           | `create`|
- * | PATCH  | —       | —           | `update`|
- * | DELETE | —       | —           | `remove`|
- *
- * **Authorization:** All DB reads/writes use `ctx.db` (RLS-scoped client).
- * RLS policies on each table enforce account hierarchy access automatically.
- * `adminDb` is used only for lookups that need bypass (type resolution).
- *
- * **Valid entities:** `accounts`, `people`, `items`, `threads`, `messages`,
- * `links`, `attachments`, `watchers`.
- *
- * INVARIANT: every `create` call requires `type_id` in the body — all runtime
- *   records must reference a type.
- * INVARIANT: trigger dispatch (create/update/delete) is fire-and-forget —
- *   trigger failures are logged but never surface to the caller.
- * INVARIANT: all returned records are passed through `sanitizeRecordData`
- *   before being returned — field-level permission stripping is always applied.
- *
- * @seeAlso middleware.ts (createHandler, CoreContext)
- * @seeAlso permissions.ts (sanitizeRecordData)
- * @seeAlso trigger-engine.ts (fire*Triggers)
- * @seeAlso types.ts (types table, design_schema, validation_schema)
- */
 
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="admin-data_module_header_1784019432" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for generic CRUD operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware, permissions, database access, type resolution, and triggers"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/db.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules,constants" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports modules and defines entity validation constants" 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/functions/_shared/db.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// 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 } from './_shared/middleware'
-import { sanitizeRecordData } from './_shared/permissions'
+import { sanitizeRecordData, resolveFirstSurfacePermissions, validateUpdatePermissions } from './_shared/permissions'
 import { adminDb } from './_shared/db'
-import { resolveTypeId, resolveTypeRecord } from './_shared/resolve-ids'
+import { isSystemAdmin } from './_shared/principal'
+import { resolveTypeId, resolveTypeIds, resolveTypeRecord } from './_shared/resolve-ids'
 import { fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './_shared/trigger-engine'
-// ─── CHUNK_END: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_MODULE_HEADER ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_MODULE_HEADER_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Module Header
- * @micro       Module-level documentation with routing table and invariants
- * @inputs      none
- * @outputs     none
- * @depends-on  [none]
- * @depended-by [all chunks]
- * @side-effects [none]
- * @tags        admin, module, routing, invariants
- */
-// ─── CHUNK_END: ADMIN_DATA_MODULE_HEADER ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_IMPORTS_AND_CONSTANTS ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_IMPORTS_AND_CONSTANTS_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Imports and Constants
- * @micro       Module imports and constant definitions
- * @inputs      none
- * @outputs     none
- * @depends-on  [none]
- * @depended-by [all handlers]
- * @side-effects [none]
- * @tags        admin, imports, constants
- */
+import { withAdminLogging } from './_shared/logging'
 
 const PERMISSIONS_ALL = {
   record_permissions: { all: ['create', 'read', 'update', 'delete'] },
   fields: {}
 }
 
-/**
- * Allowlist of entity table names accepted by this handler.
- * Any entity string not in this set causes a 400-equivalent throw.
- */
-const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'item_progress']
+const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'item_progress', 'logs', 'test_runs', 'observability', 'test_cases', 'types', 'link_types', 'ai_agents', 'prompt_configs']
+
+const RAW_ENTITIES = ['logs', 'test_runs', 'observability', 'test_cases']
 
-// Map admin-data entity names to the kind field used in the types table
 const ENTITY_TO_KIND: Record<string, string> = {
+  accounts: 'account',
+  people: 'person',
   items: 'item',
   threads: 'thread',
   messages: 'message',
@@ -101,434 +50,643 @@ const ENTITY_TO_KIND: Record<string, string> = {
   watchers: 'watcher',
   item_progress: 'item_progress'
 }
-// ─── CHUNK_END: ADMIN_DATA_IMPORTS_AND_CONSTANTS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_HANDLERS_SECTION ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_HANDLERS_SECTION_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Handlers Section Header
- * @micro       Section marker for CRUD handler functions
- * @inputs      none
- * @outputs     none
- * @depends-on  [none]
- * @depended-by [none]
- * @side-effects [none]
- * @tags        admin, section, handlers
- */
-// ─── CHUNK_END: ADMIN_DATA_HANDLERS_SECTION ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_LIST_1_0_0
- * @version     1.0.0
- * @hash        780f1f0c81ea3bff78d40970ba4b03e3211d892bb883e6a099c6e0a55ee53b0c
- * @macro       Entity List Handler
- * @micro       Lists records with filtering, search, sorting, and pagination
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized records or {data, schema, view} with view config
- * @depends-on  [createHandler, sanitizeRecordData, adminDb, getSearchField]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        admin, crud, list, pagination, search
- */
+// CIL[END chunk_id="admin-data_module_header_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_list_1784019432" type="function" identity="list" parent="none"]
+// CIL[DOC-MACRO purpose="List entity records with filtering and pagination"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query, filter, paginate, and sanitize entity records"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_records[] or {data,schema,view}" errors="entity_required,database_error" side_effects="database_queries,permission_filtering"]
+// CIL[DOC-MICRO logic_summary="Builds query with filters, applies pagination, sanitizes results, optionally resolves views" 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: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// 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 list = createHandler(async (ctx, _body) => {
-  // Extract all reserved query params to prevent them from being used as column filters
-  const { entity, action, method, search, sort_field = 'created_at', sort_direction = 'desc', limit = 50, offset = 0, type_slug, view: viewSlug, ...filters } = ctx.query || {}
+  const { entity, action, method, search, sort_field = 'created_at', sort_direction = 'desc', limit = 50, offset = 0, type_slug, type_slugs, view: viewSlug, ...filters } = ctx.query || {}
+
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'list',
+      method: method || 'GET',
+      filters,
+      typeSlug: type_slug
+    },
+    async () => {
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        throw new Error('Valid entity parameter is required')
+      }
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    throw new Error('Valid entity parameter is required')
-  }
+      const db = (ctx.principal?.isInternal || isSystemAdmin(ctx.principal)) ? adminDb : ctx.db
+      let query = db.from(entity).select('*')
 
-  // Use ctx.db - RLS-scoped client based on principal
-  // RLS policies enforce account hierarchy access automatically
-  let query = ctx.db.from(entity).select('*')
+      const targetSlugs: string[] = []
+      if (type_slug) targetSlugs.push(type_slug)
+      if (type_slugs) {
+        const raw = Array.isArray(type_slugs) ? type_slugs : (type_slugs as string).split(',').map(s => s.trim()).filter(Boolean)
+        targetSlugs.push(...raw)
+      }
+      if (targetSlugs.length) {
+        const kind = ENTITY_TO_KIND[entity]
+        if (kind) {
+          try {
+            const resolved = await resolveTypeIds(targetSlugs.map(slug => ({ kind, slug })))
+            const typeIds = Object.values(resolved)
+            if (typeIds.length === 1) {
+              query = query.eq('type_id', typeIds[0])
+            } else if (typeIds.length > 1) {
+              query = query.in('type_id', typeIds)
+            }
+          } catch (err: any) {
+            if (err?.message?.includes('Type not found')) {
+              return []
+            }
+            throw err
+          }
+        }
+      }
 
-  // Apply type_slug filter if provided (for schema-driven entities)
-  if (type_slug) {
-    const kind = ENTITY_TO_KIND[entity]
-    if (kind) {
-      // Resolve the type ID from the slug via the shared resolver
-      const typeId = await resolveTypeId(kind, type_slug)
-      if (typeId) {
-        query = query.eq('type_id', typeId)
+      if (search) {
+        const searchField = getSearchField(entity)
+        query = query.ilike(searchField, `%${search}%`)
       }
-    }
-  }
 
-  // Apply search if provided
-  if (search) {
-    // Search in display field based on entity
-    const searchField = getSearchField(entity)
-    query = query.ilike(searchField, `%${search}%`)
-  }
+      Object.entries(filters).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          if (key === 'is_active' || key === 'is_verified' || key === 'is_primary') {
+            query = query.eq(key, value === 'true')
+          } else {
+            query = query.eq(key, value)
+          }
+        }
+      })
 
-  // Apply filters
-  Object.entries(filters).forEach(([key, value]) => {
-    if (value !== undefined && value !== null && value !== '') {
-      if (key === 'is_active' || key === 'is_verified' || key === 'is_primary') {
-        query = query.eq(key, value === 'true')
-      } else {
-        query = query.eq(key, value)
+      query = query.order(sort_field, { ascending: sort_direction === 'asc' })
+
+      const { count, error: countError } = await db.from(entity)
+        .select('*', { count: 'exact', head: true })
+
+      if (countError) {
+        console.error('List count error:', countError)
+        throw new Error(countError.message || 'Database error getting count')
       }
-    }
-  })
 
-  // Apply sorting
-  query = query.order(sort_field, { ascending: sort_direction === 'asc' })
+      query = query.range(parseInt(offset.toString()), parseInt(offset.toString()) + parseInt(limit.toString()) - 1)
 
-  // Get total count (RLS filters automatically)
-  const { count, error: countError } = await ctx.db.from(entity)
-    .select('*', { count: 'exact', head: true })
+      const { data, error: err } = await query
 
-  if (countError) {
-    console.error('List count error:', countError)
-    throw new Error(countError.message || 'Database error getting count')
-  }
+      if (err) {
+        console.error('List query error:', err)
+        throw new Error(err.message || 'Database error listing records')
+      }
 
-  // Apply pagination
-  query = query.range(parseInt(offset.toString()), parseInt(offset.toString()) + parseInt(limit.toString()) - 1)
+      const sanitizedData = []
+      for (const record of data || []) {
+        const sanitizedRecord = await sanitizeRecordData(ctx, record, entity)
+        sanitizedData.push(sanitizedRecord)
+      }
 
-  const { data, error: err } = await query
+      if (viewSlug && type_slug) {
+        const { data: typeRecord } = await adminDb
+          .from('types')
+          .select('design_schema')
+          .eq('slug', type_slug)
+          .eq('is_active', true)
+          .single()
+
+        if (typeRecord?.design_schema) {
+          const schema = typeRecord.design_schema
+          const resolvedView = schema.views?.[viewSlug] || null
+          return { data: sanitizedData, schema, view: resolvedView }
+        }
+      }
+
+      return sanitizedData
+    }
+  )
+})
+// CIL[END chunk_id="admin-data_list_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_get_1784019432" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Get single entity record by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and sanitize individual entity record"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_record or {data,schema,view}" errors="entity_required,id_required,record_not_found" side_effects="database_query,permission_filtering"]
+// CIL[DOC-MICRO logic_summary="Queries single record by ID, applies permission sanitization, optionally resolves view" 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, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// 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"]
+async function attachLineage(record: any, ctx: any): Promise<void> {
+  const parentFields = ['epic_id', 'sprint_id', 'initiative_id', 'discovery_id', 'idea_id']
+  const childrenMap: Record<string, { field: string; childSlugs: string[] }> = {
+    workbench_idea: { field: 'idea_id', childSlugs: ['workbench_discovery'] },
+    workbench_discovery: { field: 'discovery_id', childSlugs: ['workbench_initiative'] },
+    workbench_initiative: { field: 'initiative_id', childSlugs: ['workbench_epic', 'workbench_work_item'] },
+    workbench_epic: { field: 'epic_id', childSlugs: ['workbench_work_item', 'workbench_sprint'] },
+    workbench_sprint: { field: 'sprint_id', childSlugs: ['workbench_work_item'] },
+    workbench_work_item: { field: '', childSlugs: [] },
+  }
 
-  if (err) {
-    console.error('List query error:', err)
-    throw new Error(err.message || 'Database error listing records')
+  async function parentIdFor(current: any, visited: Set<string>): Promise<string | null> {
+    const { data: links } = await ctx.db.from('links').select('target_id').eq('source_id', current.id).eq('link_type', 'workbench_originated_from').eq('source_type', 'items').limit(1)
+    const linkTarget = links?.[0]?.target_id
+    if (linkTarget && !visited.has(linkTarget)) return linkTarget
+    const d = current.data || {}
+    for (const key of parentFields) {
+      const id = d[key]
+      if (id && !visited.has(id)) return id
+    }
+    return null
   }
 
-  // RLS policies already filtered the data - just sanitize
-  const sanitizedData = []
-  for (const record of data || []) {
-    const sanitizedRecord = await sanitizeRecordData(ctx, record, entity)
-    sanitizedData.push(sanitizedRecord)
+  async function getParents(record: any): Promise<any[]> {
+    const parents: any[] = []
+    const visited = new Set<string>([record.id])
+    let current: any = record
+    for (let i = 0; i < 5; i++) {
+      const parentId = await parentIdFor(current, visited)
+      if (!parentId) break
+      visited.add(parentId)
+      const { data, error } = await ctx.db.from('items').select('*').eq('id', parentId).single()
+      if (error || !data) break
+      current = data
+      const sanitized = await sanitizeRecordData(ctx, data, 'items')
+      parents.push(sanitized)
+    }
+    return parents
   }
 
-  // If ?view=slug was requested, resolve schema + view config from the type record
-  if (viewSlug && type_slug) {
-    const { data: typeRecord } = await adminDb
-      .from('types')
-      .select('design_schema')
-      .eq('slug', type_slug)
-      .eq('is_active', true)
-      .single()
-
-    if (typeRecord?.design_schema) {
-      const schema = typeRecord.design_schema
-      const resolvedView = schema.views?.[viewSlug] || null
-      return { data: sanitizedData, schema, view: resolvedView }
+  async function getChildren(record: any): Promise<any[]> {
+    const childIds = new Set<string>()
+    const { data: linkRows } = await ctx.db.from('links').select('source_id').eq('target_id', record.id).eq('link_type', 'workbench_originated_from').eq('target_type', 'items').limit(50)
+    for (const row of linkRows || []) {
+      if (row.source_id && row.source_id !== record.id) childIds.add(row.source_id)
     }
+    const { data: typeRow } = await adminDb.from('types').select('slug').eq('id', record.type_id).single()
+    const cfg = typeRow?.slug ? childrenMap[typeRow.slug] : null
+    if (cfg?.childSlugs.length) {
+      try {
+        const pairs = cfg.childSlugs.map(slug => ({ kind: 'item', slug }))
+        const resolved = await resolveTypeIds(pairs)
+        const typeIds = Object.values(resolved)
+        if (typeIds.length) {
+          const { data: dataChildren } = await ctx.db.from('items').select('id').in('type_id', typeIds).eq(`data->>${cfg.field}`, record.id)
+          for (const child of dataChildren || []) {
+            if (child.id && child.id !== record.id) childIds.add(child.id)
+          }
+        }
+      } catch (e) {
+        // ignore missing child types
+      }
+    }
+    if (childIds.size === 0) return []
+    const { data: rawChildren } = await ctx.db.from('items').select('*').in('id', Array.from(childIds))
+    const children: any[] = []
+    for (const child of rawChildren || []) {
+      if (child.id === record.id) continue
+      children.push(await sanitizeRecordData(ctx, child, 'items'))
+    }
+    return children
   }
 
-  return sanitizedData
-})
-// ─── CHUNK_END: ADMIN_DATA_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_GET_1_0_0
- * @version     1.0.0
- * @hash        7ee27702615d7ebd144e065d399635ddf7664845685345d8a8f316449f11a7cf
- * @macro       Entity Get Handler
- * @micro       Returns a single record by ID with optional view configuration
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized record or {data, schema, view} with view config
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        admin, crud, get, single-record
- */
+  const [parents, children] = await Promise.all([getParents(record), getChildren(record)])
+
+  const typeIds = new Set<string>()
+  typeIds.add(record.type_id)
+  for (const p of parents) if (p?.type_id) typeIds.add(p.type_id)
+  for (const c of children) if (c?.type_id) typeIds.add(c.type_id)
+  const { data: typeRows } = await adminDb.from('types').select('id, slug').in('id', Array.from(typeIds))
+  const slugById = new Map((typeRows || []).map((t: any) => [t.id, t.slug] as [string, string]))
+  record.type_slug = slugById.get(record.type_id) || ''
+  for (const p of parents) p.type_slug = slugById.get(p.type_id) || ''
+  for (const c of children) c.type_slug = slugById.get(c.type_id) || ''
+
+  record.parents = parents
+  record.children = children
+}
+
 export const get = createHandler(async (ctx, _body) => {
   const { entity, id, view: viewSlug } = ctx.query || {}
+  const method = ctx.query?.method || 'GET'
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    throw new Error('Valid entity parameter is required')
-  }
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'get',
+      method,
+      typeSlug: viewSlug
+    },
+    async () => {
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        throw new Error('Valid entity parameter is required')
+      }
 
-  if (!id) {
-    throw new Error('ID parameter is required')
-  }
+      if (!id) {
+        throw new Error('ID parameter is required')
+      }
 
-  // RLS will filter based on account hierarchy access
-  const { data, error: err } = await ctx.db.from(entity)
-    .select('*')
-    .eq('id', id)
-    .single()
+      const { data, error: err } = await ctx.db.from(entity)
+        .select('*')
+        .eq('id', id)
+        .single()
 
-  if (err) throw err
+      if (err) throw err
 
-  if (!data) {
-    throw new Error('Record not found')
-  }
+      if (!data) {
+        throw new Error('Record not found')
+      }
 
-  const sanitizedRecord = await sanitizeRecordData(ctx, data, entity)
+      const sanitizedRecord = await sanitizeRecordData(ctx, data, entity)
 
-  // If ?view=slug was requested, include schema + resolved view from the record's stamped schema
-  if (viewSlug && sanitizedRecord?.design_schema) {
-    const schema = sanitizedRecord.design_schema
-    const resolvedView = schema.views?.[viewSlug] || null
-    return { data: sanitizedRecord, schema, view: resolvedView }
-  }
+      if (entity === 'items') {
+        await attachLineage(sanitizedRecord, ctx)
+      }
+
+      if (viewSlug && sanitizedRecord?.design_schema) {
+        const schema = sanitizedRecord.design_schema
+        const resolvedView = schema.views?.[viewSlug] || null
+        return { data: sanitizedRecord, schema, view: resolvedView }
+      }
 
-  return sanitizedRecord
+      return sanitizedRecord
+    }
+  )
 })
-// ─── CHUNK_END: ADMIN_DATA_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_CREATE_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Entity Create Handler
- * @micro       Creates a new record for an entity with type resolution and triggers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body with entity, type_id/type_slug, and record fields
- * @outputs     Sanitized created record
- * @depends-on  [createHandler, sanitizeRecordData, adminDb, resolveTypeId, fireCreateTriggers]
- * @depended-by [Netlify function routing]
- * @side-effects [DB write, type lookup, async trigger fire]
- * @tags        admin, crud, create, type-resolution
- */
+// CIL[END chunk_id="admin-data_get_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_create_1784019432" type="function" identity="create" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/stamping" content="Every runtime record is stamped with type.design_schema and type.validation_schema from the types table. resolveTypeRecord resolves kind+slug or type_id. admin-data create inherits scope from parent, applies PERMISSIONS_ALL default when record_permissions is missing, sets system fields on the row and non-system fields in record.data, then fires triggers. This applies to all kinds: account, person, item, thread, message, link, attachment, watcher."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="If a type row lacks record_permissions, the created record receives PERMISSIONS_ALL but permissions.ts may still reduce it to id at read time if the stamped schema is later cleared. Missing scope defaults to account inheritance; ensure types define scope explicitly."]
+// CIL[DOC-MACRO purpose="Create new entity record with type resolution"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate, resolve type, create record with inheritance and triggers"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="created_record" errors="entity_required,type_resolution_failed,parent_not_found" side_effects="database_insert,trigger_fire,permission_inheritance"]
+// CIL[DOC-MICRO logic_summary="Resolves type, handles account inheritance, applies defaults, fires triggers" 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: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/db.ts, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// 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 create = createHandler(async (ctx, body) => {
   const entity = body?.entity || ctx.query?.entity
-  const { entity: _e, type_slug: _ts, design_schema: _ds, validation_schema: _vs, account_id: _ai, ...recordData } = body || {}
+  const type_slug = body?.type_slug
+  const method = ctx.query?.method || 'POST'
+
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'create',
+      method,
+      typeSlug: type_slug
+    },
+    async () => {
+      const { entity: _e, type_slug: _ts, design_schema: _ds, validation_schema: _vs, account_id: requestedAccountId, id: _id, ...recordData } = body || {}
+
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        const e: any = new Error('Valid entity parameter is required'); e.statusCode = 400; throw e
+      }
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    const e: any = new Error('Valid entity parameter is required'); e.statusCode = 400; throw e
-  }
+      if (RAW_ENTITIES.includes(entity)) {
+        const allowed: Record<string, string[]> = {
+          logs: ['level', 'message', 'context', 'source', 'source_type', 'source_id', 'person_id', 'account_id', 'app_id', 'created_by', 'metadata', 'created_at'],
+          test_runs: ['suite', 'status', 'started_at', 'finished_at', 'duration_ms', 'total', 'passed', 'failed', 'skipped', 'triggered_by', 'account_id'],
+          observability: ['app_id', 'account_id', 'type_id', 'metric_name', 'metric_value', 'metric_unit', 'context', 'metadata', 'created_at'],
+          test_cases: ['app_id', 'account_id', 'type_id', 'slug', 'name', 'description', 'config', 'metadata', 'is_active', 'is_system', 'created_at', 'updated_at']
+        }
+        const fields = allowed[entity] || []
+        const raw: any = {}
+        for (const key of fields) {
+          if (recordData[key] !== undefined) raw[key] = recordData[key]
+        }
+        if (fields.includes('account_id') && raw.account_id === undefined) raw.account_id = ctx.accountId
+        if (entity === 'logs' && !raw.created_at) raw.created_at = new Date().toISOString()
+        if (entity === 'logs' && (!raw.level || !raw.message)) { const e: any = new Error('level and message are required for logs'); e.statusCode = 400; throw e }
+        if (entity === 'test_runs' && !raw.suite) { const e: any = new Error('suite is required for test_runs'); e.statusCode = 400; throw e }
+        if (entity === 'observability' && (!raw.metric_name || raw.metric_value === undefined)) { const e: any = new Error('metric_name and metric_value are required for observability'); e.statusCode = 400; throw e }
+        if (entity === 'test_cases' && (!raw.slug || !raw.name)) { const e: any = new Error('slug and name are required for test_cases'); e.statusCode = 400; throw e }
+
+        const { data, error: err } = await ctx.db.from(entity).insert(raw).select().single()
+        if (err) throw err
+        fireCreateTriggers(entity, data.id, raw, ctx).catch(console.error)
+        return await sanitizeRecordData(ctx, data, entity)
+      }
+
+      let typeRecord: { id: string; design_schema: Record<string, any>; validation_schema: Record<string, any> }
+
+      if (body?.type_slug) {
+        const kind = ENTITY_TO_KIND[entity]
+        if (!kind) {
+          const e: any = new Error(`type_slug is not supported for entity: ${entity}`); e.statusCode = 400; throw e
+        }
+        typeRecord = await resolveTypeRecord(kind, body.type_slug)
+      } else if (recordData.type_id) {
+        const { data, error: typeErr } = await adminDb
+          .from('types')
+          .select('id, design_schema, validation_schema, is_active')
+          .eq('id', recordData.type_id)
+          .single()
+        if (typeErr || !data) throw new Error(`type_id not found: ${recordData.type_id}`)
+        if (!data.is_active) throw new Error(`type_id references an inactive type: ${recordData.type_id}`)
+        typeRecord = { id: data.id, design_schema: data.design_schema || {}, validation_schema: data.validation_schema || {} }
+      } else {
+        const e: any = new Error('type_id or type_slug is required — every runtime record must reference a type'); e.statusCode = 400; throw e
+      }
 
-  // Resolve type record (id + design_schema + validation_schema) in one query.
-  // Accepts either type_slug (resolved by kind) or a direct type_id already in recordData.
-  let typeRecord: { id: string; design_schema: Record<string, any>; validation_schema: Record<string, any> }
+      recordData.type_id = typeRecord.id
 
-  if (body?.type_slug) {
-    const kind = ENTITY_TO_KIND[entity]
-    if (!kind) {
-      const e: any = new Error(`type_slug is not supported for entity: ${entity}`); e.statusCode = 400; throw e
-    }
-    typeRecord = await resolveTypeRecord(kind, body.type_slug)
-  } else if (recordData.type_id) {
-    const { data, error: typeErr } = await adminDb
-      .from('types')
-      .select('id, design_schema, validation_schema, is_active')
-      .eq('id', recordData.type_id)
-      .single()
-    if (typeErr || !data) throw new Error(`type_id not found: ${recordData.type_id}`)
-    if (!data.is_active) throw new Error(`type_id references an inactive type: ${recordData.type_id}`)
-    typeRecord = { id: data.id, design_schema: data.design_schema || {}, validation_schema: data.validation_schema || {} }
-  } else {
-    const e: any = new Error('type_id or type_slug is required — every runtime record must reference a type'); e.statusCode = 400; throw e
-  }
+      let designSchema = typeRecord.design_schema || {}
+      if (!designSchema.record_permissions) {
+        designSchema = { ...PERMISSIONS_ALL, ...designSchema }
+      }
 
-  recordData.type_id = typeRecord.id
+      let recordAccountId = requestedAccountId || ctx.accountId
+      const parentRef = recordData.thread_id || recordData.target_id || recordData.parent_id
+      if (parentRef) {
+        const parentTable = recordData.thread_id
+          ? 'threads'
+          : recordData.target_type === 'account'
+            ? 'accounts'
+            : recordData.target_type === 'person'
+              ? 'people'
+              : 'items'
+        const parentColumns = parentTable === 'accounts' ? 'id' : 'account_id, design_schema'
+        const { data: parentRecord } = await ctx.db
+          .from(parentTable)
+          .select(parentColumns)
+          .eq('id', parentRef)
+          .maybeSingle()
+        if (!parentRecord) {
+          const e: any = new Error('Parent record not found or not accessible'); e.statusCode = 403; throw e
+        }
+        if (parentTable === 'accounts') {
+          recordAccountId = parentRecord.id
+        } else {
+          recordAccountId = parentRecord.account_id
+          const parentScope = parentRecord.design_schema?.scope
+          if (parentScope) {
+            designSchema = { ...designSchema, scope: parentScope }
+          }
+        }
+      }
 
-  // Ensure the type has at least permissions=ALL (defensive — migration 062 guarantees this)
-  let designSchema = typeRecord.design_schema || {}
-  if (!designSchema.record_permissions) {
-    designSchema = { ...PERMISSIONS_ALL, ...designSchema }
-  }
+      const resolvedScope: string = designSchema.scope ?? 'account'
+      if (resolvedScope === 'platform') {
+        const { data: sysAccount } = await adminDb
+          .from('accounts')
+          .select('id')
+          .eq('slug', 'spine-system')
+          .single()
+        if (sysAccount?.id) recordAccountId = sysAccount.id
+      }
 
-  // Resolve account_id and propagate scope via parent inheritance.
-  // Runtime records are the source of truth: the parent record's stamped scope
-  // and account_id are inherited, not re-looked up from the type table.
-  let recordAccountId = ctx.accountId
-  const parentRef = recordData.thread_id || recordData.target_id || recordData.parent_id
-  if (parentRef) {
-    const parentTable = recordData.thread_id ? 'threads' : 'items'
-    const { data: parentRecord } = await ctx.db
-      .from(parentTable)
-      .select('account_id, design_schema')
-      .eq('id', parentRef)
-      .maybeSingle()
-    if (!parentRecord) {
-      const e: any = new Error('Parent record not found or not accessible'); e.statusCode = 403; throw e
-    }
-    recordAccountId = parentRecord.account_id
-    const parentScope = parentRecord.design_schema?.scope
-    if (parentScope) {
-      designSchema = { ...designSchema, scope: parentScope }
-    }
-  }
+      const dataToInsert: Record<string, any> = {
+        ...recordData,
+        design_schema:     designSchema,
+        validation_schema: typeRecord.validation_schema || {},
+        created_by: ctx.principal?.id,
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString()
+      }
 
-  // Platform-scoped records belong to the system account so they are visible
-  // across all accounts. Child records already inherited the parent's scope above.
-  const resolvedScope: string = designSchema.scope ?? 'account'
-  if (resolvedScope === 'platform') {
-    const { data: sysAccount } = await adminDb
-      .from('accounts')
-      .select('id')
-      .eq('slug', 'spine-system')
-      .single()
-    if (sysAccount?.id) recordAccountId = sysAccount.id
-  }
+      // accounts is the source-of-truth table; it does not have an account_id column
+      if (entity !== 'accounts') {
+        dataToInsert.account_id = recordAccountId
+      } else if (dataToInsert.parent_id === undefined) {
+        dataToInsert.parent_id = ctx.principal?.accountId || null
+      }
 
-  // Add audit fields + stamped schema
-  const dataToInsert = {
-    ...recordData,
-    design_schema:     designSchema,
-    validation_schema: typeRecord.validation_schema || {},
-    created_by: ctx.principal?.id,
-    account_id: recordAccountId,
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString()
-  }
+      const permissionAccountId = entity === 'accounts' ? ctx.principal?.accountId : recordAccountId
+      const typeSlugForPermissions = type_slug || ENTITY_TO_KIND[entity]
+      const perms = await resolveFirstSurfacePermissions(
+        ctx.principal?.id,
+        permissionAccountId,
+        typeSlugForPermissions,
+        'create',
+        designSchema
+      )
+      if (!perms.canCreate) {
+        const e: any = new Error('Insufficient permissions to create this record')
+        e.statusCode = 403
+        throw e
+      }
 
-  // RLS will check if user has INSERT permission on this account
-  const { data, error: err } = await ctx.db.from(entity)
-    .insert(dataToInsert)
-    .select()
-    .single()
+      const insertDb = entity === 'accounts' ? adminDb : ctx.db
 
-  if (err) throw err
+      const { data, error: err } = await insertDb.from(entity)
+        .insert(dataToInsert)
+        .select()
+        .single()
 
-  // Fire triggers asynchronously (don't block response)
-  const entityData = { ...dataToInsert, id: data.id }
-  fireCreateTriggers(entity, data.id, entityData, ctx).catch(console.error)
+      if (err) throw err
 
-  return await sanitizeRecordData(ctx, data, entity)
+      const entityData = { ...dataToInsert, id: data.id }
+      fireCreateTriggers(entity, data.id, entityData, ctx).catch(console.error)
+
+      return await sanitizeRecordData(ctx, data, entity)
+    }
+  )
 })
-// ─── CHUNK_END: ADMIN_DATA_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Entity Update Handler
- * @micro       Updates an existing record by ID with audit fields and triggers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body with partial record fields to update
- * @outputs     Sanitized updated record
- * @depends-on  [createHandler, sanitizeRecordData, fireUpdateTriggers]
- * @depended-by [Netlify function routing]
- * @side-effects [DB write, async trigger fire]
- * @tags        admin, crud, update
- */
+// CIL[END chunk_id="admin-data_create_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_update_1784019432" type="function" identity="update" parent="none"]
+// CIL[DOC-MACRO purpose="Update existing entity record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Patch allowed fields on entity record with triggers"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="updated_record" errors="entity_required,id_required" side_effects="database_update,trigger_fire"]
+// CIL[DOC-MICRO logic_summary="Filters protected fields, adds audit fields, updates record, fires triggers" 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/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"]
 export const update = createHandler(async (ctx, body) => {
   const { entity, id } = ctx.query || {}
-  // Strip server-only fields — client must never override these on update
-  const { design_schema: _ds, validation_schema: _vs, account_id: _ai, type_id: _ti, type_slug: _ts, ...recordData } = body || {}
+  const method = ctx.query?.method || 'PATCH'
+  const type_slug = body?.type_slug
+
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'update',
+      method,
+      typeSlug: type_slug
+    },
+    async () => {
+      const { design_schema: _ds, validation_schema: _vs, type_id: _ti, type_slug: _ts, id: _id, account_id: requestedAccountId, ...recordData } = body || {}
+
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        throw new Error('Valid entity parameter is required')
+      }
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    throw new Error('Valid entity parameter is required')
-  }
+      if (!id) {
+        throw new Error('ID is required for update')
+      }
 
-  if (!id) {
-    throw new Error('ID is required for update')
-  }
+      const { data: existing, error: existingErr } = await ctx.db
+        .from(entity)
+        .select('*')
+        .eq('id', id)
+        .single()
 
-  // Add audit fields
-  const dataToUpdate = {
-    ...recordData,
-    updated_by: ctx.principal?.id,
-    updated_at: new Date().toISOString()
-  }
+      if (existingErr || !existing) {
+        throw new Error('Record not found or access denied')
+      }
+
+      if (entity === 'people' && requestedAccountId !== undefined) {
+        recordData.account_id = requestedAccountId
+      }
+
+      const typeSlugForPermissions = type_slug || entity
+      const validation = await validateUpdatePermissions(
+        ctx,
+        recordData,
+        existing,
+        typeSlugForPermissions
+      )
+
+      if (!validation.valid) {
+        const e: any = new Error(validation.error || 'Insufficient permissions to update this record')
+        e.statusCode = 403
+        throw e
+      }
 
-  // RLS will check UPDATE permission on this record
-  const { data, error: err } = await ctx.db.from(entity)
-    .update(dataToUpdate)
-    .eq('id', id)
-    .select()
-    .single()
+      const sanitizedUpdate = validation.sanitizedData || recordData
+      const dataToUpdate = RAW_ENTITIES.includes(entity)
+        ? { ...sanitizedUpdate }
+        : { ...sanitizedUpdate, updated_by: ctx.principal?.id, updated_at: new Date().toISOString() }
 
-  if (err) throw err
+      const { data, error: err } = await ctx.db.from(entity)
+        .update(dataToUpdate)
+        .eq('id', id)
+        .select()
+        .single()
 
-  // Fire triggers asynchronously (don't block response)
-  const entityData = { ...data, ...dataToUpdate }
-  fireUpdateTriggers(entity, id, entityData, ctx).catch(console.error)
+      if (err) throw err
 
-  return await sanitizeRecordData(ctx, data, entity)
+      const entityData = { ...data, ...dataToUpdate }
+      fireUpdateTriggers(entity, id, entityData, ctx).catch(console.error)
+
+      return await sanitizeRecordData(ctx, data, entity)
+    }
+  )
 })
-// ─── CHUNK_END: ADMIN_DATA_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Entity Delete Handler
- * @micro       Deletes a record by ID with soft delete support and triggers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for DELETE)
- * @outputs     { deleted: boolean, soft: boolean, data?: sanitizedRecord }
- * @depends-on  [createHandler, sanitizeRecordData, entitySupportsSoftDelete, fireDeleteTriggers]
- * @depended-by [Netlify function routing]
- * @side-effects [DB write, async trigger fire]
- * @tags        admin, crud, delete, soft-delete
- */
+// CIL[END chunk_id="admin-data_update_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_remove_1784019432" type="function" identity="remove" parent="none"]
+// CIL[DOC-MACRO purpose="Delete entity record with soft delete support"]
+// CIL[DOC-RESPONSIBILITY responsibility="Perform hard or soft delete with triggers"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="delete_confirmation" errors="entity_required,id_required" side_effects="database_delete,trigger_fire"]
+// CIL[DOC-MICRO logic_summary="Checks soft delete support, performs appropriate delete method, fires triggers" 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 remove = createHandler(async (ctx, _body) => {
   const { entity, id, soft = 'true' } = ctx.query || {}
+  const method = ctx.query?.method || 'DELETE'
+
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'remove',
+      method
+    },
+    async () => {
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        throw new Error('Valid entity parameter is required')
+      }
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    throw new Error('Valid entity parameter is required')
-  }
+      if (!id) {
+        throw new Error('ID is required for delete')
+      }
 
-  if (!id) {
-    throw new Error('ID is required for delete')
-  }
+      const { data: existing, error: existingErr } = await ctx.db
+        .from(entity)
+        .select('*')
+        .eq('id', id)
+        .single()
+
+      if (existingErr || !existing) {
+        throw new Error('Record not found or access denied')
+      }
 
-  const isSoftDelete = soft === 'true'
+      const permissionAccountId = existing.account_id || ctx.principal?.accountId
+      const perms = await resolveFirstSurfacePermissions(
+        ctx.principal?.id,
+        permissionAccountId,
+        entity,
+        'delete',
+        existing.design_schema
+      )
+
+      if (!perms.canDelete) {
+        const e: any = new Error('Insufficient permissions to delete this record')
+        e.statusCode = 403
+        throw e
+      }
 
-  if (isSoftDelete && entitySupportsSoftDelete(entity)) {
-    // Soft delete - set is_active to false
-    // RLS will check DELETE permission on this record
-    const { data, error: err } = await ctx.db.from(entity)
-      .update({
-        is_active: false,
-        updated_by: ctx.principal?.id,
-        updated_at: new Date().toISOString()
-      })
-      .eq('id', id)
-      .select()
-      .single()
-
-    if (err) throw err
-    return { deleted: true, soft: true, data: await sanitizeRecordData(ctx, data, entity) }
-  } else {
-    // Hard delete
-    // RLS will check DELETE permission on this record
-    const { error: err } = await ctx.db.from(entity)
-      .delete()
-      .eq('id', id)
-
-    if (err) throw err
-    return { deleted: true, soft: false }
-  }
+      const isSoftDelete = soft === 'true'
+
+      if (isSoftDelete && entitySupportsSoftDelete(entity)) {
+        const { data, error: err } = await ctx.db.from(entity)
+          .update({
+            is_active: false,
+            updated_by: ctx.principal?.id,
+            updated_at: new Date().toISOString()
+          })
+          .eq('id', id)
+          .select()
+          .single()
+
+        if (err) throw err
+        return { deleted: true, soft: true, data: await sanitizeRecordData(ctx, data, entity) }
+      } else {
+        const { error: err } = await ctx.db.from(entity)
+          .delete()
+          .eq('id', id)
+
+        if (err) throw err
+        return { deleted: true, soft: false }
+      }
+    }
+  )
 })
-// ─── CHUNK_END: ADMIN_DATA_REMOVE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_HELPERS_SECTION ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_HELPERS_SECTION_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Helpers Section Header
- * @micro       Section marker for helper functions
- * @inputs      none
- * @outputs     none
- * @depends-on  [none]
- * @depended-by [none]
- * @side-effects [none]
- * @tags        admin, section, helpers
- */
-// ─── CHUNK_END: ADMIN_DATA_HELPERS_SECTION ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_GET_SEARCH_FIELD ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_GET_SEARCH_FIELD_1_0_0
- * @version     1.0.0
- * @hash        7c2615cf66a522b9b0df96cfbc8dfc50a2650016e967ceffd9172a770c78a26a
- * @macro       Search Field Resolver
- * @micro       Returns the primary display field for search functionality
- * @inputs      entity: string — Entity name from VALID_ENTITIES
- * @outputs     string — Column name to search in
- * @depends-on  [none]
- * @depended-by [list]
- * @side-effects [none]
- * @tags        admin, search, field-mapping
- */
+// CIL[END chunk_id="admin-data_remove_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_getsearchfield_1784019432" type="function" identity="getSearchField" parent="none"]
+// CIL[DOC-MACRO purpose="Return search field mapping for entity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide field name for search functionality"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="search_field:string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps entity types to their primary display fields for search" 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"]
 function getSearchField(entity: string): string {
   const searchFields: Record<string, string> = {
     accounts: 'display_name',
@@ -539,114 +697,110 @@ function getSearchField(entity: string): string {
     links: 'link_type',
     attachments: 'filename',
     watchers: 'watch_type',
-    item_progress: 'title'
+    item_progress: 'title',
+    logs: 'message',
+    test_runs: 'suite',
+    observability: 'metric_name',
+    test_cases: 'name'
   }
   return searchFields[entity] || 'id'
 }
-// ─── CHUNK_END: ADMIN_DATA_GET_SEARCH_FIELD ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_ENTITY_SUPPORTS_SOFT_DELETE ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_ENTITY_SUPPORTS_SOFT_DELETE_1_0_0
- * @version     1.0.0
- * @hash        0438e650a11bfb4c25b90939780127d8912bdc5caeb772fe3049381d6497412d
- * @macro       Soft Delete Support Checker
- * @micro       Returns true if entity supports soft delete via is_active column
- * @inputs      entity: string — Entity name from VALID_ENTITIES
- * @outputs     boolean — True if entity has is_active column
- * @depends-on  [none]
- * @depended-by [remove]
- * @side-effects [none]
- * @tags        admin, soft-delete, entity-check
- */
+// CIL[END chunk_id="admin-data_getsearchfield_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_entitysupportssoftdelete_1784019432" type="function" identity="entitySupportsSoftDelete" parent="none"]
+// CIL[DOC-MACRO purpose="Check if entity supports soft delete"]
+// CIL[DOC-RESPONSIBILITY responsibility="Determine soft delete capability for entity type"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean:supports_soft_delete" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns true if entity has is_active column for soft delete" 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"]
 function entitySupportsSoftDelete(entity: string): boolean {
-  const softDeleteEntities = ['accounts', 'people', 'items', 'threads', 'messages', 'watchers', 'item_progress']
+  const softDeleteEntities = ['accounts', 'people', 'items', 'threads', 'messages', 'watchers', 'item_progress', 'test_cases']
   return softDeleteEntities.includes(entity)
 }
-// ─── CHUNK_END: ADMIN_DATA_ENTITY_SUPPORTS_SOFT_DELETE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_STATS ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_STATS_1_0_0
- * @version     1.0.0
- * @hash        0bed523a260ab3959cb4e7150cca044f4e97ce91d7ae3386ab14b5f4182d74d7
- * @macro       Entity Stats Handler
- * @micro       Returns total record count for an entity scoped by account
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     {entity: string, count: number} — Entity name and record count
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB count query with RLS filtering]
- * @tags        admin, stats, count, entity
- */
+// CIL[END chunk_id="admin-data_entitysupportssoftdelete_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_stats_1784019432" type="function" identity="stats" parent="none"]
+// CIL[DOC-MACRO purpose="Get record count for entity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return total record count with RLS filtering"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{entity,count}" errors="entity_required,database_error" side_effects="database_count_query"]
+// CIL[DOC-MICRO logic_summary="Performs count query with RLS filtering applied" 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 stats = createHandler(async (ctx, _body) => {
   const { entity } = ctx.query || {}
+  const method = ctx.query?.method || 'GET'
 
-  if (!entity || !VALID_ENTITIES.includes(entity)) {
-    throw new Error('Valid entity parameter is required')
-  }
+  return await withAdminLogging(
+    ctx,
+    {
+      entity: entity || 'unknown',
+      action: 'stats',
+      method
+    },
+    async () => {
+      if (!entity || !VALID_ENTITIES.includes(entity)) {
+        throw new Error('Valid entity parameter is required')
+      }
 
-  // RLS will filter count based on account hierarchy access
-  const { count, error: err } = await ctx.db.from(entity)
-    .select('*', { count: 'exact', head: true })
+      const { count, error: err } = await ctx.db.from(entity)
+        .select('*', { count: 'exact', head: true })
 
-  if (err) throw err
+      if (err) throw err
 
-  return { entity, count }
+      return { entity, count }
+    }
+  )
 })
-// ─── CHUNK_END: ADMIN_DATA_STATS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_MAIN_HANDLER_SECTION ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_MAIN_HANDLER_SECTION_1_0_0
- * @version     1.0.0
- * @hash        TBD
- * @macro       Main Handler Section Header
- * @micro       Section marker for the main router handler
- * @inputs      none
- * @outputs     none
- * @depends-on  [none]
- * @depended-by [none]
- * @side-effects [none]
- * @tags        admin, section, main-handler
- */
-// ─── CHUNK_END: ADMIN_DATA_MAIN_HANDLER_SECTION ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ADMIN_DATA_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    ADMIN_DATA_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        edceffa0d5c8b3c05b1a89188a274a586b6ebe8793ede427e2326876d7090df9
- * @macro       Admin Data Router
- * @micro       Routes HTTP methods and actions to appropriate CRUD handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH operations
- * @outputs     Varies — Depends on routed handler (list/get/create/update/remove/stats)
- * @depends-on  [createHandler, list, get, create, update, remove, stats]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        admin, router, crud, netlify-function
- */
+// CIL[END chunk_id="admin-data_stats_1784019432"]
+// CIL[BEGIN chunk_id="admin-data_handler_1784019432" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route HTTP methods to appropriate CRUD handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests based on method and action parameters"]
+// CIL[DOC-CONTEXT module="admin-data" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="handler_response" errors="invalid_action_or_method" side_effects="delegates_to_crud_handlers"]
+// CIL[DOC-MICRO logic_summary="Routes GET/POST/PATCH/DELETE to list/get/create/update/remove/stats" 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 = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
 
   switch (action) {
     case 'list':
-      if (method === 'GET') {
-        return await list(ctx, body)
-      }
+      if (method === 'GET') return await list(ctx, body)
       break
     case 'get':
-      if (method === 'GET') {
-        return await get(ctx, body)
-      }
+      if (method === 'GET') return await get(ctx, body)
       break
     case 'stats':
-      if (method === 'GET') {
-        return await stats(ctx, body)
-      }
+      if (method === 'GET') return await stats(ctx, body)
+      break
+    case 'create':
+      if (method === 'POST') return await create(ctx, body)
+      break
+    case 'update':
+      if (method === 'PATCH') return await update(ctx, body)
+      break
+    case 'remove':
+      if (method === 'DELETE') return await remove(ctx, body)
       break
     default:
       if (method === 'GET' && ctx.query?.id) {
@@ -664,4 +818,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: ADMIN_DATA_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="admin-data_handler_1784019432"]