spine-framework 0.3.125 → 0.3.126

package/.framework/src/types/types.ts

@@ -1,49 +1,23 @@
-/**
- * @module src/types/types
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Core TypeScript type definitions for the Spine frontend. These types
- * mirror the `design_schema` and API response shapes used across hooks,
- * components, and pages.
- *
- * **Type hierarchy:**
- * ```
- * DesignSchema
- *   ├── fields: Record<string, FieldDefinition>
- *   ├── views: Record<string, View>   ← ListView | DetailView
- *   ├── record_permissions
- *   └── functionality?: FunctionalityBindings
- * ItemType  ← row in v2.types table
- * Item       ← row in v2.items table
- * ```
- *
- * **`system` flag on `FieldDefinition`:** When `system: true`, the field
- * maps to a real DB column (e.g. `title`, `status`). When absent or false,
- * the field value lives in the `data` JSONB column.
- *
- * @seeAlso src/hooks/useSchemaRecord.ts (consumes FieldDefinition[])
- * @seeAlso src/hooks/useForm.ts (consumes FieldDefinition[] for validation)
- * @seeAlso src/hooks/useListSchema.ts (consumes DesignSchema + View)
- * @seeAlso functions/_shared/schema-utils.ts (server-side schema generation)
- */
-
-// ─── FIELD DEFINITIONS ───────────────────────────────────────────────────────────
-
-/**
- * Definition of a single field in a `design_schema`. Drives both UI rendering
- * and client-side validation in `useForm`.
- *
- * @prop data_type - Controls rendering widget and validation rules
- * @prop label - Human-readable display label
- * @prop required - Whether the field must be non-empty on save
- * @prop system - If true, maps to a top-level DB column; false/absent → `data` JSONB
- * @prop name - Injected at runtime by hooks; not stored in the schema itself
- * @prop validation - Type-specific constraint overrides
- * @prop options - Choice list for select/multiselect/radio fields
- * @prop permissions - Role-based read/write access map; absent = all roles allowed
- */
+
+// CIL[BEGIN chunk_id="types_fielddefinition_1783637731" type="interface" identity="FieldDefinition" parent="none"]
+// CIL[DOC-MACRO purpose="Define a single field in a design schema that drives UI rendering and client-side validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent field specifications including data type, validation rules, and role-based permissions"]
+// CIL[DOC-CONTEXT module="src/types/types" layer="frontend-hook" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Represent field specifications including data type, validation rules, and role-based permissions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. 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, .framework/src/pages/admin/IntegrationsPage.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 interface FieldDefinition {
   data_type: 'text' | 'textarea' | 'rich_text' | 'email' | 'phone' | 'url' | 
              'number' | 'currency' | 'range' | 'date' | 'datetime' | 'boolean' | 
@@ -51,10 +25,10 @@ export interface FieldDefinition {
              'file' | 'image' | 'json' | 'reference' | 'address'
   label: string
   required: boolean
-  system?: boolean // true = DB column, false/absent = custom field in .data
-  // Runtime identity — populated by SchemaFields when building field arrays from schema
+  system?: boolean 
+  
   name?: string
-  // UI hints — informational only, do not affect data contract or permissions
+  
   placeholder?: string
   description?: string
   rows?: number
@@ -80,23 +54,32 @@ export interface FieldDefinition {
     reference_kind?: string
     reference_type?: string
   }
-  // Type-specific constraint properties (move out of validation for clarity)
-  options?: (string | { value: string; label: string })[] // For select/multiselect/radio
+  
+  options?: (string | { value: string; label: string })[] 
   permissions?: {
-    [role: string]: string[] // Array of actions: ["read", "write"]
+    [role: string]: string[] 
   }
 }
+// CIL[END chunk_id="types_fielddefinition_1783637731"]
+// CIL[BEGIN chunk_id="types_viewfieldconfig_1783637731" type="interface" identity="ViewFieldConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Define per-field display/behaviour config within a view for UI rendering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent view-specific field overrides including widget type and interaction flags"]
+// CIL[DOC-CONTEXT module="src/types/types" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Represent view-specific field overrides including widget type and interaction flags" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, 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"]
+
+
+
 
-// ─── VIEW TYPES ─────────────────────────────────────────────────────────────────
 
-/**
- * Per-field display/behaviour config within a view. Stored as
- * `design_schema.views[viewSlug].fields[fieldName]`.
- *
- * @prop display_type - Override the default widget for this field in this view
- * @prop sortable - Whether the column header shows a sort toggle in list views
- * @prop searchable - Whether the field is included in free-text search
- */
 export interface ViewFieldConfig {
   display_type: 'input' | 'textarea' | 'rich_text' | 'select' | 'multiselect' | 
                  'radio' | 'checkbox' | 'switch' | 'date_picker' | 'datetime_picker' | 
@@ -106,17 +89,24 @@ export interface ViewFieldConfig {
   sortable?: boolean
   searchable?: boolean
 }
+// CIL[END chunk_id="types_viewfieldconfig_1783637731"]
+// CIL[BEGIN chunk_id="types_listview_1783637731" type="interface" identity="ListView" parent="none"]
+// CIL[DOC-MACRO purpose="Define a list view configuration for rendering data as table, card grid, or Kanban board"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent list display settings including fields, sorting, filters, stats, and grouping"]
+// CIL[DOC-CONTEXT module="src/types/types" layer="frontend-hook" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Represent list display settings including fields, sorting, filters, stats, and grouping" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.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"]
+
+
 
-/**
- * A list view definition. Rendered by `DataListPage` as a table, card grid,
- * or Kanban board depending on `display`.
- *
- * @prop fields - Ordered map of field name → `ViewFieldConfig`
- * @prop default_sort - Initial sort applied before user interaction
- * @prop filters - Field names to expose as filter controls
- * @prop stats - Summary stat cards shown above the list
- * @prop group_by - Field to use as board column grouping (`display: 'board'` only)
- */
 export interface ListView {
   type: 'list'
   display: 'table' | 'card' | 'board'
@@ -134,50 +124,99 @@ export interface ListView {
     color?: string
     filter?: Record<string, any>
   }>
-  group_by?: string // For board display
+  group_by?: string 
 }
+// CIL[END chunk_id="types_listview_1783637731"]
+// CIL[BEGIN chunk_id="types_detailviewsection_1783637731" type="interface" identity="DetailViewSection" parent="none"]
+// CIL[DOC-MACRO purpose="Define a single section within a DetailView that groups related fields"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent logical groupings of fields with optional titles for detail forms"]
+// CIL[DOC-CONTEXT module="src/types/types" layer="frontend-hook" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Represent logical groupings of fields with optional titles for detail forms" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/**
- * A single section within a `DetailView`. Groups related fields under
- * an optional title. Field permissions from the schema still apply —
- * there are no section-level permission overrides.
- */
 export interface DetailViewSection {
   title: string
   fields: Record<string, ViewFieldConfig>
-  // Note: No view-level permissions - field permissions from schema apply
+  
 }
+// CIL[END chunk_id="types_detailviewsection_1783637731"]
+// CIL[BEGIN chunk_id="types_detailview_1783637731" type="interface" identity="DetailView" parent="none"]
+// CIL[DOC-MACRO purpose="Define a detail view configuration for rendering sectioned record forms"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent detail form layout with multiple field sections"]
+// CIL[DOC-CONTEXT module="src/types/types" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Represent detail form layout with multiple field sections" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.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"]
+
+
 
-/**
- * A detail view definition. Rendered by `DataDetailPage` as a sectioned
- * record form.
- */
 export interface DetailView {
   type: 'detail'
   label: string
   sections: DetailViewSection[]
 }
+// CIL[END chunk_id="types_detailview_1783637731"]
+// CIL[BEGIN chunk_id="types_view_1783637731" type="type" identity="View" parent="none"]
+// CIL[DOC-MACRO purpose="Define discriminated union of all supported view types for schema-driven UI"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent all possible view configurations (list and detail)"]
+// CIL[DOC-CONTEXT module="View" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements View" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Discriminated union of all supported view types. */
 export type View = ListView | DetailView
+// CIL[END chunk_id="types_view_1783637731"]
+// CIL[BEGIN chunk_id="types_functionalitybindings_1783637731" type="interface" identity="FunctionalityBindings" parent="none"]
+// CIL[DOC-MACRO purpose="Define optional automation and integration bindings attached to a DesignSchema"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent trigger conditions and targets for pipelines, AI agents, embeddings, integrations, and constraints"]
+// CIL[DOC-CONTEXT module="FunctionalityBindings" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements FunctionalityBindings" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
+
 
-// ─── FUNCTIONALITY BINDINGS ──────────────────────────────────────────────────────────
-
-/**
- * Optional automation and integration bindings attached to a `DesignSchema`.
- * Each array entry describes a trigger condition and the target pipeline,
- * agent, embedding, integration, or constraint.
- *
- * These bindings are evaluated by API handlers and the system cron — not
- * by the frontend. They are included here as a type contract so the frontend
- * can read and display binding metadata without making blind `any` casts.
- */
 export interface FunctionalityBindings {
   pipelines?: Array<{
     pipeline_id: string
     trigger: 'manual' | 'on_create' | 'on_update' | 'on_field_change' | 'on_delete' | 'scheduled'
-    field?: string // For on_field_change
-    condition?: string // Expression string
+    field?: string 
+    condition?: string 
     roles: string[]
   }>
   ai_agents?: Array<{
@@ -205,45 +244,61 @@ export interface FunctionalityBindings {
   }>
   constraints?: Array<{
     type: 'unique' | 'conditional_required' | 'immutable'
-    fields?: string[] // For unique
-    field?: string // For conditional_required and immutable
-    condition?: string // For conditional_required
+    fields?: string[] 
+    field?: string 
+    condition?: string 
     message: string
-    after?: 'create' | 'update' // For immutable
+    after?: 'create' | 'update' 
   }>
 }
+// CIL[END chunk_id="types_functionalitybindings_1783637731"]
+// CIL[BEGIN chunk_id="types_designschema_1783637731" type="interface" identity="DesignSchema" parent="none"]
+// CIL[DOC-MACRO purpose="Define the complete design schema for a types record stored as JSONB in the database"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent the full schema definition including fields, views, permissions, and functionality bindings"]
+// CIL[DOC-CONTEXT module="DesignSchema" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements DesignSchema" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
+
 
-// ─── DESIGN SCHEMA ────────────────────────────────────────────────────────────────
-
-/**
- * The complete design schema for a `types` record. Stored as a JSONB column
- * (`design_schema`) and stamp-copied onto records at create time.
- *
- * @prop record_permissions - Role → allowed CRUD actions map for the entire record
- * @prop fields - All field definitions keyed by field name
- * @prop views - Named view definitions (`list`, `detail`, etc.)
- * @prop functionality - Optional automation bindings (pipelines, agents, etc.)
- */
 export interface DesignSchema {
   record_permissions: {
-    [role: string]: string[] // Array of actions: ["create", "read", "update", "delete"]
+    [role: string]: string[] 
   }
   fields: Record<string, FieldDefinition>
   views: Record<string, View>
   functionality?: FunctionalityBindings
 }
+// CIL[END chunk_id="types_designschema_1783637731"]
+// CIL[BEGIN chunk_id="types_itemtype_1783637731" type="interface" identity="ItemType" parent="none"]
+// CIL[DOC-MACRO purpose="Define a type record from the v2.types table with complete schema and validation configuration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent a configurable data type with design schema, validation rules, and metadata"]
+// CIL[DOC-CONTEXT module="ItemType" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements ItemType" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
+
 
-// ─── RECORD SHAPES ─────────────────────────────────────────────────────────────────
-
-/**
- * A row from the `v2.types` table. Represents a type definition (item type,
- * account type, person type, etc.) including its full `design_schema`.
- *
- * @prop kind - Discriminator: `'item'` | `'account'` | `'person'` | etc.
- * @prop design_schema - Full schema defining fields, views, and functionality
- * @prop validation_schema - Auto-generated JSON Schema used for server-side validation
- * @prop ownership - `'pack'` | `'tenant'` (pack-ownership tracking)
- */
 export interface ItemType {
   id: string
   name: string
@@ -257,7 +312,7 @@ export interface ItemType {
     fields: Record<string, {
       data_type: string
       required?: boolean
-      [key: string]: any // Type-specific validation properties
+      [key: string]: any 
     }>
   }
   ownership: string
@@ -267,15 +322,24 @@ export interface ItemType {
   created_at: string
   updated_at: string
 }
+// CIL[END chunk_id="types_itemtype_1783637731"]
+// CIL[BEGIN chunk_id="types_item_1783637731" type="interface" identity="Item" parent="none"]
+// CIL[DOC-MACRO purpose="Define a data item record from the v2.items table representing an instance of a type"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent a concrete data record with type reference, data payload, and metadata"]
+// CIL[DOC-CONTEXT module="Item" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements Item" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/**
- * A row from the `v2.items` table. The `data` JSONB column holds all
- * custom field values; system fields (`title`, `status`, etc.) are top-level.
- *
- * @prop design_schema - Stamp of the type's schema at create time (for resilience
- *   to schema changes; may be stale relative to `types` table)
- * @prop validation_schema - Stamp of the validation schema at create time
- */
 export interface Item {
   id: string
   item_type_id: string
@@ -290,19 +354,51 @@ export interface Item {
   created_by?: string
   account_id: string
   app_id?: string
-  design_schema?: Record<string, any> // Schema snapshot at creation time
-  validation_schema?: Record<string, any> // Validation schema snapshot at creation time
+  design_schema?: Record<string, any> 
+  validation_schema?: Record<string, any> 
 }
+// CIL[END chunk_id="types_item_1783637731"]
+// CIL[BEGIN chunk_id="types_validationerror_1783637731" type="interface" identity="ValidationError" parent="none"]
+// CIL[DOC-MACRO purpose="Define a validation error for form field validation feedback"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent field-specific validation errors with messages"]
+// CIL[DOC-CONTEXT module="ValidationError" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements ValidationError" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
 
-// ─── FORM & QUERY TYPES ───────────────────────────────────────────────────────────
 
-/** A field-level validation failure from `useForm` or server-side validation. */
 export interface ValidationError {
   field: string
   message: string
 }
+// CIL[END chunk_id="types_validationerror_1783637731"]
+// CIL[BEGIN chunk_id="types_formstate_1783637731" type="interface" identity="FormState" parent="none"]
+// CIL[DOC-MACRO purpose="Define form state management for reactive forms with data, errors, and submission status"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent complete form state including data, validation errors, touched fields, and submission status"]
+// CIL[DOC-CONTEXT module="FormState" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements FormState" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Snapshot of form state — used as a shared type between `useForm` and form components. */
 export interface FormState {
   data: Record<string, any>
   errors: Record<string, string>
@@ -310,35 +406,115 @@ export interface FormState {
   isSubmitting: boolean
   isValid: boolean
 }
+// CIL[END chunk_id="types_formstate_1783637731"]
+// CIL[BEGIN chunk_id="types_paginationparams_1783637731" type="interface" identity="PaginationParams" parent="none"]
+// CIL[DOC-MACRO purpose="Define pagination parameters for list queries with limit, offset, and page options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent pagination controls for data list APIs"]
+// CIL[DOC-CONTEXT module="PaginationParams" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements PaginationParams" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Pagination query parameters for list endpoints. */
 export interface PaginationParams {
   limit?: number
   offset?: number
   page?: number
 }
+// CIL[END chunk_id="types_paginationparams_1783637731"]
+// CIL[BEGIN chunk_id="types_sortparams_1783637731" type="interface" identity="SortParams" parent="none"]
+// CIL[DOC-MACRO purpose="Define sorting parameters for list queries with field and direction"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent sorting controls for ordered data display"]
+// CIL[DOC-CONTEXT module="SortParams" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements SortParams" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Sort order specification for list endpoints. */
 export interface SortParams {
   field: string
   direction: 'asc' | 'desc'
 }
+// CIL[END chunk_id="types_sortparams_1783637731"]
+// CIL[BEGIN chunk_id="types_filterparams_1783637731" type="interface" identity="FilterParams" parent="none"]
+// CIL[DOC-MACRO purpose="Define filter parameters for list queries with flexible key-value filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent filter controls for data list APIs"]
+// CIL[DOC-CONTEXT module="FilterParams" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements FilterParams" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Arbitrary key→value filter map for list endpoints. */
 export interface FilterParams {
   [key: string]: any
 }
+// CIL[END chunk_id="types_filterparams_1783637731"]
+// CIL[BEGIN chunk_id="types_searchparams_1783637731" type="interface" identity="SearchParams" parent="none"]
+// CIL[DOC-MACRO purpose="Define comprehensive search parameters combining pagination, search, sort, and filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent complete search controls for data list APIs"]
+// CIL[DOC-CONTEXT module="SearchParams" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements SearchParams" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** Combined search, sort, filter, and pagination params for list queries. */
 export interface SearchParams extends PaginationParams {
   search?: string
   sort?: SortParams
   filters?: FilterParams
 }
+// CIL[END chunk_id="types_searchparams_1783637731"]
+// CIL[BEGIN chunk_id="types_entitycolumn_1783637731" type="interface" identity="EntityColumn" parent="none"]
+// CIL[DOC-MACRO purpose="Define column configuration for entity list display with sorting and display options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent column metadata for data table rendering"]
+// CIL[DOC-CONTEXT module="EntityColumn" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements EntityColumn" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
 
-// ─── UI DISPLAY TYPES ────────────────────────────────────────────────────────────────
 
-/** A rendered column descriptor for list/table UI components. */
 export interface EntityColumn {
   key: string
   label: string
@@ -348,8 +524,24 @@ export interface EntityColumn {
   badgeColors?: Record<string, string>
   maxLength?: number
 }
+// CIL[END chunk_id="types_entitycolumn_1783637731"]
+// CIL[BEGIN chunk_id="types_entitystat_1783637731" type="interface" identity="EntityStat" parent="none"]
+// CIL[DOC-MACRO purpose="Define stat card configuration for entity list summaries with counts and filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent summary statistics display for data lists"]
+// CIL[DOC-CONTEXT module="EntityStat" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements EntityStat" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** A stat card shown above entity list pages (count or filtered count). */
 export interface EntityStat {
   title: string
   type: 'count' | 'filter_count'
@@ -357,27 +549,50 @@ export interface EntityStat {
   color: string
   filter?: Record<string, any>
 }
+// CIL[END chunk_id="types_entitystat_1783637731"]
+// CIL[BEGIN chunk_id="types_entityfilter_1783637731" type="interface" identity="EntityFilter" parent="none"]
+// CIL[DOC-MACRO purpose="Define filter configuration for entity lists with search, enum, and boolean filter types"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent filter controls for data list filtering"]
+// CIL[DOC-CONTEXT module="EntityFilter" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements EntityFilter" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
 
-/** A filter control definition for entity list pages. */
 export interface EntityFilter {
   key: string
   label: string
   type: 'search' | 'enum' | 'boolean'
   options?: string[]
 }
+// CIL[END chunk_id="types_entityfilter_1783637731"]
+// CIL[BEGIN chunk_id="types_itemprogress_1783637731" type="interface" identity="ItemProgress" parent="none"]
+// CIL[DOC-MACRO purpose="Define progress tracking for items with status, scoring, and detailed progress data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent user progress through items with completion status and metadata"]
+// CIL[DOC-CONTEXT module="ItemProgress" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements ItemProgress" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+
+
+
 
-// ─── ITEM PROGRESS ───────────────────────────────────────────────────────────
-
-/**
- * A per-person, per-item progress record. Tracks pipeline status, score, and
- * arbitrary interaction data for courses, onboarding, tasks, and quizzes.
- *
- * `title` is auto-composed as "<item title> — <person name>".
- * `description` is auto-composed as "Completed · score 85 · 2 attempts".
- * `data` holds extensible fields: attempts, time_spent, last_position, etc.
- *
- * INVARIANT: (person_id, item_id) is unique — state, not a log.
- */
 export interface ItemProgress {
   id: string
   type_id: string
@@ -405,3 +620,4 @@ export interface ItemProgress {
   created_at: string
   updated_at: string
 }
+// CIL[END chunk_id="types_itemprogress_1783637731"]