spine-framework 0.3.144 → 0.4.0

package/.framework/functions/cil-context.ts

@@ -1,25 +1,27 @@
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_module_header_1784235266" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Module header and top-level exports for cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Own module-level imports, exports, and configuration for cortex.functions.custom_cil-context"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="module exports and side effects" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Declares module scope, imports dependencies, and exports public surface of cortex.functions.custom_cil-context" 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: function. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/table-primitives.tsx, .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"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Netlify function handler for CIL context lookup, edit-safety briefing, and post-edit next steps"]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose /api/cil-context endpoint that dispatches get_context, find_context, and post_edit actions"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="api" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query/body: action, stable_id, version_id, project_id, chunk_id, chunk_name, max_depth" outputs="JSON { ok, brief } or { ok, error, hint }" errors="Invalid stable_id; missing version_id or chunk_id; chunk not found; unknown action" side_effects="Reads items and links tables; resolves link type IDs"]
+// CIL[DOC-MICRO logic_summary="Routes requests to buildBrief or post-edit helpers and returns a structured response" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer, ai, runtime"]
 
 
 
 
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
+import { parseStableId } from './_shared/cil'
 import { resolveLinkTypeId } from './_shared/resolve-ids'
+// CIL[DOC-VECTOR type="context" content="purpose='Netlify function handler for CIL context lookup, edit-safety briefing, and post-edit next steps'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:module_header:module_header"]
 
 
 
@@ -27,46 +29,39 @@ import { resolveLinkTypeId } from './_shared/resolve-ids'
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_module_header_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_getchunkbyid_1784235266" type="function" identity="getchunkbyid" parent="none"]
-// CIL[DOC-MACRO purpose="Implements getchunkbyid logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute getchunkbyid and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides getchunkbyid with getChunkById(id: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:getChunkById:function" type="function" identity="getChunkById" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single CIL chunk row by item id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the items row for a given chunk database id"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="data" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="id: string" outputs="item object or null" errors="none" side_effects="Selects id, title, data from items table"]
+// CIL[DOC-MICRO logic_summary="Query adminDb items by id using maybeSingle and return data" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
-// 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 getChunkById(id: string): Promise<any | null> {
   const { data } = await adminDb.from('items').select('id, title, data')
     .eq('id', id).maybeSingle()
   return data
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch a single CIL chunk row by item id'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:getChunkById:function"]
 
 
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_getchunkbyid_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_findchunkbyname_1784235266" type="function" identity="findchunkbyname" parent="none"]
-// CIL[DOC-MACRO purpose="Implements findchunkbyname logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute findchunkbyname and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides findchunkbyname with findChunkByName(name: string, projectId?: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:findChunkByName:function" type="function" identity="findChunkByName" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Find an active CIL chunk by its chunk name and optional project"]
+// CIL[DOC-RESPONSIBILITY responsibility="Locate a chunk item using its chunk_name and optional project_id"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="data" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="name: string, projectId?: string" outputs="item object or null" errors="none" side_effects="Filters items table by kb_type, chunk_name, is_active, and optional project_id"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-MICRO logic_summary="Build a query for cil_chunk items matching name and project, limit 1, and return data" notable_decisions=""]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
-// 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 findChunkByName(name: string, projectId?: string): Promise<any | null> {
   let q = adminDb.from('items').select('id, title, data')
     .filter('data->>kb_type', 'eq', 'cil_chunk')
@@ -76,27 +71,80 @@ async function findChunkByName(name: string, projectId?: string): Promise<any |
   const { data } = await q.limit(1).maybeSingle()
   return data
 }
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:findChunkByName:function"]
+// CIL[DOC-VECTOR type="context" content="purpose='Find an active CIL chunk by its chunk name and optional project'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+// CIL[DOC-CONTEXT module="unknown" layer="unknown" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
 
 
 
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_findchunkbyname_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_blastradiusbfs_1784235266" type="function" identity="blastradiusbfs" parent="none"]
-// CIL[DOC-MACRO purpose="Implements blastradiusbfs logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute blastradiusbfs and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides blastradiusbfs with blastRadiusBFS( inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:getProjectActiveVersionId:function" type="function" identity="getProjectActiveVersionId" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Resolve a project's currently active version id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the active_version_id stored on a project item"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="data" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="projectId: string" outputs="version id string or null" errors="none" side_effects="Selects from items table"]
+// CIL[DOC-MICRO logic_summary="Fetch the project item and return data.active_version_id or null" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
-// 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."]
+async function getProjectActiveVersionId(projectId: string): Promise<string | null> {
+  const { data } = await adminDb.from('items').select('id, data')
+    .eq('id', projectId).maybeSingle()
+  return data?.data?.active_version_id || null
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve a project's currently active version id'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:getProjectActiveVersionId:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:findChunkByStableId:function" type="function" identity="findChunkByStableId" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Find a CIL chunk by its stable id within a version and optional project"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the active chunk matching stable_id and version_id"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="data" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="stableId: string, versionId: string, projectId?: string" outputs="item object or null" errors="none" side_effects="Filters items table by kb_type, stable_id, version_id, is_active, and optional project_id"]
+// CIL[DOC-MICRO logic_summary="Query cil_chunk items by stable_id, version, and project, limit 1, and return data" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+async function findChunkByStableId(
+  stableId: string,
+  versionId: string,
+  projectId?: string
+): Promise<any | null> {
+  let q = adminDb.from('items').select('id, title, data')
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .filter('data->>stable_id', 'eq', stableId)
+    .filter('data->>version_id', 'eq', versionId)
+    .eq('is_active', true)
+  if (projectId) q = q.filter('data->>project_id', 'eq', projectId)
+  const { data } = await q.limit(1).maybeSingle()
+  return data
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Find a CIL chunk by its stable id within a version and optional project'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:findChunkByStableId:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:blastRadiusBFS:function" type="function" identity="blastRadiusBFS" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Breadth-first search of transitive callers for a chunk"]
+// CIL[DOC-RESPONSIBILITY responsibility="Collect upstream callers up to maxDepth using cil_calls links"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="analysis" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="chunkId: string, maxDepth: number, callsLinkTypeId: string" outputs="Array of { chunk_id, chunk_name, file_path, depth }" errors="none" side_effects="Repeatedly queries links and items tables"]
+// CIL[DOC-MICRO logic_summary="Traverse caller links from target to source, tracking depth and visited set, aggregating chunk metadata" notable_decisions="Uses queue-based BFS; only follows depth hops; populates result with chunk_id, name, path, and depth"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 async function blastRadiusBFS(
   chunkId: string,
   maxDepth: number,
@@ -135,27 +183,30 @@ async function blastRadiusBFS(
 
   return result
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Breadth-first search of transitive callers for a chunk'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:blastRadiusBFS:function"]
 
 
 
 
+    // CIL[DOC-STABILITY stability="internal"]
+    // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+    // CIL[DOC-CONTEXT module="unknown" layer="unknown" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_blastradiusbfs_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_getconfigdeps_1784235266" type="function" identity="getconfigdeps" parent="none"]
-// CIL[DOC-MACRO purpose="Implements getconfigdeps logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute getconfigdeps and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides getconfigdeps with getConfigDeps( inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:getConfigDeps:function" type="function" identity="getConfigDeps" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Find configuration fields that target a chunk"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return config dependencies linked to the chunk via cil_configures"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="analysis" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="chunkId: string, configuresLinkTypeId: string | null" outputs="Array of { field_name, source_file, config_id }" errors="none" side_effects="Selects from links and items tables"]
+// CIL[DOC-MICRO logic_summary="Fetch cil_configures links pointing to the chunk, then resolve source item metadata into config dependency records" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
-// 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 getConfigDeps(
   chunkId: string,
   configuresLinkTypeId: string | null
@@ -180,27 +231,27 @@ async function getConfigDeps(
   }
   return results
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Find configuration fields that target a chunk'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:getConfigDeps:function"]
 
 
 
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_getconfigdeps_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_safetyverdict_1784235266" type="function" identity="safetyverdict" parent="none"]
-// CIL[DOC-MACRO purpose="Implements safetyverdict logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute safetyverdict and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides safetyverdict with safetyVerdict( inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:safetyVerdict:function" type="function" identity="safetyVerdict" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Classify edit risk for a chunk based on stability, blast radius, drift, and docs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compute safe/caution/risky level and a human-readable flag list"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="analysis" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="chunk: any, blastRadius: any[], driftStatus: 'current' | 'stale' | 'unknown', configDeps: any[]" outputs="{ level, summary, flags }" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Collect warning flags from chunk data and derived metrics, then choose a level based on flag severity" notable_decisions="Risky if stable, high blast radius, or stale; caution otherwise; safe when no flags"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. 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 safetyVerdict(
   chunk: any,
   blastRadius: any[],
@@ -231,26 +282,26 @@ function safetyVerdict(
 
   return { level, summary, flags }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Classify edit risk for a chunk based on stability, blast radius, drift, and docs'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:safetyVerdict:function"]
 
 
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_safetyverdict_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_buildbrief_1784235266" type="function" identity="buildbrief" parent="none"]
-// CIL[DOC-MACRO purpose="Implements buildbrief logic in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute buildbrief and return its computed result"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Provides buildbrief with buildBrief(chunk: any, maxBlastDepth = 4 inputs, handling internal flow and returning a result" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:buildBrief:function" type="function" identity="buildBrief" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="Assemble a complete context brief for a CIL chunk"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return contract, hash status, blast radius, calls, tests, config deps, and edit safety verdict"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="analysis" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="chunk: any, maxBlastDepth = 4" outputs="Record<string, any> brief" errors="Resolves link type ids with catch-to-null; drift status defaults to unknown" side_effects="Queries links and items tables multiple times"]
+// CIL[DOC-MICRO logic_summary="Resolve call/test/configure link type IDs, run blast radius BFS, gather callees and test paths, load config dependencies, derive drift status, and compute safety verdict" notable_decisions="Falls back to stored test_unit_path and test_e2e_path when no test links exist; drift status is not currently computed from a hash comparison"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
 async function buildBrief(chunk: any, maxBlastDepth = 4): Promise<Record<string, any>> {
   const d = chunk.data || {}
 
@@ -306,6 +357,7 @@ async function buildBrief(chunk: any, maxBlastDepth = 4): Promise<Record<string,
   return {
     chunk_id: chunk.id,
     chunk_name: d.chunk_name || '',
+    stable_id: d.stable_id || null,
     file_path: d.file_path || '',
     line_start: d.line_start || null,
     line_end: d.line_end || null,
@@ -348,36 +400,48 @@ async function buildBrief(chunk: any, maxBlastDepth = 4): Promise<Record<string,
     edit_safety: verdict,
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Assemble a complete context brief for a CIL chunk'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:buildBrief:function"]
 
 
 
 
 
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_buildbrief_1784235266"]
-// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_context_handler_1784235266" type="variable" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Defines handler configuration or state in cortex.functions.custom_cil-context"]
-// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for handler"]
-// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-context" layer="function" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="value of handler" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Declares handler with initial value or constant binding used by cortex.functions.custom_cil-context" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+// CIL[BEGIN stable_id="~/.framework/functions/cil-context.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/cil-context.ts"]
+// CIL[DOC-MACRO purpose="createHandler wrapper dispatching cil-context API actions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate input and call find or build helpers for get_context, find_context, and post_edit"]
+// CIL[DOC-CONTEXT module="functions/cil" layer="api" related_files=".framework/functions/_shared/cil.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/cil-context.ts"]
+// CIL[DOC-CONTRACT inputs="ctx and body from createHandler" outputs="JSON response for the selected action" errors="Throws on missing/invalid params or unknown action" side_effects="Calls buildBrief and database helpers"]
+// CIL[DOC-MICRO logic_summary="Select action from query/body, resolve chunk by stable_id, name, or chunk_id, then build and return the brief or post-edit instructions" notable_decisions="get_context requires stable_id or chunk_id; find_context requires stable_id or chunk_name; post_edit requires chunk_id"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
 export const handler = createHandler(async (ctx, body) => {
   const action = ctx.query?.action || 'get_context'
 
   
   if (action === 'get_context') {
+    const stableId = ctx.query?.stable_id || body?.stable_id
+    const versionId = ctx.query?.version_id || body?.version_id
+    const projectId = ctx.query?.project_id || body?.project_id
     const chunkId = ctx.query?.chunk_id || body?.chunk_id
-    if (!chunkId) throw new Error('chunk_id is required')
 
-    const chunk = await getChunkById(chunkId)
-    if (!chunk) throw new Error(`Chunk not found: ${chunkId}`)
+    let chunk: any | null = null
+    if (stableId) {
+      if (!parseStableId(stableId)) throw new Error('Invalid stable_id format')
+      const effectiveVersionId = versionId || (projectId ? await getProjectActiveVersionId(projectId) : undefined)
+      if (!effectiveVersionId) throw new Error('version_id or project_id required when using stable_id')
+      chunk = await findChunkByStableId(stableId, effectiveVersionId, projectId)
+      if (!chunk) throw new Error(`Chunk not found: stable_id=${stableId}, version_id=${effectiveVersionId}`)
+    } else {
+      if (!chunkId) throw new Error('chunk_id is required')
+      chunk = await getChunkById(chunkId)
+      if (!chunk) throw new Error(`Chunk not found: ${chunkId}`)
+    }
 
     const maxDepth = parseInt(ctx.query?.max_depth || body?.max_depth || '4', 10)
     const brief = await buildBrief(chunk, maxDepth)
@@ -387,16 +451,33 @@ export const handler = createHandler(async (ctx, body) => {
 
   
   if (action === 'find_context') {
-    const chunkName = ctx.query?.chunk_name || body?.chunk_name
+    const stableId = ctx.query?.stable_id || body?.stable_id
+    const versionId = ctx.query?.version_id || body?.version_id
     const projectId = ctx.query?.project_id || body?.project_id
-    if (!chunkName) throw new Error('chunk_name is required')
-
-    const chunk = await findChunkByName(chunkName, projectId)
-    if (!chunk) {
-      return {
-        ok: false,
-        error: `No chunk named "${chunkName}" found${projectId ? ` in project ${projectId}` : ''}`,
-        hint: 'Use custom_cil-graph?action=search to find chunks by description',
+    const chunkName = ctx.query?.chunk_name || body?.chunk_name
+
+    let chunk: any | null = null
+    if (stableId) {
+      if (!parseStableId(stableId)) throw new Error('Invalid stable_id format')
+      const effectiveVersionId = versionId || (projectId ? await getProjectActiveVersionId(projectId) : undefined)
+      if (!effectiveVersionId) throw new Error('version_id or project_id required when using stable_id')
+      chunk = await findChunkByStableId(stableId, effectiveVersionId, projectId)
+      if (!chunk) {
+        return {
+          ok: false,
+          error: `No chunk with stable_id "${stableId}" found for version ${effectiveVersionId}`,
+          hint: 'Use custom_cil-graph?action=search to find chunks by description',
+        }
+      }
+    } else {
+      if (!chunkName) throw new Error('chunk_name is required')
+      chunk = await findChunkByName(chunkName, projectId)
+      if (!chunk) {
+        return {
+          ok: false,
+          error: `No chunk named "${chunkName}" found${projectId ? ` in project ${projectId}` : ''}`,
+          hint: 'Use custom_cil-graph?action=search to find chunks by description',
+        }
       }
     }
 
@@ -423,6 +504,7 @@ export const handler = createHandler(async (ctx, body) => {
       ok: true,
       chunk_id: chunkId,
       chunk_name: d.chunk_name || '',
+      stable_id: d.stable_id || null,
       file_path: d.file_path || '',
       stored_hash: d.stored_hash || null,
       hash_updated_at: d.hash_updated_at || null,
@@ -439,7 +521,12 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error(`Unknown action: ${action}. Valid: get_context, find_context, post_edit`)
 })
+// CIL[DOC-VECTOR type="context" content="purpose='createHandler wrapper dispatching cil-context API actions'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/cil.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/cil-context.ts:handler:constant"]
 
 
-
-// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_context_handler_1784235266"]