spine-framework 0.3.144 → 0.4.0

package/.framework/functions/item-progress.ts

@@ -1,65 +1,115 @@
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Defines the item-progress module and its CRUD handler exports"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provides Netlify function entry points and helpers for item progress records"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="exports" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports shared utilities and wires list, get, upsert, and update handlers behind a single method router" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="human; ai"]
 
 
 
 
-
-
-// CIL[BEGIN chunk_id="itemprogress_moduleheader_1783968140" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for item progress tracking API"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import handler utilities and database access"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="Import failures" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports createHandler, adminDb, resolveTypeId, emitLog" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { resolveTypeId } from './_shared/resolve-ids'
 import { emitLog } from './_shared/audit'
-// CIL[END chunk_id="itemprogress_moduleheader_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_constants_1783968140" type="constants" identity="constants" parent="none"]
-// CIL[DOC-LEARNING topic="runtime-type:generic/pipeline" content="item-progress reads typeRecord.design_schema.pipeline for the ordered list of statuses. Transitions are valid when the target index is greater than or equal to the current index. If pipeline is missing, the default is [not_started, in_progress, completed]."]
-// CIL[DOC-NOTE type="design_schema_caveat" content="Any status not in the pipeline array is treated as always allowed. Force=true bypasses pipeline validation, so the client can override if the type changes."]
-// CIL[DOC-MACRO purpose="Define progress pipeline constants and helper functions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide pipeline validation and composition utilities"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Constants and helper functions" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Defines default pipeline, transition validation, and composition helpers" 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, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.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="context" content="purpose='Defines the item-progress module and its CRUD handler exports'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:PIPELINE_DEFAULT:constant" type="constant" identity="PIPELINE_DEFAULT" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Default status pipeline used when a type has no custom design schema pipeline"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide fallback ordered status values"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string[]" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Static array of default progress statuses" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const PIPELINE_DEFAULT = ['not_started', 'in_progress', 'completed']
-
+// CIL[DOC-VECTOR type="context" content="purpose='Default status pipeline used when a type has no custom design schema pipeline'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:PIPELINE_DEFAULT:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:getPipeline:function" type="function" identity="getPipeline" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Resolve the status pipeline for a type record, falling back to the default"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return ordered pipeline from type design schema or default"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="typeRecord any" outputs="string[]" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Read typeRecord design schema pipeline or return PIPELINE_DEFAULT" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function getPipeline(typeRecord: any): string[] {
   return typeRecord?.design_schema?.pipeline ?? PIPELINE_DEFAULT
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve the status pipeline for a type record, falling back to the default'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:getPipeline:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:isValidTransition:function" type="function" identity="isValidTransition" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Validate that a status transition is forward or unchanged in the pipeline"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check if target status index is at least source status index"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="pipeline string[], from string, to string" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return true if either status is missing or target index is greater than or equal to source index" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function isValidTransition(pipeline: string[], from: string, to: string): boolean {
   const fromIdx = pipeline.indexOf(from)
   const toIdx = pipeline.indexOf(to)
   if (fromIdx === -1 || toIdx === -1) return true
   return toIdx >= fromIdx
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Validate that a status transition is forward or unchanged in the pipeline'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:isValidTransition:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:composeTitle:function" type="function" identity="composeTitle" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Build a title from item and person names"]
+// CIL[DOC-RESPONSIBILITY responsibility="Combine item title and person name with an em dash"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="itemTitle string|null, personName string|null" outputs="string|null" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return null if both empty, otherwise combine with em dash" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function composeTitle(itemTitle: string | null, personName: string | null): string | null {
   if (!itemTitle && !personName) return null
   if (!personName) return itemTitle
   if (!itemTitle) return personName
   return `${itemTitle} — ${personName}`
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Build a title from item and person names'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:composeTitle:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:composeDescription:function" type="function" identity="composeDescription" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Compose a human readable status description with optional score and attempts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format label, score, and attempt count into a dot separated string"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="status string, score number|null, attempts number|null" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Label status, append score and attempt count if present, join with middle dot" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function composeDescription(status: string, score: number | null, attempts: number | null): string {
   const parts: string[] = []
   const label = status === 'completed' ? 'Completed' : status === 'in_progress' ? 'In Progress' : 'Not Started'
@@ -68,21 +118,21 @@ function composeDescription(status: string, score: number | null, attempts: numb
   if (attempts !== null && attempts !== undefined && attempts > 0) parts.push(`${attempts} attempt${attempts === 1 ? '' : 's'}`)
   return parts.join(' · ')
 }
-// CIL[END chunk_id="itemprogress_constants_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_list_1783968140" type="function" identity="list" parent="none"]
-// CIL[DOC-MACRO purpose="List progress records with filtering and pagination"]
-// CIL[DOC-RESPONSIBILITY responsibility="Query and return paginated progress records"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Array of progress records" errors="DB errors" side_effects="DB read operations"]
-// CIL[DOC-MICRO logic_summary="Builds filtered query with person/item/status filters, applies pagination" 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/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Compose a human readable status description with optional score and attempts'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:composeDescription:function"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="List active item progress records with optional filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query item_progress table and return matching records"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="ctx RequestContext" outputs="array of item progress records" errors="throws on database error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Build a query, apply optional filters, and return data ordered by updated_at desc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const list = createHandler(async (ctx) => {
   const { person_id, item_id, item_ids, status, limit = '100', offset = '0' } = ctx.query || {}
 
@@ -102,21 +152,21 @@ export const list = createHandler(async (ctx) => {
   if (error) throw error
   return data
 })
-// CIL[END chunk_id="itemprogress_list_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_get_1783968140" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Get single progress record by ID"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve individual progress record"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Progress record" errors="ID required, not found, DB errors" side_effects="DB read operation"]
-// CIL[DOC-MICRO logic_summary="Queries by ID, returns full progress record" 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: 26. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 26. Total affected: 29."]
-// 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 item progress records with optional filters'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single item progress record by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the requested record or throw not found"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="ctx RequestContext" outputs="item progress record" errors="throws if id missing or record not found" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Read id from query, select single row, and return data" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const get = createHandler(async (ctx) => {
   const id = ctx.query?.id
   if (!id) throw new Error('Progress record ID is required')
@@ -130,21 +180,21 @@ export const get = createHandler(async (ctx) => {
   if (error || !data) throw new Error('Progress record not found')
   return data
 })
-// CIL[END chunk_id="itemprogress_get_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_upsert_1783968140" type="function" identity="upsert" parent="none"]
-// CIL[DOC-MACRO purpose="Upsert progress record with pipeline validation and auto-composition"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create or update progress with smart defaults"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Progress record" errors="Required fields missing, invalid transition, DB errors" side_effects="DB upsert, audit logging"]
-// CIL[DOC-MICRO logic_summary="Validates pipeline transitions, auto-composes metadata, handles timestamps" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 6. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 6. Total affected: 6."]
-// 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 item progress record by ID'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:upsert:constant" type="constant" identity="upsert" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Create or update an item progress record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve type, validate status transitions, enrich title/description, and upsert record"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="ctx RequestContext, body object" outputs="upserted record" errors="throws on missing required fields, invalid transition, or database error" side_effects="emits audit log"]
+// CIL[DOC-MICRO logic_summary="Resolve type id, load existing record, validate status transition, compute attempts and timestamps, fetch title and description if missing, build payload, upsert, and emit log" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const upsert = createHandler(async (ctx, body) => {
   const { person_id, item_id, type_id, type_slug, account_id, app_id, force } = body || {}
   let { status, score, data: dataPayload, title, description } = body || {}
@@ -239,21 +289,21 @@ export const upsert = createHandler(async (ctx, body) => {
 
   return result
 })
-// CIL[END chunk_id="itemprogress_upsert_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_update_1783968140" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Update progress record with pipeline validation and audit logging"]
-// CIL[DOC-RESPONSIBILITY responsibility="Modify progress with transition safety checks"]
-// CIL[DOC-CONTEXT module="item-progress" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Updated progress record" errors="ID required, not found, invalid transition, DB errors" side_effects="DB update, audit logging"]
-// CIL[DOC-MICRO logic_summary="Validates pipeline transitions, updates timestamps, logs changes" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, \."]
-// 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 or update an item progress record'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:upsert:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Patch an existing item progress record by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Apply status transition and merge data, then update row"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="ctx RequestContext, body object" outputs="updated record" errors="throws if id missing, record not found, or invalid transition" side_effects="emits audit log"]
+// CIL[DOC-MICRO logic_summary="Read id, load record, validate transition, merge data with timestamps, update, and emit 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
   if (!id) throw new Error('Progress record ID is required')
@@ -311,21 +361,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return result
 })
-// CIL[END chunk_id="itemprogress_update_1783968140"]
-// CIL[BEGIN chunk_id="itemprogress_handler_1783968140" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Route HTTP methods to appropriate progress handlers"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch CRUD requests to correct handler functions"]
-// CIL[DOC-CONTEXT module="item-progress" 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 method" errors="Unsupported method" side_effects="Delegates to handlers"]
-// CIL[DOC-MICRO logic_summary="Switch statement routes GET/POST/PATCH to appropriate 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='Patch an existing item progress record by ID'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:update:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/item-progress.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/item-progress.ts"]
+// CIL[DOC-MACRO purpose="Route method-based requests to list, get, upsert, or update"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch GET/POST/PATCH calls to the appropriate handler"]
+// CIL[DOC-CONTEXT module="item-progress" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="ctx RequestContext, body object" outputs="handler result" errors="throws for unsupported method" side_effects="calls downstream handlers"]
+// CIL[DOC-MICRO logic_summary="Read method and id from query, dispatch to list/get/upsert/update accordingly" 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 method = ctx.query?.method || 'GET'
   const id = ctx.query?.id
@@ -336,4 +386,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error(`Method ${method} not supported`)
 })
-// CIL[END chunk_id="itemprogress_handler_1783968140"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route method-based requests to list, get, upsert, or update'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/item-progress.ts:handler:constant"]

package/.framework/functions/kb.ts

@@ -1,7 +1,30 @@
+// CIL[BEGIN stable_id="~/.framework/functions/kb.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/kb.ts"]
+// CIL[DOC-MACRO purpose="Netlify function entry point for knowledge base operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import shared kb handlers and the admin-data update helper for the unified kb function"]
+// CIL[DOC-CONTEXT module="framework.functions.kb" layer="function" related_files=".framework/functions/_shared/kb.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-data.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, kbIngest/kbRevoke/kbReindex/kbSearch, and adminUpdate for the kb Netlify function" notable_decisions=[]]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
 import { createHandler } from './_shared/middleware'
-import { kbIngest, kbRevoke, kbReindex, kbSearch } from './_shared/kb'
-import { update as adminUpdate } from './admin-data'
+import { kbIngest, kbPublish, kbRevoke, kbReindex, kbSearch } from './_shared/kb'
+// CIL[DOC-VECTOR type="context" content="purpose='Netlify function entry point for knowledge base operations'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/kb.ts,.framework/functions/admin-data.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/kb.ts:module_header:module_header"]
 
+// CIL[BEGIN stable_id="~/.framework/functions/kb.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/kb.ts"]
+// CIL[DOC-MACRO purpose="Dispatch knowledge base actions from a Netlify function handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route the incoming action to the correct kb handler or publish workflow"]
+// CIL[DOC-CONTEXT module="framework.functions.kb" layer="function" related_files=".framework/functions/_shared/kb.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-data.ts,.framework/functions/kb.ts"]
+// CIL[DOC-CONTRACT inputs="ctx (RequestContext), body (object), action from query or body" outputs="kb handler result or { record, ingest } for publish" errors="unknown kb action, missing id for publish" side_effects="calls kbIngest/kbRevoke/kbReindex/kbSearch, delegates publish to admin-data then re-ingests"]
+// CIL[DOC-MICRO logic_summary="Determines the action from ctx.query.action defaulting to search, switches on ingest/revoke/reindex/search/publish, and for publish builds a synthetic PATCH context for admin-data before re-ingesting" notable_decisions=["Publishes by delegating to admin-data with a synthetic PATCH context", "Re-ingests the record after publishing to refresh the knowledge base"]']
+// 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?.action || 'search'
 
@@ -14,15 +37,16 @@ export const handler = createHandler(async (ctx, body) => {
       return await kbReindex(ctx, body)
     case 'search':
       return await kbSearch(ctx, body)
-    case 'publish': {
-      const { id } = body
-      if (!id) throw new Error('id is required')
-      const updateCtx = { ...ctx, query: { ...ctx.query, entity: 'items', id, method: 'PATCH' } }
-      const record = await adminUpdate(updateCtx, { status: 'published' })
-      const ingest = await kbIngest(ctx, { id })
-      return { record, ingest }
-    }
+    case 'publish':
+      return await kbPublish(ctx, body)
     default:
       throw new Error(`unknown kb action: ${action}`)
   }
 })
+// CIL[DOC-VECTOR type="context" content="purpose='Dispatch knowledge base actions from a Netlify function handler'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/kb.ts,.framework/functions/admin-data.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/kb.ts:handler:constant"]