spine-framework 0.3.145 → 0.4.0

package/.framework/functions/prompt-configs.ts

@@ -1,29 +1,39 @@
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Import shared dependencies for prompt configuration handlers."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare module-level imports used by prompt-config handlers."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports middleware, audit, permissions, database, and principal utilities." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework"]
 import { createHandler } from './_shared/middleware'
 import { emitLog } from './_shared/audit'
 import { sanitizeRecordData } from './_shared/permissions'
 import { adminDb } from './_shared/db'
 import { isSystemAdmin } from './_shared/principal'
+// CIL[DOC-VECTOR type="context" content="purpose='Import shared dependencies for prompt configuration handlers.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:module_header:module_header"]
 
 
 
 
 
 
-// CIL[BEGIN chunk_id="prompt-configs_module_header_1783932909" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Lists prompt configs with filtering and sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config listing with filters"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="ctx, _body" outputs="Array of sanitized prompt configs" errors="Throws on DB errors" side_effects="Database queries, permission sanitization"]
-// CIL[DOC-MICRO logic_summary="Filters by model/active status, applies sanitization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="List prompt configuration records with optional filtering."]
+// CIL[DOC-RESPONSIBILITY responsibility="Return a paginated, filtered list of prompt configs for the current account."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query optional model, is_active, limit, offset" outputs="sanitized prompt_config records array" errors="throws if account missing or db error" side_effects="queries prompt_configs table"]
+// CIL[DOC-MICRO logic_summary="Determines db context, builds query with filters and pagination, sanitizes each record." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .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: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const list = createHandler(async (ctx, _body) => {
   const { model, is_active, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -59,21 +69,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// CIL[END chunk_id="prompt-configs_module_header_1783932909"]
-// CIL[BEGIN chunk_id="prompt-configs_get_1783932909" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Retrieves single prompt config by ID with sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle individual prompt config retrieval"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Sanitized prompt config record" errors="Throws if ID missing or DB error" side_effects="Database query, permission sanitization"]
-// CIL[DOC-MICRO logic_summary="Fetches config by ID, applies permission sanitization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.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="context" content="purpose='List prompt configuration records with optional filtering.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Retrieve a single prompt configuration by ID."]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the sanitized prompt config for the given id."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.id" outputs="sanitized prompt_config record" errors="throws if id missing or db error" side_effects="queries prompt_configs table"]
+// CIL[DOC-MICRO logic_summary="Validates id, fetches the single matching record, sanitizes and returns it." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -92,21 +102,21 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'prompt_config')
 })
-// CIL[END chunk_id="prompt-configs_get_1783932909"]
-// CIL[BEGIN chunk_id="prompt-configs_create_1783932909" type="function" identity="create" parent="none"]
-// CIL[DOC-MACRO purpose="Creates new prompt config with validation and defaults"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config creation with security"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Created prompt config record" errors="Throws on validation or DB errors" side_effects="Database insert, audit logging"]
-// CIL[DOC-MICRO logic_summary="Validates required fields, sets defaults, creates config" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 3. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 4."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Retrieve a single prompt configuration by ID.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Create a new prompt configuration record."]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert a new prompt_config with defaults and return the created record."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="body with name, slug and optional fields" outputs="created prompt_config record" errors="throws if name/slug missing, account missing, or db error" side_effects="inserts into prompt_configs table and emits audit log"]
+// CIL[DOC-MICRO logic_summary="Validates required fields, applies defaults, inserts the row, and emits an audit log." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const create = createHandler(async (ctx, body) => {
   const { app_id, name, slug, description, system_prompt, context_template, model, temperature, max_tokens,
     is_multi_turn, max_history_messages, confidence_threshold, escalation_action, escalation_target,
@@ -159,21 +169,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="prompt-configs_create_1783932909"]
-// CIL[BEGIN chunk_id="prompt-configs_update_1783932909" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Updates prompt config with field allowlist validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config updates with security"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Updated prompt config record" errors="Throws on validation or DB errors" side_effects="Database update, audit logging"]
-// CIL[DOC-MICRO logic_summary="Updates allowed fields, maintains audit trail" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 9. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/db.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 9. Total affected: 11."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Create a new prompt configuration record.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:create:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Update an existing prompt configuration."]
+// CIL[DOC-RESPONSIBILITY responsibility="Apply allowed field updates to a prompt config and return the updated record."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="body or query with id plus allowed updates" outputs="updated prompt_config record" errors="throws if id missing or db error" side_effects="updates prompt_configs table and emits audit log"]
+// CIL[DOC-MICRO logic_summary="Merges allowed updates with updated_at timestamp, performs the update, and emits an audit log." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   const { id: _bodyId, ...updates } = body || {}
@@ -207,21 +217,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="prompt-configs_update_1783932909"]
-// CIL[BEGIN chunk_id="prompt-configs_remove_1783932909" type="function" identity="remove" parent="none"]
-// CIL[DOC-MACRO purpose="Hard deletes prompt config with audit logging"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config deletion with audit trail"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="{success: true}" errors="Throws if ID missing or DB error" side_effects="Database delete, audit logging"]
-// CIL[DOC-MICRO logic_summary="Hard deletes config, maintains audit trail" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Update an existing prompt configuration.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:update:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Delete a prompt configuration by ID."]
+// CIL[DOC-RESPONSIBILITY responsibility="Remove a prompt_config record and confirm success."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.id" outputs="{ success: true }" errors="throws if id missing, not found, or db error" side_effects="deletes from prompt_configs table and emits audit log"]
+// CIL[DOC-MICRO logic_summary="Fetches the current record for audit, deletes the row, and emits an audit log." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const remove = createHandler(async (ctx, _body) => {
   const id = ctx.query?.id
 
@@ -251,21 +261,21 @@ export const remove = createHandler(async (ctx, _body) => {
 
   return { success: true }
 })
-// CIL[END chunk_id="prompt-configs_remove_1783932909"]
-// CIL[BEGIN chunk_id="prompt-configs_handler_1783932909" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Routes HTTP methods to prompt config handlers"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle request routing for prompt config CRUD"]
-// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Varies by handler" errors="Throws on unsupported methods" side_effects="Delegates to appropriate handler"]
-// CIL[DOC-MICRO logic_summary="Routes based on method, delegates to CRUD handlers" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Delete a prompt configuration by ID.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:remove:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/prompt-configs.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/prompt-configs.ts"]
+// CIL[DOC-MACRO purpose="Dispatch prompt configuration requests by HTTP method and query."]
+// CIL[DOC-RESPONSIBILITY responsibility="Route incoming requests to list, get, create, update, or remove handlers."]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/prompt-configs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query action and method, optional body" outputs="result from delegated handler" errors="throws if invalid action or method" side_effects="delegates to other handlers"]
+// CIL[DOC-MICRO logic_summary="Switches on HTTP method and query id/action to call the appropriate handler." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -289,4 +299,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="prompt-configs_handler_1783932909"]
+// CIL[DOC-VECTOR type="context" content="purpose='Dispatch prompt configuration requests by HTTP method and query.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/permissions.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/prompt-configs.ts:handler:constant"]

package/.framework/functions/roles.ts

@@ -1,9 +1,40 @@
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-AUDIENCE audience="framework-internal"]
+// CIL[DOC-MACRO purpose="Set up imports and exports for the roles Edge Function module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide shared middleware and permission utilities for role handlers"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="module exports and imports" errors="none at module load" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, adminDb, emitLog, PermissionEngine and sanitizeRecordData for role CRUD operations" notable_decisions="Centralizes role logic behind shared permission and database helpers"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
-
+// CIL[DOC-VECTOR type="context" content="purpose='Set up imports and exports for the roles Edge Function module'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:permissions:constant" type="constant" identity="permissions" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Provide a local alias for the shared PermissionEngine"]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose permission checks under a typed local constant for role handlers"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="permissions: any" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Casts PermissionEngine to any as a module-local permissions reference" notable_decisions="Avoids changing shared permissions typings by using a local any cast"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 const permissions = PermissionEngine as any
+// CIL[DOC-VECTOR type="context" content="purpose='Provide a local alias for the shared PermissionEngine'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:permissions:constant"]
 
 
 
@@ -11,21 +42,14 @@ const permissions = PermissionEngine as any
 
 
 
-// CIL[BEGIN chunk_id="roles_module_header_1783932909" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Lists roles with filtering and permission-based sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle role listing with app and system filters"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="ctx, _body" outputs="Array of role records" errors="Throws on DB errors" side_effects="Database queries, permission checks"]
-// CIL[DOC-MICRO logic_summary="Filters roles, applies permission sanitization for non-admins" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.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/roles.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="List active roles with optional app and system filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return a paginated list of roles respecting query filters and user permission scoping"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query with optional app_id, is_system, limit and offset" outputs="array of role records" errors="database errors and unhandled query failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Build a query on the roles table, filter by app_id and is_system, paginate and then either return full results for system admins or sanitize each record" notable_decisions="Defaults limit to 50 and offset to 0; sorts by is_system then name"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const list = createHandler(async (ctx, _body) => {
   const { app_id, is_system, limit = '50', offset = '0' } = ctx.query || {}
 
@@ -67,21 +91,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return filteredData
 })
-// CIL[END chunk_id="roles_module_header_1783932909"]
-// CIL[BEGIN chunk_id="roles_get_1783932909" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Retrieves single role by ID with sanitization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle individual role retrieval"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Single role record" errors="Throws if ID missing or DB error" side_effects="Database query, permission sanitization"]
-// CIL[DOC-MICRO logic_summary="Fetches role by ID, applies permission sanitization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.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="context" content="purpose='List active roles with optional app and system filters'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single active role by its id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return one sanitized role record when the caller provides a valid id"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.id" outputs="single role record" errors="missing id and database fetch errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Fetch the role by id with an app join and apply sanitizeRecordData before returning" notable_decisions="Requires id in query and treats missing records as database errors"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
   
@@ -104,21 +128,21 @@ export const get = createHandler(async (ctx, _body) => {
   const roleWithType = { ...data, type: 'role' }
   return await sanitizeRecordData(ctx, roleWithType, 'role')
 })
-// CIL[END chunk_id="roles_get_1783932909"]
-// CIL[BEGIN chunk_id="roles_create_1783932909" type="function" identity="create" parent="none"]
-// CIL[DOC-MACRO purpose="Creates new role with permission validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle role creation with security checks"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Created role record" errors="Throws on validation, permission, or DB errors" side_effects="Database insert, audit logging"]
-// CIL[DOC-MICRO logic_summary="Validates permissions, checks uniqueness, creates role" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch a single active role by its id'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Create a new role for an app or the platform"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate caller permissions, enforce slug uniqueness and insert a new role record"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="body with app_id, slug, name, description, permissions object and is_system flag" outputs="newly created role record" errors="missing fields, permission denied, duplicate slug or database errors" side_effects="inserts a roles row and emits an audit log"]
+// CIL[DOC-MICRO logic_summary="Require slug and name, enforce system_admin protection, check create permissions, guard against duplicate slugs and insert the role with a logged audit event" notable_decisions="Non-system-admins need surface create permission; system_admin slug is protected"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const create = createHandler(async (ctx, body) => {
   const { app_id, slug, name, description, permissions: rolePermissions, is_system } = body
 
@@ -184,21 +208,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="roles_create_1783932909"]
-// CIL[BEGIN chunk_id="roles_update_1783932909" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Updates role with field-level permission validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle role updates with security validation"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Updated role record" errors="Throws on validation, permission, or DB errors" side_effects="Database update, audit logging"]
-// CIL[DOC-MICRO logic_summary="Validates update permissions, applies changes with audit trail" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.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="context" content="purpose='Create a new role for an app or the platform'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:create:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Update an existing role by id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate the request, apply field-level update permissions and persist the changes"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="body with id and updates" outputs="updated role record" errors="missing id, missing role, validation failure or database errors" side_effects="updates the roles row and emits an audit log"]
+// CIL[DOC-MICRO logic_summary="Require id and a valid principal, fetch the current record, validate update fields, apply updates with a fresh timestamp and log the change" notable_decisions="Uses permissions.validateUpdatePermissions before applying any field changes"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const update = createHandler(async (ctx, body) => {
   const { id, ...updates } = body
 
@@ -247,21 +271,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="roles_update_1783932909"]
-// CIL[BEGIN chunk_id="roles_remove_1783932909" type="function" identity="remove" parent="none"]
-// CIL[DOC-MACRO purpose="Soft deletes role by setting is_active to false"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle role deletion with audit trail"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Deactivated role record" errors="Throws on validation or DB errors" side_effects="Database update, audit logging"]
-// CIL[DOC-MICRO logic_summary="Soft deletes role, maintains audit trail" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Update an existing role by id'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:update:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Soft-delete a role by setting is_active to false"]
+// CIL[DOC-RESPONSIBILITY responsibility="Mark the requested role as inactive and record the deletion in the audit log"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="body with id" outputs="deactivated role record" errors="missing id, missing role or database errors" side_effects="sets roles.is_active to false and emits an audit log"]
+// CIL[DOC-MICRO logic_summary="Require id and a valid principal, fetch the current record, update is_active to false and log the deletion" notable_decisions="Performs a soft delete instead of removing the row"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const remove = createHandler(async (ctx, body) => {
   const { id } = body
 
@@ -299,21 +323,21 @@ export const remove = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="roles_remove_1783932909"]
-// CIL[BEGIN chunk_id="roles_handler_1783932909" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Routes HTTP methods to appropriate role handlers"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle request routing for role CRUD operations"]
-// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Varies by handler" errors="Throws on unsupported methods" side_effects="Delegates to appropriate handler"]
-// CIL[DOC-MICRO logic_summary="Routes based on HTTP method, delegates to CRUD handlers" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Soft-delete a role by setting is_active to false'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:remove:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/roles.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/roles.ts"]
+// CIL[DOC-MACRO purpose="Route incoming role function requests to the correct handler by HTTP method"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch list, get, create, update and remove operations based on ctx.query.method"]
+// CIL[DOC-CONTEXT module="roles" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/roles.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.method and optional id" outputs="result from the dispatched handler" errors="unsupported method" side_effects="none directly; delegated handlers may mutate data"]
+// CIL[DOC-MICRO logic_summary="Select the method from query or default to GET, then route to list, get, create, update or remove accordingly" notable_decisions="GET with id calls get; GET without id calls list; unsupported methods throw"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const handler = createHandler(async (ctx, body) => {
   const method = ctx.query?.method || 'GET'
 
@@ -334,4 +358,10 @@ export const handler = createHandler(async (ctx, body) => {
       throw new Error(`Unsupported method: ${method}`)
   }
 })
-// CIL[END chunk_id="roles_handler_1783932909"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route incoming role function requests to the correct handler by HTTP method'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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/roles.ts:handler:constant"]