spine-framework 0.3.124 → 0.3.126

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

@@ -1,26 +1,45 @@
-/**
- * @module item-progress
- * @audience both
- * @layer api-handler
- * @stability stable
- *
- * CRUD + upsert API for the `item_progress` table. Tracks per-person, per-item
- * progress state for courses, tasks, onboarding, and any item-based pipeline.
- *
- * Routed by: GET/POST/PATCH /.netlify/functions/item-progress
- *
- * INVARIANT: (person_id, item_id) is unique — state, not a log.
- * INVARIANT: status transitions are forward-only unless force: true.
- * INVARIANT: score must be 0–100 or null.
- */
 
+
+
+
+
+
+// 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'
-
-// ─── HELPERS ──────────────────────────────────────────────────────────────────
-
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const PIPELINE_DEFAULT = ['not_started', 'in_progress', 'completed']
 
 function getPipeline(typeRecord: any): string[] {
@@ -49,13 +68,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(' · ')
 }
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-/**
- * Lists progress records for the authenticated principal.
- * Query params: person_id, item_id, item_ids (comma-sep), status, limit, offset
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const list = createHandler(async (ctx) => {
   const { person_id, item_id, item_ids, status, limit = '100', offset = '0' } = ctx.query || {}
 
@@ -75,10 +102,21 @@ export const list = createHandler(async (ctx) => {
   if (error) throw error
   return data
 })
-
-/**
- * Gets a single item_progress record by id.
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const get = createHandler(async (ctx) => {
   const id = ctx.query?.id
   if (!id) throw new Error('Progress record ID is required')
@@ -92,20 +130,25 @@ export const get = createHandler(async (ctx) => {
   if (error || !data) throw new Error('Progress record not found')
   return data
 })
-
-/**
- * Upserts a progress record for (person_id, item_id).
- * Auto-composes title and description. Enforces pipeline transitions.
- * Sets started_at / completed_at timestamps in data. Increments attempts.
- *
- * Body: person_id*, item_id*, type_id*, account_id*, status, score, data,
- *       title, description, app_id, force (bypass direction check)
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 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 || {}
 
-  // Resolve type_id from type_slug if provided; otherwise require it directly
   let resolvedTypeId = type_id
   if (!resolvedTypeId && type_slug) {
     resolvedTypeId = await resolveTypeId('item_progress', type_slug)
@@ -115,7 +158,6 @@ export const upsert = createHandler(async (ctx, body) => {
     throw new Error('person_id, item_id, type_id (or type_slug), and account_id are required')
   }
 
-  // Fetch type record for pipeline
   const { data: typeRecord } = await adminDb
     .from('types')
     .select('design_schema')
@@ -124,7 +166,6 @@ export const upsert = createHandler(async (ctx, body) => {
 
   const pipeline = getPipeline(typeRecord)
 
-  // Fetch existing record (if any)
   const { data: existing } = await ctx.db
     .from('item_progress')
     .select('*')
@@ -135,12 +176,10 @@ export const upsert = createHandler(async (ctx, body) => {
   const currentStatus = existing?.status ?? 'not_started'
   const targetStatus  = status ?? currentStatus
 
-  // Validate pipeline transition
   if (status && existing && !force && !isValidTransition(pipeline, currentStatus, targetStatus)) {
     throw new Error(`Invalid status transition: ${currentStatus} → ${targetStatus}. Use force: true to override.`)
   }
 
-  // Merge data payload with timestamps and attempts
   const now = new Date().toISOString()
   const existingData = existing?.data ?? {}
   const attempts = (existingData.attempts ?? 0) + (status && status !== currentStatus ? 1 : 0)
@@ -152,7 +191,6 @@ export const upsert = createHandler(async (ctx, body) => {
   if (targetStatus === 'in_progress' && !existingData.started_at) mergedData.started_at = now
   if (targetStatus === 'completed' && !existingData.completed_at) mergedData.completed_at = now
 
-  // Auto-compose title/description if not provided
   if (!title) {
     const [{ data: itemRow }, { data: personRow }] = await Promise.all([
       adminDb.from('items').select('title').eq('id', item_id).single(),
@@ -201,12 +239,21 @@ export const upsert = createHandler(async (ctx, body) => {
 
   return result
 })
-
-/**
- * Partially updates an existing item_progress record.
- * Body: id (required), plus any updatable fields.
- * Enforces forward-only status transitions unless force: true.
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   if (!id) throw new Error('Progress record ID is required')
@@ -264,9 +311,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return result
 })
-
-// ─── ROUTER ──────────────────────────────────────────────────────────────────
-
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx, body) => {
   const method = ctx.query?.method || 'GET'
   const id = ctx.query?.id
@@ -277,3 +336,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error(`Method ${method} not supported`)
 })
+// CIL[END chunk_id="itemprogress_handler_1783968140"]

package/.framework/functions/kb.ts

@@ -0,0 +1,28 @@
+import { createHandler } from './_shared/middleware'
+import { kbIngest, kbRevoke, kbReindex, kbSearch } from './_shared/kb'
+import { update as adminUpdate } from './admin-data'
+
+export const handler = createHandler(async (ctx, body) => {
+  const action = ctx.query?.action || 'search'
+
+  switch (action) {
+    case 'ingest':
+      return await kbIngest(ctx, body)
+    case 'revoke':
+      return await kbRevoke(ctx, body)
+    case 'reindex':
+      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 }
+    }
+    default:
+      throw new Error(`unknown kb action: ${action}`)
+  }
+})