spine-framework 0.3.124 → 0.3.126

package/.framework/functions/embeddings.ts

@@ -1,56 +1,328 @@
-/**
- * @module embeddings
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD, lifecycle, and search API for the `embeddings` table. Embeddings store
- * vector representations of text chunks for RAG workloads.
- *
- * **Routed by:** `GET/POST/PATCH /.netlify/functions/embeddings`
- *
- * **Actions:**
- * | method | ?action         | handler           |
- * |--------|-----------------|-------------------|
- * | POST   | generate        | generate          |
- * | POST   | revoke          | revoke            |
- * | POST   | approve         | approve           |
- * | GET    | stats           | getStats          |
- * | POST   | batch-create    | batchCreate       |
- * | POST   | delete-document | deleteByDocument  |
- * | POST   | cleanup         | cleanup           |
- * | POST   | search-similar  | searchSimilar     |
- * | POST   | search-semantic | searchSemantic    |
- * | GET    | ?id             | get               |
- * | GET    | (default)       | list              |
- * | POST   | —               | create            |
- * | PATCH  | —               | update            |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped). Account context
- * required for writes.
- *
- * INVARIANT: `generate` is the single entry point for AI-powered embedding
- *   creation. Custom code must call `generate` — never write to the embeddings
- *   table directly.
- * INVARIANT: `update` only patches `content` and `metadata`.
- * INVARIANT: `searchSimilar` requires a pre-computed `query_embedding` vector.
- *
- * @seeAlso agent-runner.ts (retrieveKnowledge calls match_embeddings RPC)
- * @seeAlso pipeline-runner.ts (generate_embeddings stage type)
- * @seeAlso audit.ts (emitLog for embedding.* events)
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+
+
+
+
+// CIL[DOC-MACRO purpose="Create single embedding record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create embedding with validation and audit logging"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="embedding_data" outputs="created_embedding" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Validate input, create embedding record, log creation event" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
+export const create = createHandler(async (ctx, body) => {
+  const { model_id, document_id, chunk_index, content, metadata } = body
+
+  if (!model_id || !document_id || !content) {
+    throw new Error('model_id, document_id, and content are required')
+  }
+
+  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
+    throw new Error('User context (person and account) required')
+  }
+
+  const { data, error: err } = await ctx.db
+    .from('embeddings')
+    .insert({
+      model_id,
+      document_id,
+      chunk_index: chunk_index || 0,
+      content,
+      metadata: metadata || {},
+      account_id: ctx.accountId
+    })
+    .select()
+    .single()
+
+  if (err) throw err
+
+  await emitLog(ctx, 'embedding.created', 
+    { type: 'embedding', id: data.id }, 
+    { after: { document_id, model_id } }
+  )
+
+  return data
+})
+
+
+
+
+// CIL[DOC-MACRO purpose="Update embedding record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Modify embedding content or metadata"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="embedding_id,updates" outputs="updated_embedding" errors="not_found,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Update specified fields, log modification event" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
+export const update = createHandler(async (ctx, body) => {
+  const id = body?.id || ctx.query?.id
+  const { id: _bodyId, content, metadata } = body || {}
+
+  if (!id) {
+    throw new Error('Embedding ID is required')
+  }
+
+  const updateFields: Record<string, any> = {}
+  if (content !== undefined) updateFields.content = content
+  if (metadata !== undefined) updateFields.metadata = metadata
+
+  const { data, error: err } = await ctx.db
+    .from('embeddings')
+    .update(updateFields)
+    .eq('id', id)
+    .select()
+    .single()
+
+  if (err) throw err
+
+  await emitLog(ctx, 'embedding.updated', 
+    { type: 'embedding', id }, 
+    { after: { content_updated: !!content } }
+  )
+
+  return data
+})
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[DOC-MACRO purpose="Generate embeddings for knowledge item"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create vectors for item content using multiple strategies"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="item_id,options" outputs="generation_result" errors="validation_errors,api_errors" side_effects="db_write,api_calls,audit_log"]
+// CIL[DOC-MICRO logic_summary="Extract content, call embedding API, store vectors with metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.80" flags="complex_logic,external_api"]
+export const generate = createHandler(async (ctx, body) => {
+  const { item_id, force_regenerate = false, account_id_override } = body || {}
+  if (!item_id) throw new Error('item_id is required')
+
+  
+  const { data: item, error: itemErr } = await adminDb
+    .from('items')
+    .select('*, type:types(design_schema)')
+    .eq('id', item_id)
+    .single()
+
+  if (itemErr || !item) throw new Error(`Item ${item_id} not found`)
+
+  const typeDesign = item.type?.design_schema || {}
+  const kbType = item.data?.kb_type || 'article'
+
+  
+  let vectorTypes: string[] = []
+  const rawVT = typeDesign.vector_types
+  if (Array.isArray(rawVT)) {
+    vectorTypes = rawVT
+  } else if (rawVT && typeof rawVT === 'object') {
+    vectorTypes = rawVT[kbType] || rawVT['default'] || ['semantic', 'structure']
+  } else {
+    vectorTypes = ['semantic', 'structure']
+  }
+
+  const embeddingFields: string[] = typeDesign.embedding_fields?.structure || []
+  const resolvedAccountId = account_id_override || item.account_id || await getPlatformAccountId()
+  const isPublished = item.status === 'published'
+
+  
+  const { data: existing } = await adminDb
+    .from('embeddings')
+    .select('id, content_hash, chunk_index, metadata')
+    .eq('document_id', item_id)
+
+  const existingMap = new Map<string, any>()
+  for (const row of existing || []) {
+    const vt = row.metadata?.vector_type || ''
+    const ci = row.chunk_index ?? 0
+    existingMap.set(`${vt}:${ci}`, row)
+  }
+
+  
+  if (force_regenerate) {
+    await adminDb.from('embeddings').delete().eq('document_id', item_id)
+    existingMap.clear()
+  }
+
+  const created: string[] = []
+  const skipped: string[] = []
+  const errors: string[] = []
+
+  
+  const syncVectors = vectorTypes.filter(vt => vt !== 'summary')
+  const contents: Array<{ vt: string; text: string; chunkIndex: number }> = []
+
+  for (const vt of syncVectors) {
+    const builder = CONTENT_BUILDERS[vt]
+    if (!builder) { errors.push(`Unknown vector type: ${vt}`); continue }
+    const text = builder(item, { embedding_fields: embeddingFields })
+    if (!text) { skipped.push(`${vt}:empty`); continue }
+    contents.push({ vt, text, chunkIndex: 0 })
+  }
+
+  
+  if (vectorTypes.includes('summary')) {
+    const summaryText = await generateAiSummary(item, ctx)
+    if (summaryText) contents.push({ vt: 'summary', text: summaryText, chunkIndex: 0 })
+  }
+
+  
+  const toEmbed = contents.filter(({ vt, text, chunkIndex }) => {
+    const hash = contentHash(text)
+    const key = `${vt}:${chunkIndex}`
+    const row = existingMap.get(key)
+    if (row && row.content_hash === hash) { skipped.push(key); return false }
+    return true
+  })
+
+  if (!toEmbed.length) {
+    return { item_id, embeddings_created: 0, embeddings_skipped: skipped.length, errors }
+  }
+
+  
+  let vectors: string[] = []
+  try {
+    vectors = await callEmbeddingApi(toEmbed.map(c => c.text), ctx)
+  } catch (e: any) {
+    throw new Error(`Embedding API call failed: ${e.message}`)
+  }
+
+  const now = new Date().toISOString()
+
+  
+  for (let i = 0; i < toEmbed.length; i++) {
+    const { vt, text, chunkIndex } = toEmbed[i]
+    const hash = contentHash(text)
+    const key = `${vt}:${chunkIndex}`
+    const existingRow = existingMap.get(key)
+
+    const row = {
+      account_id:   resolvedAccountId,
+      model_id:     'text-embedding-3-small',
+      document_id:  item_id,
+      chunk_index:  chunkIndex,
+      content:      text,
+      embedding:    vectors[i],
+      content_hash: hash,
+      approved_at:  isPublished ? now : null,
+      revoked_at:   null,
+      metadata: {
+        vector_type:    vt,
+        item_type:      item.type?.design_schema ? (item.data?.kb_type ? 'kb_article' : 'item') : 'item',
+        kb_type:        kbType,
+        security_level: item.data?.security_level || 'internal',
+        source_item_id: item_id,
+      },
+    }
+
+    if (existingRow) {
+      await adminDb.from('embeddings').update(row).eq('id', existingRow.id)
+    } else {
+      await adminDb.from('embeddings').insert(row)
+    }
+    created.push(key)
+  }
+
+  await emitLog(ctx, 'embeddings.generated',
+    { type: 'item', id: item_id },
+    { after: { vectors_created: created.length, vectors_skipped: skipped.length, is_published: isPublished } }
+  )
+
+  return {
+    item_id,
+    embeddings_created: created.length,
+    embeddings_skipped: skipped.length,
+    errors,
+  }
+})
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="embeddings_moduleheader_1783969696" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for embeddings module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import crypto, middleware, database, audit, and permissions"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import required dependencies for embedding generation and management" 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: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.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"]
 
 import { createHash } from 'crypto'
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
+import { isSystemAdmin } from './_shared/principal'
 import { sanitizeRecordData } from './_shared/permissions'
-
-// ─── UNIVERSAL CONTENT BUILDERS ──────────────────────────────────────────────
-// Each builder accepts an item record and returns a plain-text string to embed.
-// Custom apps populate item.data with the named fields below; the builder picks
-// the first non-empty value from a priority chain.
-
+import { callOpenAIEmbeddings, callOpenAIChat } from './_shared/llm'
+// CIL[END chunk_id="embeddings_moduleheader_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_contentbuilders_1783969696" type="function" identity="contentBuilders" parent="none"]
+// CIL[DOC-MACRO purpose="Content extraction utilities for embeddings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Transform item data into embeddable text content"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="text_content" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Extract and format various content types from knowledge base items" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_logic"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.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 stripHtml(html: string): string {
   return html
     .replace(/<[^>]+>/g, ' ')
@@ -142,56 +414,39 @@ function buildErrorSignalContent(item: any): string {
   if (Array.isArray(sigs) && sigs.length) return sigs.join('\n')
   const tags = item.data?.ca_analysis_tags
   if (Array.isArray(tags) && tags.length) return tags.join('\n')
-  // Extract code-like patterns from description
+  
   const desc = item.description || ''
   const codeBlocks = desc.match(/```[\s\S]*?```/g) || []
   return codeBlocks.map((b: string) => b.replace(/```\w*\n?/g, '')).join('\n').trim()
 }
 
 function buildSummaryContentSync(item: any): string {
-  // Sync fallback — AI-generated summary handled asynchronously in generateSummary()
+  
   const desc = stripHtml(item.description || '')
   return `${item.title || ''}: ${desc.slice(0, 300)}`
 }
 
-async function generateAiSummary(item: any): Promise<string> {
-  const apiKey = process.env.OPENAI_API_KEY || process.env.LLM_API_KEY
-  const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1'
-  if (!apiKey) return buildSummaryContentSync(item)
+async function generateAiSummary(item: any, ctx?: any): Promise<string> {
   const plain = stripHtml(item.description || '').slice(0, 3000)
   try {
-    const res = await fetch(`${baseUrl}/chat/completions`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
-      body: JSON.stringify({
-        model: process.env.LLM_DEFAULT_MODEL || 'gpt-4o-mini',
-        temperature: 0.2,
-        max_tokens: 120,
-        messages: [
-          { role: 'system', content: 'Write one concise paragraph (max 100 words) summarising this knowledge base article for search indexing. Output only the paragraph.' },
-          { role: 'user', content: `Title: ${item.title}\n\n${plain}` },
-        ],
-      }),
-    })
-    if (!res.ok) return buildSummaryContentSync(item)
-    const j: any = await res.json()
+    const j = await callOpenAIChat(
+      ctx,
+      [
+        { role: 'system', content: 'Write one concise paragraph (max 100 words) summarising this knowledge base article for search indexing. Output only the paragraph.' },
+        { role: 'user', content: `Title: ${item.title}\n\n${plain}` },
+      ],
+      process.env.LLM_DEFAULT_MODEL || 'gpt-4o-mini',
+      { temperature: 0.2, max_tokens: 120 }
+    )
     return j.choices?.[0]?.message?.content?.trim() || buildSummaryContentSync(item)
   } catch {
     return buildSummaryContentSync(item)
   }
 }
 
-async function callEmbeddingApi(inputs: string[]): Promise<string[]> {
-  const apiKey = process.env.OPENAI_API_KEY || process.env.LLM_API_KEY
-  const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1'
-  if (!apiKey || !inputs.length) return inputs.map(() => '')
-  const res = await fetch(`${baseUrl}/embeddings`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
-    body: JSON.stringify({ model: 'text-embedding-3-small', input: inputs }),
-  })
-  if (!res.ok) throw new Error(`Embedding API error ${res.status}`)
-  const j: any = await res.json()
+async function callEmbeddingApi(inputs: string[], ctx?: any): Promise<string[]> {
+  if (!inputs.length) return inputs.map(() => '')
+  const j = await callOpenAIEmbeddings(ctx, inputs, 'text-embedding-3-small')
   const sorted = (j.data || []).sort((a: any, b: any) => a.index - b.index)
   return sorted.map((d: any) => `[${d.embedding.join(',')}]`)
 }
@@ -200,7 +455,7 @@ function contentHash(text: string): string {
   return createHash('sha256').update(text).digest('hex').slice(0, 16)
 }
 
-// Resolve platform account ID (spine-system) — memoised per process
+
 let _platformAccountId: string | null = null
 async function getPlatformAccountId(): Promise<string | null> {
   if (_platformAccountId) return _platformAccountId
@@ -209,10 +464,24 @@ async function getPlatformAccountId(): Promise<string | null> {
   return _platformAccountId
 }
 
-// ─── VECTOR TYPE → CONTENT BUILDER MAP ───────────────────────────────────────
-// Maps a vector_type string to a function that produces embeddable text from
-// an item record. `summary` is handled separately due to async LLM call.
 
+
+
+// CIL[END chunk_id="embeddings_contentbuilders_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_contentbuildersmap_1783969696" type="function" identity="contentBuildersMap" parent="none"]
+// CIL[DOC-MACRO purpose="Content builder registry mapping"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map content types to their extraction functions"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="builder_function" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Define mapping between vector types and content extraction functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: 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"]
 type ContentBuilder = (item: any, meta?: any) => string
 
 const CONTENT_BUILDERS: Record<string, ContentBuilder> = {
@@ -224,28 +493,23 @@ const CONTENT_BUILDERS: Record<string, ContentBuilder> = {
   outcome:      buildOutcomeContent,
   context:      buildContextContent,
   error_signal: buildErrorSignalContent,
-  // summary handled separately
+  
 }
-
-// ─── GENERATE HANDLER ────────────────────────────────────────────────────────
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_LIST_1_0_0
- * @version     1.0.0
- * @hash        929d4ac3030c10ac7a31bef9cad565900a5cd11af2e130ce3e4cfc28bc65d5ab
- * @macro       Embeddings List Handler
- * @micro       Lists embeddings with filtering, pagination, and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized embedding records
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        embeddings, list, crud, pagination
- */
+// CIL[END chunk_id="embeddings_contentbuildersmap_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_list_1783969696" type="function" identity="list" parent="none"]
+// CIL[DOC-MACRO purpose="List embeddings with filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and filter embeddings by model and document"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_embeddings" errors="auth_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query embeddings with filters, sanitize data, return paginated results" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 3. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 3."]
+// 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) => {
   const { model_id, document_id, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -253,8 +517,9 @@ export const list = createHandler(async (ctx, _body) => {
     throw new Error('Account context required')
   }
 
-  // RLS automatically filters to accessible accounts
-  let query = ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  let query = db
     .from('embeddings')
     .select('*')
     .order('created_at', { ascending: false })
@@ -283,23 +548,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// ─── CHUNK_END: EMBEDDINGS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_GET_1_0_0
- * @version     1.0.0
- * @hash        261bfd4dd3107ebfbc0a2ee3d870ac449f543699358a03d8bea27f86ba57b5bc
- * @macro       Embedding Get Handler
- * @micro       Returns single embedding record with sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized embedding record
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        embeddings, get, crud, single-record
- */
+// CIL[END chunk_id="embeddings_list_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_get_1783969696" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Get single embedding by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve individual embedding record"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_embedding" errors="not_found,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query embedding by ID and sanitize data for response" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -307,7 +570,9 @@ export const get = createHandler(async (ctx, _body) => {
     throw new Error('Embedding ID is required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  const { data, error: err } = await db
     .from('embeddings')
     .select('*')
     .eq('id', id)
@@ -317,118 +582,21 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'embedding')
 })
-// ─── CHUNK_END: EMBEDDINGS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        26bc1b478138d27fc02ebeede1b0ede362ef43864591bc7353390d5f60ae81db
- * @macro       Embedding Create Handler
- * @micro       Creates embedding record with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Embedding data including model_id, document_id, content
- * @outputs     Inserted embedding record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, audit logging]
- * @tags        embeddings, create, crud, audit
- */
-export const create = createHandler(async (ctx, body) => {
-  const { model_id, document_id, chunk_index, content, metadata } = body
-
-  if (!model_id || !document_id || !content) {
-    throw new Error('model_id, document_id, and content are required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('embeddings')
-    .insert({
-      model_id,
-      document_id,
-      chunk_index: chunk_index || 0,
-      content,
-      metadata: metadata || {},
-      account_id: ctx.accountId
-    })
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'embedding.created', 
-    { type: 'embedding', id: data.id }, 
-    { after: { document_id, model_id } }
-  )
-
-  return data
-})
-// ─── CHUNK_END: EMBEDDINGS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        e543c87308991159cda8e50f85127884475004bffaedb4508117481375bfaa43
- * @macro       Embedding Update Handler
- * @micro       Updates embedding content and/or metadata with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Embedding updates including id
- * @outputs     Updated embedding record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, audit logging]
- * @tags        embeddings, update, crud, audit
- */
-export const update = createHandler(async (ctx, body) => {
-  const id = body?.id || ctx.query?.id
-  const { id: _bodyId, content, metadata } = body || {}
-
-  if (!id) {
-    throw new Error('Embedding ID is required')
-  }
-
-  const updateFields: Record<string, any> = {}
-  if (content !== undefined) updateFields.content = content
-  if (metadata !== undefined) updateFields.metadata = metadata
-
-  const { data, error: err } = await ctx.db
-    .from('embeddings')
-    .update(updateFields)
-    .eq('id', id)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'embedding.updated', 
-    { type: 'embedding', id }, 
-    { after: { content_updated: !!content } }
-  )
-
-  return data
-})
-// ─── CHUNK_END: EMBEDDINGS_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_GET_STATS ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_GET_STATS_1_0_0
- * @version     1.0.0
- * @hash        176a002d14e89cffb0cb993b554c28e2258f66951901be49a4eccbe7855a2d7a
- * @macro       Embeddings Statistics Handler
- * @micro       Returns total embedding count for account with RLS scoping
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     {total_embeddings: number} — Total count of embeddings
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB count query]
- * @tags        embeddings, stats, count, monitoring
- */
+// CIL[END chunk_id="embeddings_get_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_getstats_1783969696" type="function" identity="getStats" parent="none"]
+// CIL[DOC-MACRO purpose="Get embedding statistics"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return total count of embeddings"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="embedding_stats" errors="auth_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Count total embeddings in database for account" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 getStats = createHandler(async (ctx, _body) => {
   if (!ctx.accountId) {
     throw new Error('Account context required')
@@ -442,23 +610,21 @@ export const getStats = createHandler(async (ctx, _body) => {
 
   return { total_embeddings: count || 0 }
 })
-// ─── CHUNK_END: EMBEDDINGS_GET_STATS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_BATCH_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_BATCH_CREATE_1_0_0
- * @version     1.0.0
- * @hash        18f603dbb73e044737283100d6e4cc092597a61645905473d6c6ec1ee67a9d7f
- * @macro       Embeddings Batch Create Handler
- * @micro       Bulk inserts multiple embeddings with account stamping and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — embeddings_data array of embedding objects
- * @outputs     Array of inserted embedding records
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [Bulk DB insert, audit logging]
- * @tags        embeddings, batch-create, bulk, audit
- */
+// CIL[END chunk_id="embeddings_getstats_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_batchcreate_1783969696" type="function" identity="batchCreate" parent="none"]
+// CIL[DOC-MACRO purpose="Create multiple embeddings at once"]
+// CIL[DOC-RESPONSIBILITY responsibility="Batch insert embedding records efficiently"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="created_embeddings" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Bulk insert embeddings with account context, log batch creation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 batchCreate = createHandler(async (ctx, body) => {
   const { embeddings_data } = body
 
@@ -489,23 +655,21 @@ export const batchCreate = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: EMBEDDINGS_BATCH_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_DELETE_BY_DOCUMENT ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_DELETE_BY_DOCUMENT_1_0_0
- * @version     1.0.0
- * @hash        1f74f199f69f563dbc9e72c0f3906412d6315721212261c5a61da4250cb34909
- * @macro       Embeddings Document Delete Handler
- * @micro       Deletes all embeddings for a document with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — document_id to delete embeddings for
- * @outputs     {deleted_count: number} — Number of deleted embeddings
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB delete, audit logging]
- * @tags        embeddings, delete, document, audit
- */
+// CIL[END chunk_id="embeddings_batchcreate_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_deletebydocument_1783969696" type="function" identity="deleteByDocument" parent="none"]
+// CIL[DOC-MACRO purpose="Delete all embeddings for a document"]
+// CIL[DOC-RESPONSIBILITY responsibility="Remove embeddings when document is deleted"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="deletion_count" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Delete embeddings by document ID, log deletion event" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 deleteByDocument = createHandler(async (ctx, body) => {
   const { document_id } = body
 
@@ -528,23 +692,21 @@ export const deleteByDocument = createHandler(async (ctx, body) => {
 
   return { deleted_count: data?.length || 0 }
 })
-// ─── CHUNK_END: EMBEDDINGS_DELETE_BY_DOCUMENT ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_CLEANUP ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_CLEANUP_1_0_0
- * @version     1.0.0
- * @hash        b5caa85d93d7eb232eaf7f81c63f7adc4269898397c4cc1d9186ce868a056223
- * @macro       Embeddings Cleanup Handler
- * @micro       Deletes old embeddings beyond retention period with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — days_to_keep (default 365)
- * @outputs     {deleted_count: number} — Number of deleted embeddings
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB delete by date, audit logging]
- * @tags        embeddings, cleanup, retention, audit
- */
+// CIL[END chunk_id="embeddings_deletebydocument_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_cleanup_1783969696" type="function" identity="cleanup" parent="none"]
+// CIL[DOC-MACRO purpose="Clean up old embeddings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Remove embeddings older than specified days"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="deletion_count" errors="db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Delete embeddings older than cutoff date, log cleanup" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 cleanup = createHandler(async (ctx, body) => {
   const { days_to_keep } = body
   const daysToKeep = days_to_keep || 365
@@ -567,23 +729,21 @@ export const cleanup = createHandler(async (ctx, body) => {
 
   return { deleted_count: data?.length || 0 }
 })
-// ─── CHUNK_END: EMBEDDINGS_CLEANUP ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_SEARCH_SIMILAR ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_SEARCH_SIMILAR_1_0_0
- * @version     1.0.0
- * @hash        e34df64fa1db62cdef551da14b15e6f7183915562ca68763b5ebe28fe889fff7
- * @macro       Embeddings Vector Search Handler
- * @micro       Performs vector similarity search using cosine similarity via RPC
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — query_embedding vector and search parameters
- * @outputs     {results, count, model_id, threshold} — Search results with metadata
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing, agent-runner.ts]
- * @side-effects [RPC call for vector similarity search]
- * @tags        embeddings, search, vector, similarity, rpc
- */
+// CIL[END chunk_id="embeddings_cleanup_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_searchsimilar_1783969696" type="function" identity="searchSimilar" parent="none"]
+// CIL[DOC-MACRO purpose="Search similar embeddings by vector"]
+// CIL[DOC-RESPONSIBILITY responsibility="Find embeddings similar to query vector"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="similar_results" errors="validation_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Call stored procedure for vector similarity search with threshold" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 searchSimilar = createHandler(async (ctx, body) => {
   const { query_embedding, model_id, limit = 10, threshold = 0.7 } = body || {}
 
@@ -595,7 +755,7 @@ export const searchSimilar = createHandler(async (ctx, body) => {
     throw new Error('query_embedding is required for similarity search')
   }
 
-  // Call the RPC function for vector similarity search
+  
   const { data, error: err } = await ctx.db.rpc('search_similar_embeddings', {
     p_account_id: ctx.accountId,
     p_model_id: model_id || 'text-embedding-ada-002',
@@ -613,23 +773,21 @@ export const searchSimilar = createHandler(async (ctx, body) => {
     threshold: parseFloat(threshold.toString())
   }
 })
-// ─── CHUNK_END: EMBEDDINGS_SEARCH_SIMILAR ────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_SEARCH_SEMANTIC ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_SEARCH_SEMANTIC_1_0_0
- * @version     1.0.0
- * @hash        26c9cb4da3ddfa47c34afd1c60c2568f760a97d07719a58e9ae2e3d3926e84ce
- * @macro       Embeddings Text Search Handler
- * @micro       Performs full-text search on embedding content using Postgres websearch
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — query string and optional filters
- * @outputs     {results, count, method, query} — Search results with metadata
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB full-text search query]
- * @tags        embeddings, search, text-search, fallback
- */
+// CIL[END chunk_id="embeddings_searchsimilar_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_searchsemantic_1783969696" type="function" identity="searchSemantic" parent="none"]
+// CIL[DOC-MACRO purpose="Search embeddings by text query"]
+// CIL[DOC-RESPONSIBILITY responsibility="Find embeddings matching text search query"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="search_results" errors="validation_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use database full-text search on embedding content" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 searchSemantic = createHandler(async (ctx, body) => {
   const { query, model_id, document_ids, limit = 10 } = body || {}
 
@@ -670,172 +828,21 @@ export const searchSemantic = createHandler(async (ctx, body) => {
     query
   }
 })
-// ─── CHUNK_END: EMBEDDINGS_SEARCH_SEMANTIC ────────────────────────────────────────────────
-
-// ─── GENERATE ────────────────────────────────────────────────────────────────
-/**
- * Generates embeddings for an item using the universal vector vocabulary.
- * Reads design_schema.vector_types from the item's type record to determine
- * which vectors to produce. Skips chunks whose content_hash is unchanged.
- * Sets approved_at = now() for published items, NULL for drafts.
- *
- * Body: item_id (required), force_regenerate (bool), account_id_override (uuid)
- *
- * This is the ONLY sanctioned way for custom code to write to the embeddings
- * table. Direct writes from custom functions are a hard-rule violation.
- */
-export const generate = createHandler(async (ctx, body) => {
-  const { item_id, force_regenerate = false, account_id_override } = body || {}
-  if (!item_id) throw new Error('item_id is required')
-
-  // Load item + type
-  const { data: item, error: itemErr } = await adminDb
-    .from('items')
-    .select('*, type:types(design_schema)')
-    .eq('id', item_id)
-    .single()
-
-  if (itemErr || !item) throw new Error(`Item ${item_id} not found`)
-
-  const typeDesign = item.type?.design_schema || {}
-  const kbType = item.data?.kb_type || 'article'
-
-  // Resolve which vector types to generate
-  // design_schema.vector_types can be a plain array (all kb_types share the same list)
-  // or a keyed object { postmortem: [...], how_to: [...] } to vary by kb_type sub-type
-  let vectorTypes: string[] = []
-  const rawVT = typeDesign.vector_types
-  if (Array.isArray(rawVT)) {
-    vectorTypes = rawVT
-  } else if (rawVT && typeof rawVT === 'object') {
-    vectorTypes = rawVT[kbType] || rawVT['default'] || ['semantic', 'structure']
-  } else {
-    vectorTypes = ['semantic', 'structure']
-  }
-
-  const embeddingFields: string[] = typeDesign.embedding_fields?.structure || []
-  const resolvedAccountId = account_id_override || item.account_id || await getPlatformAccountId()
-  const isPublished = item.status === 'published'
-
-  // Load existing embeddings for hash comparison
-  const { data: existing } = await adminDb
-    .from('embeddings')
-    .select('id, content_hash, chunk_index, metadata')
-    .eq('document_id', item_id)
-
-  const existingMap = new Map<string, any>()
-  for (const row of existing || []) {
-    const vt = row.metadata?.vector_type || ''
-    const ci = row.chunk_index ?? 0
-    existingMap.set(`${vt}:${ci}`, row)
-  }
-
-  // If force_regenerate, delete all current embeddings first
-  if (force_regenerate) {
-    await adminDb.from('embeddings').delete().eq('document_id', item_id)
-    existingMap.clear()
-  }
-
-  const created: string[] = []
-  const skipped: string[] = []
-  const errors: string[] = []
-
-  // Build content for non-summary vectors synchronously
-  const syncVectors = vectorTypes.filter(vt => vt !== 'summary')
-  const contents: Array<{ vt: string; text: string; chunkIndex: number }> = []
-
-  for (const vt of syncVectors) {
-    const builder = CONTENT_BUILDERS[vt]
-    if (!builder) { errors.push(`Unknown vector type: ${vt}`); continue }
-    const text = builder(item, { embedding_fields: embeddingFields })
-    if (!text) { skipped.push(`${vt}:empty`); continue }
-    contents.push({ vt, text, chunkIndex: 0 })
-  }
-
-  // Summary vector — async LLM call
-  if (vectorTypes.includes('summary')) {
-    const summaryText = await generateAiSummary(item)
-    if (summaryText) contents.push({ vt: 'summary', text: summaryText, chunkIndex: 0 })
-  }
-
-  // Filter out unchanged chunks (by content hash)
-  const toEmbed = contents.filter(({ vt, text, chunkIndex }) => {
-    const hash = contentHash(text)
-    const key = `${vt}:${chunkIndex}`
-    const row = existingMap.get(key)
-    if (row && row.content_hash === hash) { skipped.push(key); return false }
-    return true
-  })
-
-  if (!toEmbed.length) {
-    return { item_id, embeddings_created: 0, embeddings_skipped: skipped.length, errors }
-  }
-
-  // Single batched API call for all vectors that need updating
-  let vectors: string[] = []
-  try {
-    vectors = await callEmbeddingApi(toEmbed.map(c => c.text))
-  } catch (e: any) {
-    throw new Error(`Embedding API call failed: ${e.message}`)
-  }
-
-  const now = new Date().toISOString()
-
-  // Upsert each vector
-  for (let i = 0; i < toEmbed.length; i++) {
-    const { vt, text, chunkIndex } = toEmbed[i]
-    const hash = contentHash(text)
-    const key = `${vt}:${chunkIndex}`
-    const existingRow = existingMap.get(key)
-
-    const row = {
-      account_id:   resolvedAccountId,
-      model_id:     'text-embedding-3-small',
-      document_id:  item_id,
-      chunk_index:  chunkIndex,
-      content:      text,
-      embedding:    vectors[i],
-      content_hash: hash,
-      approved_at:  isPublished ? now : null,
-      revoked_at:   null,
-      metadata: {
-        vector_type:    vt,
-        item_type:      item.type?.design_schema ? (item.data?.kb_type ? 'kb_article' : 'item') : 'item',
-        kb_type:        kbType,
-        security_level: item.data?.security_level || 'internal',
-        source_item_id: item_id,
-      },
-    }
-
-    if (existingRow) {
-      await adminDb.from('embeddings').update(row).eq('id', existingRow.id)
-    } else {
-      await adminDb.from('embeddings').insert(row)
-    }
-    created.push(key)
-  }
-
-  await emitLog(ctx, 'embeddings.generated',
-    { type: 'item', id: item_id },
-    { after: { vectors_created: created.length, vectors_skipped: skipped.length, is_published: isPublished } }
-  )
-
-  return {
-    item_id,
-    embeddings_created: created.length,
-    embeddings_skipped: skipped.length,
-    errors,
-  }
-})
-
-// ─── REVOKE ───────────────────────────────────────────────────────────────────
-/**
- * Sets revoked_at = now() on all embeddings for a document_id.
- * Embeddings are NOT deleted — the row stays for audit trail.
- * match_embeddings will not return them (revoked_at IS NULL is a hard filter).
- *
- * Body: document_id (required)
- */
+// CIL[END chunk_id="embeddings_searchsemantic_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_revoke_1783969696" type="function" identity="revoke" parent="none"]
+// CIL[DOC-MACRO purpose="Revoke embeddings for document"]
+// CIL[DOC-RESPONSIBILITY responsibility="Mark embeddings as revoked for compliance"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="revocation_count" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Set revoked_at timestamp for document embeddings" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 revoke = createHandler(async (ctx, body) => {
   const { document_id } = body || {}
   if (!document_id) throw new Error('document_id is required')
@@ -856,15 +863,21 @@ export const revoke = createHandler(async (ctx, body) => {
 
   return { document_id, revoked_count: data?.length || 0 }
 })
-
-// ─── APPROVE ─────────────────────────────────────────────────────────────────
-/**
- * Clears revoked_at and refreshes approved_at on all embeddings for a document_id.
- * Called when an item re-enters published state (also handled automatically by
- * the items_embedding_sync DB trigger, but available as an explicit API action).
- *
- * Body: document_id (required)
- */
+// CIL[END chunk_id="embeddings_revoke_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_approve_1783969696" type="function" identity="approve" parent="none"]
+// CIL[DOC-MACRO purpose="Approve embeddings for document"]
+// CIL[DOC-RESPONSIBILITY responsibility="Mark embeddings as approved for search"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="approval_count" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Set approved_at timestamp and clear revoked_at" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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) => {
   const { document_id } = body || {}
   if (!document_id) throw new Error('document_id is required')
@@ -885,24 +898,23 @@ export const approve = createHandler(async (ctx, body) => {
 
   return { document_id, approved_count: data?.length || 0 }
 })
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: EMBEDDINGS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    EMBEDDINGS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        5c4c550bcf413d5975c54a1f1cbfbc4641425d663127fa55fac1616085a43644
- * @macro       Embeddings Router
- * @micro       Routes HTTP methods and actions to appropriate 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/batch-create/delete-document/cleanup/search-similar/search-semantic/stats)
- * @depends-on  [createHandler, list, get, create, update, getStats, batchCreate, deleteByDocument, cleanup, searchSimilar, searchSemantic]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        embeddings, router, crud, netlify-function
- */
+// CIL[END chunk_id="embeddings_approve_1783969696"]
+// CIL[BEGIN chunk_id="embeddings_handler_1783969696" type="function" identity="handler" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/embeddings" content="The embeddings generate action reads item.type.design_schema.vector_types to decide which content builders to run and design_schema.embedding_fields.structure to pick fields for the structure vector. Defaults are [semantic, structure] when vector_types is absent."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="Unknown vector_types entries are logged as errors and skipped. The embeddings function expects the type join to expose design_schema; items created without a type_id will not produce embeddings."]
+// CIL[DOC-MACRO purpose="Route embeddings HTTP methods"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to embedding operations"]
+// CIL[DOC-CONTEXT module="embeddings" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="function_responses" errors="method_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Route based on action and method to specific embedding functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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'
@@ -969,4 +981,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: EMBEDDINGS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="embeddings_handler_1783969696"]