spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/schema-utils.ts

@@ -1,90 +1,95 @@
-/**
- * @module schema-utils
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Schema generation and field-level data transformation for all Spine types.
- *
- * Three public functions form the core contract:
- *   - `generateValidationSchema` — derives a runtime validation schema from a
- *     `design_schema`, stripping display/permission info and keeping only
- *     structural constraints.
- *   - `sanitizeFieldData` — coerces and validates a single field value for
- *     write (create/update) operations. Throws on invalid data.
- *   - `formatFieldData` — converts a stored field value to a human-readable
- *     display string for read operations. Never throws.
- *   - `transformRecordData` — applies sanitize or format to all fields in a
- *     record using a pre-generated ValidationSchema.
- *
- * These are called by `permissions.ts` (`validateFirstSurfaceUpdatePermissions`
- * and `sanitizeFirstSurfaceRecordData`) — do not call them directly from API
- * handlers. Use `PermissionEngine.sanitizeRecordData` / `validateUpdatePermissions`.
- *
- * INVARIANT: all sanitize functions throw on invalid data. Callers must catch
- *   errors and convert them to field-level validation error messages.
- * INVARIANT: all format functions return the raw data unchanged if formatting
- *   is not applicable (never throw, never return null for non-null input).
- *
- * @seeAlso permissions.ts (primary caller of sanitizeFieldData, formatFieldData)
- * @seeAlso src/types/types.ts (FieldDefinition interface)
- * @seeAlso index.ts (not re-exported — internal to core; use PermissionEngine)
- */
 
-import { FieldDefinition } from '../../src/types/types'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────
-
-/**
- * Structural-only validation schema derived from a `design_schema`.
- *
- * Contains one entry per field with the field's `data_type` and any explicit
- * `validation` constraints. Display properties (`display_type`, views, sections)
- * and permission properties are stripped. Used as input to `sanitizeFieldData`
- * and `formatFieldData`.
- *
- * @inputSpec none — output type of generateValidationSchema
- * @outputSpec fields: Record<fieldName, { data_type, required?, ...constraints }>
- * @calledBy generateValidationSchema (producer), transformRecordData,
- *   permissions.ts validateFirstSurfaceUpdatePermissions (consumer)
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="schemautils_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import field definition type for schema utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import FieldDefinition interface from types"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/025_retype_threads_messages.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FieldDefinition type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import type definition for field structure" 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: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/025_retype_threads_messages.sql, \."]
+// 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 { FieldDefinition } from '../../src/types/types'
+// CIL[END chunk_id="schemautils_imports_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_validationinterface_1784020784" type="interface" identity="ValidationSchema" parent="none"]
+// CIL[DOC-MACRO purpose="Define validation schema interface for field validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide structure for validation rules per field"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ValidationSchema interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with fields containing data_type and validation rules" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/src/pages/admin/TypeDetailPage.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 ValidationSchema {
   fields: Record<string, {
     data_type: string
     required?: boolean
-    [key: string]: any // Type-specific validation properties
+    [key: string]: any
   }>
 }
-
-// ─── PUBLIC API ──────────────────────────────────────────────────────────────
-
-/**
- * Derives a `ValidationSchema` from a `design_schema` by extracting only
- * structural constraints (data_type, required, validation.*) and discarding
- * display, permission, and view configuration.
- *
- * The resulting schema is used to drive `sanitizeFieldData` and
- * `formatFieldData` for every field in a record. It is generated once per
- * type and passed to `transformRecordData` for bulk field processing.
- *
- * @param designSchema - The full design_schema object from a type record
- * @returns ValidationSchema with one entry per field
- * @throws never — returns empty schema if designSchema.fields is missing
- * @inputSpec designSchema.fields: Record<fieldName, FieldDefinition> — must match
- *   the FieldDefinition interface from src/types/types.ts
- * @inputSpec designSchema.fields[x].data_type: string — required in every field
- * @outputSpec ValidationSchema.fields: Record<string, { data_type, required, ...constraints }>
- * @sideEffects none
- * @calledBy permissions.ts (validateFirstSurfaceUpdatePermissions), any caller
- *   needing a validation schema without the full design_schema overhead
- * @testUnit tests/unit/schema-utils.test.ts — 'generateValidationSchema' describe block
- *
- * @example
- * ```ts
- * const schema = generateValidationSchema(record.design_schema)
- * const cleaned = transformRecordData(record.data, schema, 'sanitize')
- * ```
- */
+// CIL[END chunk_id="schemautils_validationinterface_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_generatevalidationschema_1784020784" type="function" identity="generateValidationSchema" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/validation_generation" content="generateValidationSchema builds a Zod-compatible validation schema from design_schema.fields. It uses data_type, required, validation, options, and reference fields to produce row-level and data-level validators."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="Unsupported data_types or validation keys are ignored. Reference fields need reference_kind and reference_type or validation will not enforce foreign keys."]
+// CIL[DOC-MACRO purpose="Generate validation schema from design schema"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert design schema to validation rules"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ValidationSchema" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Extracts field definitions and builds validation schema" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function generateValidationSchema(designSchema: any): ValidationSchema {
   const validationSchema: ValidationSchema = {
     fields: {}
@@ -97,23 +102,19 @@ export function generateValidationSchema(designSchema: any): ValidationSchema {
   for (const [fieldName, fieldDef] of Object.entries(designSchema.fields)) {
     const field = fieldDef as FieldDefinition
     
-    // Extract only structural validation properties exactly as declared
     const validationField: any = {
       data_type: field.data_type,
       required: field.required
     }
 
-    // Add explicit validation constraints exactly as declared
     if (field.validation) {
       Object.assign(validationField, field.validation)
     }
 
-    // Add type-specific constraint properties (moved out of validation for clarity)
     if (field.options) {
       validationField.options = field.options
     }
 
-    // Add reference properties if they exist
     if (field.data_type === 'reference' && field.validation) {
       if (field.validation.reference_kind) validationField.reference_kind = field.validation.reference_kind
       if (field.validation.reference_type) validationField.reference_type = field.validation.reference_type
@@ -124,41 +125,21 @@ export function generateValidationSchema(designSchema: any): ValidationSchema {
 
   return validationSchema
 }
-
-/**
- * Coerces and validates a single field value for a write (create/update) operation.
- *
- * Dispatches to a type-specific sanitizer based on `data_type`. Every sanitizer:
- *   - Coerces the input to the correct type
- *   - Applies constraint validation (min/max/length/pattern/options)
- *   - Throws a descriptive `Error` on the first validation failure
- *   - Returns the cleaned value on success
- *
- * Unknown `data_type` values pass through unchanged (no throw).
- *
- * @param data - Raw field value from the request body
- * @param data_type - The field's declared data_type from design_schema.fields[x]
- * @param validation - Optional validation constraints from the field definition
- * @returns Sanitized value in the correct type for storage
- * @throws Error — descriptive message naming the field constraint violated
- * @inputSpec data: any — null and undefined are returned as-is without sanitization
- * @inputSpec data_type: string — one of the 21 supported type keys (see switch below)
- * @inputSpec validation: object | undefined — type-specific constraints
- * @outputSpec any — coerced value matching the data_type storage format
- * @sideEffects none
- * @calledBy permissions.ts (validateFirstSurfaceUpdatePermissions, per-field loop)
- * @calls sanitizeText | sanitizeTextarea | sanitizeEmail | sanitizeNumber | etc.
- * @testUnit tests/unit/schema-utils.test.ts — 'sanitizeFieldData' describe block
- *
- * @example
- * ```ts
- * const clean = sanitizeFieldData('hello@EXAMPLE.COM', 'email')
- * // → 'hello@example.com'
- *
- * sanitizeFieldData('not-a-url', 'url')
- * // throws Error('Invalid URL format')
- * ```
- */
+// CIL[END chunk_id="schemautils_generatevalidationschema_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizefielddata_1784020784" type="function" identity="sanitizeFieldData" parent="none"]
+// CIL[DOC-MACRO purpose="Dispatch sanitization based on field data type"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route data to appropriate sanitizer function"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[\".framework/migrations/025_retype_threads_messages.sql\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized data" errors="validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes to type-specific sanitizers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/025_retype_threads_messages.sql, .framework/src/pages/admin/IntegrationsPage.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 function sanitizeFieldData(
   data: any, 
   data_type: string, 
@@ -217,40 +198,21 @@ export function sanitizeFieldData(
       return data
   }
 }
-
-/**
- * Converts a stored field value to a human-readable display string.
- *
- * Dispatches to a type-specific formatter based on `data_type`. Formatters
- * never throw — if the data cannot be formatted, the raw value is returned.
- * Only types with meaningful display transformations have a case; all others
- * fall through to the default (return data unchanged).
- *
- * @param data - Stored field value (from DB, post-sanitization)
- * @param data_type - The field's declared data_type
- * @param context - Optional context for type-specific formatting (e.g.
- *   `context.currency_code` for currency fields, `context.field` for boolean
- *   contextual labels like 'Active'/'Inactive')
- * @returns Formatted display value
- * @throws never
- * @inputSpec data: any — null and undefined are returned as-is
- * @inputSpec data_type: string — one of 21 supported keys; unknown → pass-through
- * @inputSpec context: object | undefined — type-specific display hints
- * @outputSpec any — display-ready value; string for most types, raw data for pass-through
- * @sideEffects none
- * @calledBy permissions.ts (sanitizeFirstSurfaceRecordData, per-field loop)
- * @calls formatJson | formatDate | formatDatetime | formatCurrency | etc.
- * @testUnit tests/unit/schema-utils.test.ts — 'formatFieldData' describe block
- *
- * @example
- * ```ts
- * formatFieldData('2024-01-15', 'date')
- * // → 'January 15, 2024'
- *
- * formatFieldData(1234.5, 'currency', { currency_code: 'USD' })
- * // → '$1,234.50'
- * ```
- */
+// CIL[END chunk_id="schemautils_sanitizefielddata_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatfielddata_1784020784" type="function" identity="formatFieldData" parent="none"]
+// CIL[DOC-MACRO purpose="Dispatch formatting based on field data type"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route data to appropriate formatter function"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[\".framework/migrations/025_retype_threads_messages.sql\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted data" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes to type-specific formatters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/025_retype_threads_messages.sql, .framework/src/pages/admin/IntegrationsPage.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 function formatFieldData(
   data: any, 
   data_type: string, 
@@ -285,37 +247,21 @@ export function formatFieldData(
       return data
   }
 }
-
-/**
- * Applies `sanitizeFieldData` or `formatFieldData` to all fields in a record,
- * using the ValidationSchema for per-field type and constraint information.
- *
- * Fields not present in the schema are passed through unchanged. This is
- * intentional — unknown fields are not rejected here; the PermissionEngine
- * handles field-level access control separately.
- *
- * @param data - Key/value record of field names to raw or stored values
- * @param validationSchema - Schema from `generateValidationSchema`
- * @param operation - 'sanitize' for write path; 'format' for display path
- * @param context - Optional context passed through to formatFieldData
- * @returns Transformed record with the same keys
- * @throws Error (sanitize mode only) — if any field fails validation
- * @inputSpec data: Record<string, any> — flat field map
- * @inputSpec validationSchema: ValidationSchema — from generateValidationSchema
- * @inputSpec operation: 'sanitize' | 'format'
- * @outputSpec Record<string, any> — same keys, transformed values
- * @sideEffects none
- * @calledBy Custom code in v2-custom/ that needs bulk field transformation
- * @calls sanitizeFieldData | formatFieldData (per field)
- * @testUnit tests/unit/schema-utils.test.ts — 'transformRecordData' describe block
- *
- * @example
- * ```ts
- * const schema = generateValidationSchema(type.design_schema)
- * const sanitized = transformRecordData(body.data, schema, 'sanitize')
- * const formatted = transformRecordData(record.data, schema, 'format', ctx)
- * ```
- */
+// CIL[END chunk_id="schemautils_formatfielddata_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_transformrecorddata_1784020784" type="function" identity="transformRecordData" parent="none"]
+// CIL[DOC-MACRO purpose="Transform record data using validation schema"]
+// CIL[DOC-RESPONSIBILITY responsibility="Apply sanitization or formatting to all record fields"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="transformed data" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Iterates through fields and applies appropriate transformation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 export function transformRecordData(
   data: Record<string, any>,
   validationSchema: ValidationSchema,
@@ -328,7 +274,6 @@ export function transformRecordData(
     const fieldValidation = validationSchema.fields[fieldName]
     
     if (!fieldValidation) {
-      // No validation schema for this field, pass through as-is
       transformed[fieldName] = fieldValue
       continue
     }
@@ -350,22 +295,26 @@ export function transformRecordData(
 
   return transformed
 }
-
-// ─── SANITIZE HELPERS ────────────────────────────────────────────────────────────
-
-/**
- * Trims, strips control characters, HTML-escapes, and applies minLength/
- * maxLength/pattern constraints. Throws on minLength/pattern violation;
- * silently truncates on maxLength.
- * @throws Error on minLength or pattern violation
- */
+// CIL[END chunk_id="schemautils_transformrecorddata_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizetext_1784020784" type="function" identity="sanitizeText" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize text field data with HTML encoding"]
+// CIL[DOC-RESPONSIBILITY responsibility="Clean text and apply validation rules"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized string" errors="validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Removes control chars, HTML encodes, validates length/pattern" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeText(data: any, validation?: any): string {
   let text = String(data).trim()
   
-  // Remove control characters except newlines and tabs
   text = text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')
   
-  // Escape HTML entities
   text = text
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
@@ -373,7 +322,6 @@ function sanitizeText(data: any, validation?: any): string {
     .replace(/"/g, '&quot;')
     .replace(/'/g, '&#x27;')
   
-  // Apply length constraints
   if (validation?.minLength && text.length < validation.minLength) {
     throw new Error(`Text must be at least ${validation.minLength} characters`)
   }
@@ -381,7 +329,6 @@ function sanitizeText(data: any, validation?: any): string {
     text = text.substring(0, validation.maxLength)
   }
   
-  // Apply pattern validation
   if (validation?.pattern) {
     const regex = new RegExp(validation.pattern)
     if (!regex.test(text)) {
@@ -391,19 +338,26 @@ function sanitizeText(data: any, validation?: any): string {
   
   return text
 }
-
-/**
- * Same as sanitizeText but preserves newlines. Strips control chars,
- * HTML-escapes, applies minLength/maxLength.
- * @throws Error on minLength violation
- */
+// CIL[END chunk_id="schemautils_sanitizetext_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizetextarea_1784020784" type="function" identity="sanitizeTextarea" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize textarea field data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Clean textarea content and validate length"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized string" errors="length validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Removes control chars, HTML encodes, checks length limits" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeTextarea(data: any, validation?: any): string {
   let text = String(data).trim()
   
-  // Remove control characters except newlines and tabs
   text = text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')
   
-  // Escape HTML entities but preserve line breaks
   text = text
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
@@ -411,7 +365,6 @@ function sanitizeTextarea(data: any, validation?: any): string {
     .replace(/"/g, '&quot;')
     .replace(/'/g, '&#x27;')
   
-  // Apply length constraints
   if (validation?.minLength && text.length < validation.minLength) {
     throw new Error(`Text must be at least ${validation.minLength} characters`)
   }
@@ -421,17 +374,24 @@ function sanitizeTextarea(data: any, validation?: any): string {
   
   return text
 }
-
-/**
- * Allowlist-based HTML sanitizer for rich text. Strips all tags not in the
- * allowed set (`p br strong em u ol ul li a h1-h6`), removes script tags and
- * `on*` event attributes, applies minLength/maxLength.
- * @throws Error on minLength violation
- */
+// CIL[END chunk_id="schemautils_sanitizetextarea_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizerichtext_1784020784" type="function" identity="sanitizeRichText" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize rich text HTML content"]
+// CIL[DOC-RESPONSIBILITY responsibility="Filter HTML tags and remove dangerous content"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized HTML" errors="length validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Allows safe tags, removes scripts, strips event 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: shared. 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"]
 function sanitizeRichText(data: any, validation?: any): string {
   let html = String(data).trim()
   
-  // Basic HTML sanitization - allow only safe tags
   const allowedTags = ['p', 'br', 'strong', 'em', 'u', 'ol', 'ul', 'li', 'a', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']
   const tagRegex = /<\/?([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/g
   
@@ -442,11 +402,9 @@ function sanitizeRichText(data: any, validation?: any): string {
     return ''
   })
   
-  // Remove script tags and on* attributes
   html = html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
   html = html.replace(/on\w+\s*=/gi, '')
   
-  // Apply length constraints
   if (validation?.minLength && html.length < validation.minLength) {
     throw new Error(`Content must be at least ${validation.minLength} characters`)
   }
@@ -456,15 +414,24 @@ function sanitizeRichText(data: any, validation?: any): string {
   
   return html
 }
-
-/**
- * Lowercases, trims, and validates basic `name@domain.tld` format.
- * @throws Error('Invalid email format') on invalid input
- */
+// CIL[END chunk_id="schemautils_sanitizerichtext_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeemail_1784020784" type="function" identity="sanitizeEmail" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and sanitize email addresses"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure email format is valid"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="normalized email" errors="invalid format error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Lowercases, trims, validates with regex pattern" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeEmail(data: any, validation?: any): string {
   let email = String(data).toLowerCase().trim()
   
-  // Basic email validation
   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
   if (!emailRegex.test(email)) {
     throw new Error('Invalid email format')
@@ -472,18 +439,26 @@ function sanitizeEmail(data: any, validation?: any): string {
   
   return email
 }
-
-/**
- * Strips all non-digit/non-`+` characters. Applies optional pattern validation.
- * @throws Error on pattern mismatch
- */
+// CIL[END chunk_id="schemautils_sanitizeemail_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizephone_1784020784" type="function" identity="sanitizePhone" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize phone number format"]
+// CIL[DOC-RESPONSIBILITY responsibility="Clean and validate phone numbers"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="cleaned phone" errors="format validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Removes non-digits, validates against pattern if provided" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizePhone(data: any, validation?: any): string {
   let phone = String(data).trim()
   
-  // Remove all non-digit characters except +
   phone = phone.replace(/[^\d+]/g, '')
   
-  // Apply pattern validation if specified
   if (validation?.pattern) {
     const regex = new RegExp(validation.pattern)
     if (!regex.test(phone)) {
@@ -493,18 +468,26 @@ function sanitizePhone(data: any, validation?: any): string {
   
   return phone
 }
-
-/**
- * Parses via `new URL()` and validates `http:` or `https:` protocol.
- * @throws Error on invalid URL or disallowed protocol
- */
+// CIL[END chunk_id="schemautils_sanitizephone_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeurl_1784020784" type="function" identity="sanitizeUrl" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and sanitize URLs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure URL format and protocol are valid"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="normalized URL" errors="invalid URL error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates URL format, restricts to HTTP/HTTPS protocols" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeUrl(data: any, validation?: any): string {
   let url = String(data).trim()
   
-  // Basic URL validation
   try {
     const urlObj = new URL(url)
-    // Only allow http/https protocols
     if (!['http:', 'https:'].includes(urlObj.protocol)) {
       throw new Error('Only HTTP and HTTPS URLs are allowed')
     }
@@ -513,12 +496,21 @@ function sanitizeUrl(data: any, validation?: any): string {
     throw new Error('Invalid URL format')
   }
 }
-
-/**
- * Coerces to Number, applies min/max constraints, rounds down to nearest
- * step if `validation.step` is set.
- * @throws Error on NaN or out-of-range
- */
+// CIL[END chunk_id="schemautils_sanitizeurl_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizenumber_1784020784" type="function" identity="sanitizeNumber" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and sanitize numeric values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure number validity and range constraints"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated number" errors="range/validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates NaN, checks min/max, applies step rounding" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeNumber(data: any, validation?: any): number {
   let num = Number(data)
   
@@ -526,7 +518,6 @@ function sanitizeNumber(data: any, validation?: any): number {
     throw new Error('Invalid number')
   }
   
-  // Apply min/max constraints
   if (validation?.min !== undefined && num < validation.min) {
     throw new Error(`Number must be at least ${validation.min}`)
   }
@@ -534,21 +525,30 @@ function sanitizeNumber(data: any, validation?: any): number {
     throw new Error(`Number must be at most ${validation.max}`)
   }
   
-  // Apply step constraint
   if (validation?.step) {
     const remainder = num % validation.step
     if (remainder !== 0) {
-      num = num - remainder // Round down to nearest step
+      num = num - remainder
     }
   }
   
   return num
 }
-
-/**
- * Coerces to Number, rounds to 2 decimal places, applies min/max.
- * @throws Error on NaN or out-of-range
- */
+// CIL[END chunk_id="schemautils_sanitizenumber_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeurrency_1784020784" type="function" identity="sanitizeCurrency" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize currency amounts with rounding"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate and round currency values"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="rounded currency" errors="range/validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Rounds to 2 decimal places, validates range constraints" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeCurrency(data: any, validation?: any): number {
   let num = Number(data)
   
@@ -556,10 +556,8 @@ function sanitizeCurrency(data: any, validation?: any): number {
     throw new Error('Invalid currency amount')
   }
   
-  // Round to 2 decimal places for currency
   num = Math.round(num * 100) / 100
   
-  // Apply min/max constraints
   if (validation?.min !== undefined && num < validation.min) {
     throw new Error(`Amount must be at least ${validation.min}`)
   }
@@ -569,30 +567,49 @@ function sanitizeCurrency(data: any, validation?: any): number {
   
   return num
 }
-
-/** Delegates to `sanitizeNumber`. @throws same as sanitizeNumber */
+// CIL[END chunk_id="schemautils_sanitizeurrency_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizerange_1784020784" type="function" identity="sanitizeRange" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize range values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delegate range sanitization to number sanitizer"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized number" errors="number validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple wrapper around sanitizeNumber function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeRange(data: any, validation?: any): number {
   return sanitizeNumber(data, validation)
 }
-
-/**
- * Parses via `new Date()`, returns ISO date string (`YYYY-MM-DD`). Applies
- * min/max date constraints.
- * @throws Error on invalid date or out-of-range
- */
+// CIL[END chunk_id="schemautils_sanitizerange_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizedate_1784020784" type="function" identity="sanitizeDate" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and format date strings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure valid date format and constraints"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ISO date string" errors="date validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Parses date, validates range, returns ISO format" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeDate(data: any, validation?: any): string {
   let dateStr = String(data).trim()
   
-  // Try to parse as ISO date
   const date = new Date(dateStr)
   if (isNaN(date.getTime())) {
     throw new Error('Invalid date format')
   }
   
-  // Return as ISO date string
   const isoDate = date.toISOString().split('T')[0]
   
-  // Apply min/max constraints
   if (validation?.min) {
     const minDate = new Date(validation.min)
     if (date < minDate) {
@@ -608,25 +625,31 @@ function sanitizeDate(data: any, validation?: any): string {
   
   return isoDate
 }
-
-/**
- * Parses via `new Date()`, returns full ISO datetime string. Applies
- * min/max datetime constraints.
- * @throws Error on invalid datetime or out-of-range
- */
+// CIL[END chunk_id="schemautils_sanitizedate_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizedatetime_1784020784" type="function" identity="sanitizeDatetime" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and format datetime strings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure valid datetime format and constraints"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ISO datetime string" errors="datetime validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Parses datetime, validates range, returns ISO format" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeDatetime(data: any, validation?: any): string {
   let dateStr = String(data).trim()
   
-  // Try to parse as ISO datetime
   const date = new Date(dateStr)
   if (isNaN(date.getTime())) {
     throw new Error('Invalid datetime format')
   }
   
-  // Return as ISO datetime string
   const isoDatetime = date.toISOString()
   
-  // Apply min/max constraints
   if (validation?.min) {
     const minDate = new Date(validation.min)
     if (date < minDate) {
@@ -642,12 +665,21 @@ function sanitizeDatetime(data: any, validation?: any): string {
   
   return isoDatetime
 }
-
-/**
- * Accepts `true/false` booleans or truthy/falsy strings
- * (`'true','1','yes','on'` / `'false','0','no','off'`).
- * @throws Error on unrecognised value
- */
+// CIL[END chunk_id="schemautils_sanitizedatetime_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeboolean_1784020784" type="function" identity="sanitizeBoolean" parent="none"]
+// CIL[DOC-MACRO purpose="Convert and sanitize boolean values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Normalize various boolean representations"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean value" errors="invalid boolean error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handles boolean, string, number representations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeBoolean(data: any, validation?: any): boolean {
   if (typeof data === 'boolean') {
     return data
@@ -662,22 +694,43 @@ function sanitizeBoolean(data: any, validation?: any): boolean {
   
   throw new Error('Invalid boolean value')
 }
-
-/** Delegates to `sanitizeBoolean`. */
+// CIL[END chunk_id="schemautils_sanitizeboolean_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizecheckbox_1784020784" type="function" identity="sanitizeCheckbox" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize checkbox boolean values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delegate checkbox sanitization to boolean sanitizer"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean value" errors="boolean validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple wrapper around sanitizeBoolean function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeCheckbox(data: any, validation?: any): boolean {
   return sanitizeBoolean(data, validation)
 }
-
-/**
- * Validates the value against `validation.options` (string[]). 
- * @throws Error('Invalid option selected') if value not in allowed list
- */
+// CIL[END chunk_id="schemautils_sanitizecheckbox_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeselect_1784020784" type="function" identity="sanitizeSelect" parent="none"]
+// CIL[DOC-MACRO purpose="Validate select field options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure selected value is in allowed options"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated option" errors="invalid option error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Trims value, checks against allowed options array" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeSelect(data: any, validation?: any): string {
   let value = String(data).trim()
   
-  // Validate against allowed options
   if (validation?.options) {
-    // Options are now just an array of strings
     const allowedValues = Array.isArray(validation.options) ? validation.options : []
     if (!allowedValues.includes(value)) {
       throw new Error('Invalid option selected')
@@ -686,12 +739,21 @@ function sanitizeSelect(data: any, validation?: any): string {
   
   return value
 }
-
-/**
- * Accepts array or comma-separated string. Deduplicates. Validates each
- * value against `validation.options`. Truncates to `validation.max`.
- * @throws Error on invalid option or non-array/string input
- */
+// CIL[END chunk_id="schemautils_sanitizeselect_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizemultiselect_1784020784" type="function" identity="sanitizeMultiselect" parent="none"]
+// CIL[DOC-MACRO purpose="Validate multiselect array values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle array or comma-separated multiselect data"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated array" errors="invalid option errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Converts to array, removes duplicates, validates options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeMultiselect(data: any, validation?: any): string[] {
   let values: string[]
   
@@ -703,12 +765,9 @@ function sanitizeMultiselect(data: any, validation?: any): string[] {
     throw new Error('Multiselect must be an array or comma-separated string')
   }
   
-  // Remove duplicates
   values = [...new Set(values)]
   
-  // Validate against allowed options
   if (validation?.options) {
-    // Options are now just an array of strings
     const allowedValues = Array.isArray(validation.options) ? validation.options : []
     for (const value of values) {
       if (!allowedValues.includes(value)) {
@@ -717,89 +776,129 @@ function sanitizeMultiselect(data: any, validation?: any): string[] {
     }
   }
   
-  // Apply max selection count
   if (validation?.max && values.length > validation.max) {
     values = values.slice(0, validation.max)
   }
   
   return values
 }
-
-/** Delegates to `sanitizeSelect`. */
+// CIL[END chunk_id="schemautils_sanitizemultiselect_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeradio_1784020784" type="function" identity="sanitizeRadio" parent="none"]
+// CIL[DOC-MACRO purpose="Validate radio button selections"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delegate radio sanitization to select sanitizer"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated option" errors="invalid option error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple wrapper around sanitizeSelect function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeRadio(data: any, validation?: any): string {
   return sanitizeSelect(data, validation)
 }
-
-/**
- * Validates `#RGB` or `#RRGGBB` hex format. Normalizes 3-digit to 6-digit.
- * Returns uppercase. @throws Error on invalid hex format
- */
+// CIL[END chunk_id="schemautils_sanitizeradio_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeolor_1784020784" type="function" identity="sanitizeColor" parent="none"]
+// CIL[DOC-MACRO purpose="Validate and format hex color codes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure proper hex color format"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="normalized hex color" errors="invalid color format error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates hex format, converts 3-digit to 6-digit, uppercases" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeColor(data: any, validation?: any): string {
   let color = String(data).trim()
   
-  // Validate hex color format
   const hexRegex = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/
   if (!hexRegex.test(color)) {
     throw new Error('Invalid color format. Use #RRGGBB or #RGB format')
   }
   
-  // Normalize to 6-digit hex
   if (color.length === 4) {
     color = '#' + color[1] + color[1] + color[2] + color[2] + color[3] + color[3]
   }
   
   return color.toUpperCase()
 }
-
-/**
- * Validates `data.name` presence, optional maxSize and allowedTypes.
- * Sanitizes filename to `[a-zA-Z0-9.-_]` characters only.
- * @throws Error on invalid file data, size, or type
- */
+// CIL[END chunk_id="schemautils_sanitizeolor_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeile_1784020784" type="function" identity="sanitizeFile" parent="none"]
+// CIL[DOC-MACRO purpose="Validate file objects and metadata"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure file data validity and constraints"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated file object" errors="file validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks object structure, size, type, sanitizes filename" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeFile(data: any, validation?: any): any {
-  // Basic file validation - would need more sophisticated handling in practice
   if (typeof data !== 'object' || !data.name) {
     throw new Error('Invalid file data')
   }
   
-  // Validate file size
   if (validation?.maxSize && data.size > validation.maxSize) {
     throw new Error(`File size exceeds maximum of ${validation.maxSize} bytes`)
   }
   
-  // Validate file type
   if (validation?.allowedTypes && !validation.allowedTypes.includes(data.type)) {
     throw new Error(`File type ${data.type} is not allowed`)
   }
   
-  // Sanitize filename
   data.name = data.name.replace(/[^a-zA-Z0-9.-]/g, '_')
   
   return data
 }
-
-/**
- * Delegates to `sanitizeFile`. Image dimension validation is a stub
- * (noted for future implementation).
- * @throws same as sanitizeFile
- */
+// CIL[END chunk_id="schemautils_sanitizeile_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeimage_1784020784" type="function" identity="sanitizeImage" parent="none"]
+// CIL[DOC-MACRO purpose="Validate image files with dimensions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Extend file sanitization for image-specific validation"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated image object" errors="image validation errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses file sanitizer, placeholder for dimension validation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeImage(data: any, validation?: any): any {
   const file = sanitizeFile(data, validation)
   
-  // Additional image-specific validation
   if (validation?.maxWidth || validation?.maxHeight) {
-    // Would need to actually load and check image dimensions
-    // For now, just pass through
   }
   
   return file
 }
-
-/**
- * Parses JSON strings. Rejects payloads containing `'function'`, `'eval'`,
- * or `'script'` strings as a basic code-injection guard.
- * @throws Error on invalid JSON or dangerous content
- */
+// CIL[END chunk_id="schemautils_sanitizeimage_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizejson_1784020784" type="function" identity="sanitizeJson" parent="none"]
+// CIL[DOC-MACRO purpose="Parse and sanitize JSON data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure JSON validity and remove dangerous content"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="parsed JSON object" errors="JSON parsing/security errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Parses string JSON, checks for dangerous keywords" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeJson(data: any, validation?: any): any {
   if (typeof data === 'string') {
     try {
@@ -809,7 +908,6 @@ function sanitizeJson(data: any, validation?: any): any {
     }
   }
   
-  // Basic security check - prevent code injection
   const jsonStr = JSON.stringify(data)
   if (jsonStr.includes('function') || jsonStr.includes('eval') || jsonStr.includes('script')) {
     throw new Error('JSON contains potentially dangerous content')
@@ -817,37 +915,51 @@ function sanitizeJson(data: any, validation?: any): any {
   
   return data
 }
-
-/**
- * Validates UUID v1–v5 format. DB-level FK constraints enforce existence.
- * @throws Error('Invalid reference format') on non-UUID input
- */
+// CIL[END chunk_id="schemautils_sanitizejson_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizereference_1784020784" type="function" identity="sanitizeReference" parent="none"]
+// CIL[DOC-MACRO purpose="Validate UUID reference format"]
+// CIL[DOC-RESPONSIBILITY responsibility="Ensure reference follows UUID pattern"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validated UUID string" errors="invalid UUID error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates against UUID regex pattern, trims whitespace" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeReference(data: any, validation?: any): string {
   let ref = String(data).trim()
   
-  // Validate UUID format
   const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
   if (!uuidRegex.test(ref)) {
     throw new Error('Invalid reference format')
   }
   
-  // Would need to check existence in referenced table
-  // For now, just validate format
-  
   return ref
 }
-
-/**
- * Sanitizes each string field of an address object via `sanitizeText`.
- * Passes non-string fields through unchanged.
- * @throws Error if input is not an object
- */
+// CIL[END chunk_id="schemautils_sanitizereference_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_sanitizeaddress_1784020784" type="function" identity="sanitizeAddress" parent="none"]
+// CIL[DOC-MACRO purpose="Sanitize address object data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Clean address fields and validate structure"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized address object" errors="invalid address error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validates object type, sanitizes string fields with text sanitizer" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function sanitizeAddress(data: any, validation?: any): any {
   if (typeof data !== 'object' || data === null) {
     throw new Error('Address must be an object')
   }
   
-  // Sanitize each address component
   const sanitized: any = {}
   for (const [key, value] of Object.entries(data)) {
     if (typeof value === 'string') {
@@ -859,15 +971,39 @@ function sanitizeAddress(data: any, validation?: any): any {
   
   return sanitized
 }
-
-// ─── FORMAT HELPERS ────────────────────────────────────────────────────────────
-
-/** Formats an object as a 2-space indented JSON string. */
+// CIL[END chunk_id="schemautils_sanitizeaddress_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatjson_1784020784" type="function" identity="formatJson" parent="none"]
+// CIL[DOC-MACRO purpose="Format JSON with pretty printing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert JSON to readable string format"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted JSON string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses JSON.stringify with 2-space indentation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatJson(data: any): string {
   return JSON.stringify(data, null, 2)
 }
-
-/** Formats an ISO date string as locale date ('January 15, 2024'). Returns raw data on invalid input. */
+// CIL[END chunk_id="schemautils_formatjson_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatdate_1784020784" type="function" identity="formatDate" parent="none"]
+// CIL[DOC-MACRO purpose="Format dates for display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert date to human-readable format"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted date string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses toLocaleDateString with long month format" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatDate(data: string): string {
   const date = new Date(data)
   if (isNaN(date.getTime())) {
@@ -880,8 +1016,21 @@ function formatDate(data: string): string {
     day: 'numeric'
   })
 }
-
-/** Formats an ISO datetime string as locale date+time ('January 15, 2024, 02:30 PM'). Returns raw on invalid. */
+// CIL[END chunk_id="schemautils_formatdate_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatdatetime_1784020784" type="function" identity="formatDatetime" parent="none"]
+// CIL[DOC-MACRO purpose="Format datetime for display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert datetime to human-readable format"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted datetime string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses toLocaleString with date and time components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatDatetime(data: string): string {
   const date = new Date(data)
   if (isNaN(date.getTime())) {
@@ -896,8 +1045,21 @@ function formatDatetime(data: string): string {
     minute: '2-digit'
   })
 }
-
-/** Formats a number as currency using Intl.NumberFormat. Defaults to USD. context.currency_code overrides. */
+// CIL[END chunk_id="schemautils_formatdatetime_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatcurrency_1784020784" type="function" identity="formatCurrency" parent="none"]
+// CIL[DOC-MACRO purpose="Format currency with locale"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format numbers as currency strings"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted currency string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses Intl.NumberFormat with currency style" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatCurrency(data: number, context?: any): string {
   const currency = context?.currency_code || 'USD'
   return new Intl.NumberFormat('en-US', {
@@ -905,10 +1067,22 @@ function formatCurrency(data: number, context?: any): string {
     currency: currency
   }).format(data)
 }
-
-/** Formats 10-digit US numbers as '(NXX) NXX-XXXX'. 11-digit with leading 1 as '+1 (NXX) NXX-XXXX'. Returns raw otherwise. */
+// CIL[END chunk_id="schemautils_formatcurrency_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatphone_1784020784" type="function" identity="formatPhone" parent="none"]
+// CIL[DOC-MACRO purpose="Format phone numbers for display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format phone numbers in standard US format"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted phone string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Formats 10-digit and 11-digit US phone numbers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatPhone(data: string): string {
-  // Basic US phone formatting
   const phone = data.replace(/\D/g, '')
   if (phone.length === 10) {
     return `(${phone.slice(0, 3)}) ${phone.slice(3, 6)}-${phone.slice(6)}`
@@ -918,20 +1092,57 @@ function formatPhone(data: string): string {
   
   return data
 }
-
-/** Pass-through — URLs are already display-ready. */
+// CIL[END chunk_id="schemautils_formatphone_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formaturl_1784020784" type="function" identity="formatUrl" parent="none"]
+// CIL[DOC-MACRO purpose="Format URLs for display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return URL data unchanged"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="URL string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Pass-through function, no formatting applied" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatUrl(data: string): string {
   return data
 }
-
-/** Pass-through — UUID returned as-is; display resolution requires a DB lookup (not done here). */
+// CIL[END chunk_id="schemautils_formaturl_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatreference_1784020784" type="function" identity="formatReference" parent="none"]
+// CIL[DOC-MACRO purpose="Format references for display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return reference data unchanged"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="reference string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Pass-through function, no formatting applied" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatReference(data: string, context?: any): string {
-  // Would need to look up the referenced entity
-  // For now, return the UUID
   return data
 }
-
-/** Joins address components (street, city, state, postal_code, country) into a comma-separated string. */
+// CIL[END chunk_id="schemautils_formatreference_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formataddress_1784020784" type="function" identity="formatAddress" parent="none"]
+// CIL[DOC-MACRO purpose="Format address objects as strings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert address object to comma-separated string"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted address string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Joins address components with commas, filters empty values" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatAddress(data: any): string {
   if (typeof data !== 'object' || data === null) {
     return String(data)
@@ -947,8 +1158,21 @@ function formatAddress(data: any): string {
   
   return parts.join(', ')
 }
-
-/** Joins a string array with ', '. Returns String(data) for non-arrays. */
+// CIL[END chunk_id="schemautils_formataddress_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatmultiselect_1784020784" type="function" identity="formatMultiselect" parent="none"]
+// CIL[DOC-MACRO purpose="Format multiselect arrays as strings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert array to comma-separated string"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="comma-separated string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Joins array elements with commas, handles non-arrays" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatMultiselect(data: string[]): string {
   if (!Array.isArray(data)) {
     return String(data)
@@ -956,8 +1180,21 @@ function formatMultiselect(data: string[]): string {
   
   return data.join(', ')
 }
-
-/** Returns 'Active'/'Inactive' when context.field is 'is_active'; otherwise 'Yes'/'No'. */
+// CIL[END chunk_id="schemautils_formatmultiselect_1784020784"]
+// CIL[BEGIN chunk_id="schemautils_formatboolean_1784020784" type="function" identity="formatBoolean" parent="none"]
+// CIL[DOC-MACRO purpose="Format booleans with contextual labels"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert boolean to human-readable labels"]
+// CIL[DOC-CONTEXT module="schema-utils" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted boolean string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses contextual labels for is_active, defaults to Yes/No" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function formatBoolean(data: boolean, context?: any): string {
   if (context?.field === 'is_active') {
     return data ? 'Active' : 'Inactive'
@@ -965,3 +1202,4 @@ function formatBoolean(data: boolean, context?: any): string {
   
   return data ? 'Yes' : 'No'
 }
+// CIL[END chunk_id="schemautils_formatboolean_1784020784"]