spine-framework 0.3.145 → 0.4.1

package/.framework/functions/apps.ts

@@ -1,3 +1,12 @@
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Application management handlers and CRUD operations for public.apps"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define and export Netlify-style handler functions for the app lifecycle: list, get, schema, create, update, remove, availability, version, and dispatch"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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="imported shared modules" outputs="exported handler constants" errors="import-time type errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports shared middleware and permission helpers; exports handler functions for the apps API" notable_decisions="Uses createHandler for consistent request/response wrapping; delegates to PermissionEngine for access control"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="backend maintainers"]
 
 
 
@@ -25,53 +34,56 @@
 
 
 
- 
 
+
+
+
+
+ 
 
 
 
 
 
 
-// CIL[BEGIN chunk_id="apps_moduleheader_1783969696" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for apps module"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import middleware, database, permissions, and logging utilities"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required dependencies for app management functions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.96" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.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"]
 
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { isSystemAdmin } from './_shared/principal'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
-
-const permissions = PermissionEngine as any
-// CIL[END chunk_id="apps_moduleheader_1783969696"]
-// CIL[BEGIN chunk_id="apps_list_1783969696" type="function" identity="list" parent="none"]
-// CIL[DOC-LEARNING topic="apps_list:get_account_apps_filter" content="/api/apps?action=list calls get_account_apps, which filters by account ownership, is_active, and the requesting user's roles. An app missing from this list will never be rendered by AuthenticatedRouter."]
-// CIL[DOC-MACRO purpose="List apps with filtering and permissions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and filter apps by account and user roles"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_app_list" errors="auth_errors,db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Query apps by account with role-based filtering and data sanitization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-VECTOR type="context" content="purpose='Application management handlers and CRUD operations for public.apps'; 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/apps.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:permissions:constant" type="constant" identity="permissions" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Type alias shim for PermissionEngine"]
+// CIL[DOC-RESPONSIBILITY responsibility="Reference PermissionEngine with loose typing for app handlers"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="permissions reference" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Casts PermissionEngine to any to avoid strict type errors in this module" notable_decisions="Should be replaced by a properly typed export from the permissions engine"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/RolesPage.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."]
+const permissions = PermissionEngine as any
+// CIL[DOC-VECTOR type="context" content="purpose='Type alias shim for 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/apps.ts:permissions:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="List apps for an account with optional filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return a sanitized list of apps accessible to the caller's roles"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query with include_system, include_inactive, account_id; ctx.accountId, ctx.principal, ctx.db" outputs="array of sanitized app records" errors="Account context required; database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolves target account, selects adminDb for system admins, calls get_account_apps RPC, and sanitizes each record" notable_decisions="Defaults include_system to true unless explicitly false; uses sanitizeRecordData per row"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const list = createHandler(async (ctx, body) => {
   const { include_system, include_inactive, account_id } = ctx.query || {}
 
@@ -105,21 +117,21 @@ export const list = createHandler(async (ctx, body) => {
 
   return sanitized
 })
-// CIL[END chunk_id="apps_list_1783969696"]
-// CIL[BEGIN chunk_id="apps_get_1783969696" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Get single app by ID or slug"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve individual app record with owner details"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_app" errors="not_found,db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Query app by ID or slug and sanitize data for response" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.96" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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 apps for an account with optional 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/apps.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single active app by id or slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return a sanitized app record matching the requested id or slug"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.id or slug" outputs="sanitized app record" errors="App ID or slug required; not found; database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Queries the apps table by id or slug, limits to active records, and returns sanitized data" notable_decisions="Prefers id over slug; uses .single() to enforce a single result"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const get = createHandler(async (ctx, body) => {
   const { id, slug } = ctx.query || {}
   
@@ -147,21 +159,21 @@ export const get = createHandler(async (ctx, body) => {
   
   return await sanitizeRecordData(ctx, data, 'app')
 })
-// CIL[END chunk_id="apps_get_1783969696"]
-// CIL[BEGIN chunk_id="apps_getschema_1783969696" type="function" identity="getSchema" parent="none"]
-// CIL[DOC-MACRO purpose="Get app schema configuration"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve schema definition for specific app"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="app_schema" errors="not_found,db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Call stored procedure to get app schema by slug" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="rpc_behavior_not_mapped"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 1. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch a single active app by id or slug'; 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/apps.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:getSchema:constant" type="constant" identity="getSchema" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Retrieve the design schema for an app by slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the schema payload from the get_app_schema RPC"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.slug" outputs="app design schema" errors="App slug is required; database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates the slug and invokes the get_app_schema RPC, returning the result" notable_decisions="Relies on a database stored procedure for schema generation"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getSchema = createHandler(async (ctx, body) => {
   const { slug } = ctx.query || {}
 
@@ -176,21 +188,21 @@ export const getSchema = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="apps_getschema_1783969696"]
-// CIL[BEGIN chunk_id="apps_create_1783969696" type="function" identity="create" parent="none"]
-// CIL[DOC-MACRO purpose="Create new app with validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create app record with permissions and audit logging"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="created_app" errors="validation_errors,permission_errors" side_effects="db_write,audit_log"]
-// CIL[DOC-MICRO logic_summary="Validate permissions, check slug uniqueness, create app, log event" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Retrieve the design schema for an app by slug'; 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/apps.ts:getSchema:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Create a new app record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate input and permissions, insert a new app row, and emit an audit log"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="body with slug, name, and optional fields; ctx.principal, ctx.accountId" outputs="created app record" errors="Missing slug/name; anonymous user; insufficient permissions; duplicate slug; database errors" side_effects="inserts an apps row and emits app.created log"]
+// CIL[DOC-MICRO logic_summary="Enforces required fields and auth, checks create permission, ensures slug uniqueness, inserts with defaults, and emits an audit event" notable_decisions="Defaults version, app_type, source, route_prefix, and min_role; only system admins bypass permission checks"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const create = createHandler(async (ctx, body) => {
   const { slug, name, description, icon, color, version, app_type, source, owner_account_id, config, nav_items, min_role, integration_deps, metadata, route_prefix, renderer } = body
 
@@ -258,21 +270,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="apps_create_1783969696"]
-// CIL[BEGIN chunk_id="apps_update_1783969696" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Update existing app with permissions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Update app record with field-level permission validation"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="updated_app" errors="not_found,permission_errors" side_effects="db_write,audit_log"]
-// CIL[DOC-MICRO logic_summary="Validate update permissions, apply changes, log modification" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Create a new app record'; 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/apps.ts:create:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Update an existing app"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate the caller, load the current record, check field-level permissions, and apply updates"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="body with id and update fields; ctx.principal, ctx.accountId" outputs="updated app record" errors="App ID is required; not found; field permission denied; database errors" side_effects="updates the apps row and emits app.updated log"]
+// CIL[DOC-MICRO logic_summary="Finds the current record, validates update permissions, sets updated_at, persists changes, and emits an audit event" notable_decisions="Strips body id from updates; uses validateUpdatePermissions to enforce field-level access"]
+// 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 || {}
@@ -324,21 +336,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="apps_update_1783969696"]
-// CIL[BEGIN chunk_id="apps_remove_1783969696" type="function" identity="remove" parent="none"]
-// CIL[DOC-MACRO purpose="Soft delete app by deactivating"]
-// CIL[DOC-RESPONSIBILITY responsibility="Deactivate app record with audit logging"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="deactivated_app" errors="not_found,auth_errors" side_effects="db_write,audit_log"]
-// CIL[DOC-MICRO logic_summary="Set is_active=false instead of hard delete, log removal" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.96" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Update an existing app'; 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/apps.ts:update:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Soft-delete an app"]
+// CIL[DOC-RESPONSIBILITY responsibility="Set is_active to false for an app after authentication and existence checks"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="body or query id; ctx.principal, ctx.accountId" outputs="deactivated app record" errors="App ID is required; not found; database errors" side_effects="deactivates the app and emits app.deleted log"]
+// CIL[DOC-MICRO logic_summary="Loads the record, flips the is_active flag and updated_at, and emits an audit event" notable_decisions="Performs a soft delete rather than a hard delete"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const remove = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
 
@@ -377,21 +389,21 @@ export const remove = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="apps_remove_1783969696"]
-// CIL[BEGIN chunk_id="apps_checkavailability_1783969696" type="function" identity="checkAvailability" parent="none"]
-// CIL[DOC-MACRO purpose="Check if app slug is available"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate app slug uniqueness for account"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="availability_boolean" errors="validation_errors,db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Call stored procedure to check slug availability in account" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="rpc_behavior_not_mapped"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Soft-delete an app'; 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/apps.ts:remove:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:checkAvailability:constant" type="constant" identity="checkAvailability" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Check whether a slug is available for an account"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return an availability boolean from the is_app_available RPC"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.slug and ctx.accountId" outputs="{ available: boolean }" errors="App slug is required; account context required; database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates the slug and account, then calls the is_app_available RPC" notable_decisions="Uses an account-scoped stored procedure to determine availability"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const checkAvailability = createHandler(async (ctx, body) => {
   const { slug } = ctx.query || {}
 
@@ -413,21 +425,21 @@ export const checkAvailability = createHandler(async (ctx, body) => {
 
   return { available: data }
 })
-// CIL[END chunk_id="apps_checkavailability_1783969696"]
-// CIL[BEGIN chunk_id="apps_updateversion_1783969696" type="function" identity="updateVersion" parent="none"]
-// CIL[DOC-MACRO purpose="Update app version number"]
-// CIL[DOC-RESPONSIBILITY responsibility="Change app version with audit logging"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="success_status" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
-// CIL[DOC-MICRO logic_summary="Call stored procedure to update version, log change" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="rpc_behavior_not_mapped"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Check whether a slug is available for an account'; 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/apps.ts:checkAvailability:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:updateVersion:constant" type="constant" identity="updateVersion" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Update an app version via a stored procedure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Bump the version of an app and emit an audit log"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="body.id and body.version" outputs="{ success: true }" errors="App ID and version are required; database errors" side_effects="updates the app version and emits app.version_updated log"]
+// CIL[DOC-MICRO logic_summary="Validates inputs, calls the update_app_version RPC, and emits an audit event" notable_decisions="RPC encapsulates version logic and any related triggers"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const updateVersion = createHandler(async (ctx, body) => {
   const { id, version } = body
 
@@ -447,21 +459,21 @@ export const updateVersion = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-// CIL[END chunk_id="apps_updateversion_1783969696"]
-// CIL[BEGIN chunk_id="apps_handler_1783969696" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Route HTTP methods to app functions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to appropriate app operations"]
-// CIL[DOC-CONTEXT module="apps" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="function_responses" errors="method_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Route based on HTTP method and query parameters to specific functions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.97" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Update an app version via a stored procedure'; 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/apps.ts:updateVersion:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/apps.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/apps.ts"]
+// CIL[DOC-MACRO purpose="Dispatch incoming app requests to the correct handler by HTTP method and action"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route GET/POST/PATCH/DELETE methods to the appropriate list, get, schema, create, update, remove, and version handlers"]
+// CIL[DOC-CONTEXT module="functions" layer="edge" 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/apps.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.method, action, id, and slug" outputs="result of the delegated handler" errors="Unsupported HTTP method" side_effects="delegates to other handlers"]
+// CIL[DOC-MICRO logic_summary="Switches on HTTP method and query params to dispatch to the appropriate app operation" notable_decisions="GET with id or slug maps to get; action schema/available handled; POST action version or create; PATCH update; DELETE remove"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
   const method = ctx.query?.method || 'GET'
 
@@ -492,4 +504,10 @@ export const handler = createHandler(async (ctx, body) => {
       throw new Error(`Unsupported method: ${method}`)
   }
 })
-// CIL[END chunk_id="apps_handler_1783969696"]
+// CIL[DOC-VECTOR type="context" content="purpose='Dispatch incoming app requests to the correct handler by HTTP method and action'; 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/apps.ts:handler:constant"]